Skip to content

How to add a new visualization

Jump to bottom
Maxnor899 edited this page Jan 18, 2026 · 4 revisions

Adding Visualizations (Code-Accurate)

This document explains how to add descriptive visualizations to the project, without modifying analyses to introduce interpretation.

Visualization is:

  • optional,
  • non-intrusive,
  • strictly based on already computed data.

Fundamental Principle

Analyses compute data.
Visualizations represent it.

No analytical computation must be moved to the graphical layer.

Involved Files

  • audio_toolkit/visualization/plots.py → implementation of all plots (matplotlib lives here)
  • audio_toolkit/engine/runner.py → visualization orchestration / dispatch
  • audio_toolkit/engine/results.py → data transport (AnalysisResult)

All plot implementations must be done exclusively in plots.py.

Where Visualization Data Comes From (Current Implementation)

In the current code, the runner triggers plots using AnalysisResult.visualization_data.

If required data does not exist, add it in the analysis, not in the plot (and store critical values in measurements as well, because visualization_data may be dropped during JSON export).

Note (code-accurate): plotting directly from measurements is a design possibility, but it is not part of the current automatic plotting path unless you also update the runner to read it.

Step 1 — Identify the Plot Type

Common plot types:

  • time series
  • frequency spectrum
  • time-frequency representation
  • histogram
  • matrix / heatmap

Each type corresponds to a clear data pattern that should already be computed by the analysis.

Step 2 — Add a Plot Function in plots.py

Create a function plot_<name> that:

  • receives only plot-ready data,
  • creates the matplotlib figure,
  • saves it using the existing helper(s),
  • explicitly closes the figure (plt.close(fig)).

No dependency on the runner or the analysis layer.

Step 3 — Expose the Plot via Visualizer

In plots.py, add the corresponding method to the Visualizer class.

Wrapper responsibilities:

  • inject dpi, formats, figsize from configuration,
  • keep figure saving / naming consistent,
  • simplify runner code.

Step 4 — Trigger Visualization in the Runner (Code-Accurate)

In audio_toolkit/engine/runner.py, visualizations are triggered by a method-identifier dispatch.

To enable automatic plotting for a new analysis method:

  1. Ensure the analysis returns an AnalysisResult with visualization_data populated (plot-ready).
  2. In the runner’s visualization dispatch (currently implemented as if method == "..." cases), add a new branch for your method identifier.
  3. In that branch, call the appropriate Visualizer method and pass the visualization_data (and any needed config-derived values already available to the runner).

The runner performs no DSP computation; it only selects the right plot function and passes precomputed data.

Channel Handling

  • If visualization_data is channel-indexed:
    • iterate over channels in the runner (or inside the Visualizer wrapper, if that’s the chosen convention for that plot)
  • If data is global:
    • generate a single plot

The choice of channel-indexed vs global must be made in the analysis (i.e., by how it structures visualization_data), not by recomputing or reshaping data in the plot function.

Generated File Organization

Best practices:

  • one folder per method
  • one file per channel and per plot type

Examples:

  • spectral/fft_global_left.png
  • time_frequency/stft_right.png

Graph Design Rules

  • descriptive titles only
  • explicitly labeled axes
  • no annotations suggesting conclusions
  • no hard-coded interpretative thresholds

Validation Checklist (Code-Accurate)

  • when visualization.enabled = true, your plots are generated for the new method
  • when visualization.enabled = false, the pipeline runs normally (no plot code is executed)
  • no data is modified during plotting (read-only usage)
  • all figures are closed (plt.close)
  • matplotlib code lives only in plots.py

Summary

Action File
Add plot function + wrapper plots.py
Ensure plot-ready data exists analysis → AnalysisResult.visualization_data
Enable automatic plotting for a method runner.py (dispatch branch)

This guide defines the code-accurate way to add visualizations to the project.

Clone this wiki locally