How to add a new analysis

Adding a New Analysis

This document describes step by step how to add a new analysis method to the project, in a way that is compatible with the existing architecture, configurable, and optionally visualizable.

The goals are to guarantee:

• objective measurements only (no automatic interpretation),
• full integration into the pipeline,
• results usable by the visualization layer without tight coupling.

---

Pipeline Overview

YAML Configuration
   ↓
Registry (identifier → function)
   ↓
Runner (orchestration)
   ↓
Analysis Method
   ↓
AnalysisResult
   ↓
JSON Export (+ optional visualization)

---

Involved Files

When adding a new analysis, the following files may be involved:

• audio_toolkit/analyses/<category>.py → method implementation
• audio_toolkit/engine/registry.py → registry API (do not modify)
• audio_toolkit/engine/context.py → input data structure
• audio_toolkit/engine/results.py → result structure
• audio_toolkit/engine/runner.py → execution + visualization trigger
• audio_toolkit/visualization/plots.py → graph generation (if needed)

---

Step 1 — Choose a Category

The category determines:

• the Python file to modify,
• the key used in the YAML configuration.

Existing categories:

• temporal
• spectral
• time_frequency
• modulation
• information
• inter_channel
• steganography
• meta_analysis

Implement the method in the corresponding file.

---

Step 2 — Implement the Analysis Function

Expected Signature

def my_analysis(context, params) -> AnalysisResult:
    ...

• context must be treated as immutable
• params comes from the configuration (merged defaults + overrides)

Best Practices

• Explicitly validate input parameters
• Process all channels present in context.audio_data
• Never call another analysis method
• Never produce conclusions or automatic labels

---

Step 3 — Build the AnalysisResult

Available Fields

• method: method identifier
• measurements: raw, serializable data
• metrics: derived scalars (optional)
• anomaly_score: optional numeric indicator
• visualization_data: plot-ready data (optional)

Important Rules

• Critical information must always be stored in measurements
• visualization_data may be dropped during export
• Avoid verdict-style fields (e.g. detected / encoded)

---

Step 4 — Add Visualization Data (Optional)

Principle

visualization_data must contain only ready-to-plot structures:

• axes
• series
• matrices

No computation should be redone in the visualization layer.

Example Structures

Time Series

visualization_data[channel] = {
    "time": t,
    "value": y
}

Spectrum

visualization_data[channel] = {
    "frequencies": freqs,
    "magnitudes": mags
}

Time-Frequency Representation

visualization_data[channel] = {
    "times": times,
    "frequencies": freqs,
    "matrix": tf
}

---

Step 5 — Register the Analysis Method

Each analysis method must be registered to be executable.

Registration is done inside the analysis module itself, by calling register_method(...) at import time:

register_method(
    identifier="my_analysis",
    category="information",
    function=my_analysis,
    default_params={...}
)

Rules:

• identifier must be unique and is used in the YAML configuration.
• category must match the configuration section.
• function must return an AnalysisResult.
• default_params must be serializable.

Notes:

• Do not edit engine/registry.py.
• Registration relies on module import side effects; the runner imports the analyses package at startup.

Without registration, the method cannot be executed.

---

Step 6 — Enable via Configuration

analyses:
  <category>:
    enabled: true
    methods:
      - name: "my_analysis"
        params:
          ...

---

Step 7 — Verify Full Integration

Checklist:

• the method runs without visualization
• the method runs with visualization.enabled = true
• results are present in results.json
• no critical information is lost

---

Summary

Element	Location
Computation	analyses/*.py
Activation	registry + YAML
Data	AnalysisResult
Plots	plots.py via the runner

---

This guide defines the contract that every new analysis must respect.