xai4tsc.utils.plot

Relevance visualisation: plot_relevance() and add_relevance().

Attributes

logger

Functions

plot_relevance(→ pathlib.Path | None)

Plot a 1-D signal with an overlaid relevance map.

add_relevance(→ matplotlib.axes.Axes)

Overlay relevance onto a single Matplotlib axes.

plot_relevance_f(→ pathlib.Path | None)

Plot a frequency-domain explanation by reusing plot_relevance().

plot_relevance_tf(→ pathlib.Path | None)

Plot a time-frequency explanation as side-by-side spectrogram heatmaps.

plot_perturbation_curve(→ pathlib.Path | None)

Plot a perturbation (pixel-flipping) curve from per-sample metric scores.

Module Contents

xai4tsc.utils.plot.logger
xai4tsc.utils.plot.plot_relevance(signal: numpy.ndarray, relevance: numpy.ndarray | None = None, rel_type: str = 'bubbles', rel_type_kwargs: dict | None = None, linewidth: float = 1.4, threshold: float = 0.0, cmap_boost: float = 0.0, title: str | None = None, colorbar: bool = False, graph_only: bool = False, save_path: pathlib.Path | str | None = None, xlabel: str = 'Time [ms]') → pathlib.Path | None

Plot a 1-D signal with an overlaid relevance map.

Works for any 1-D domain: the time domain (signal vs time) and, via plot_relevance_f(), the frequency domain (magnitude spectrum vs frequency).

Parameters:

  • signal (np.ndarray) – Signal data of shape (B, C, T), (C, T), or (T,).

  • relevance (np.ndarray, optional) – Relevance values matching the shape of signal. Defaults to zeros.

  • rel_type (str) – Visualisation style: "bubbles" (default), "background", "intensity", "graph", "bar", or None.

  • rel_type_kwargs (dict) – Extra keyword arguments forwarded to add_relevance().

  • linewidth (float) – Line width for the signal plot.

  • threshold (float) – Relevance values below this absolute magnitude are suppressed.

  • cmap_boost (float) – Value added (with sign) to non-zero relevances before colourmap mapping.

  • title (str, optional) – Figure title.

  • colorbar (bool) – Whether to add a colourbar to the figure.

  • graph_only (bool) – If True, hide all axes decorations.

  • save_path (Path or str, optional) – File path to save the figure. If None, the figure is shown interactively.

  • xlabel (str) – Label for the x-axis ("Time [ms]" by default; "Frequency" for frequency-domain plots).

Returns:

Path to the last saved file, or None if not saved.

Return type:

Path or None

xai4tsc.utils.plot.add_relevance(ax: matplotlib.axes.Axes, signal: numpy.ndarray, relevance: numpy.ndarray, rel_type: str = 'bubble', threshold: float = 0.0, cmap: str = 'bwr', cmap_boost: float = 0.0, **kwargs: object) → matplotlib.axes.Axes

Overlay relevance onto a single Matplotlib axes.

Parameters:

  • ax (Axes) – The axes to draw on.

  • signal (np.ndarray) – 1-D time series for this channel.

  • relevance (np.ndarray) – 1-D relevance values matching signal.

  • rel_type (str) – Visualisation style: "bubbles" (default), "background", "intensity", "graph", "bar", or None.

  • threshold (float) – Relevance values below this absolute magnitude are suppressed.

  • cmap (str or Colormap) – Matplotlib colourmap used for relevance colouring.

  • cmap_boost (float) – Value added (with sign) to non-zero relevances before colour mapping.

  • **kwargs – Style overrides forwarded to the chosen visualisation type (e.g. bubble_size, bar_height, linewidth).

Returns:

The modified axes.

Return type:

Axes

xai4tsc.utils.plot.plot_relevance_f(signal: numpy.ndarray, relevance: numpy.ndarray | None = None, rel_type: str = 'bubbles', save_path: pathlib.Path | None = None, **kwargs: object) → pathlib.Path | None

Plot a frequency-domain explanation by reusing plot_relevance().

The magnitude spectrum is drawn as the 1-D “signal” and the relevance is overlaid in the usual styles. Complex inputs (e.g. an FFT spectrum, or a complex relevance from an explanation-space wrapper) are reduced to magnitude so the shared 1-D machinery applies.

Parameters:

  • signal (np.ndarray) – Frequency coefficients of shape (B, C, F) (possibly complex).

  • relevance (np.ndarray, optional) – Relevance values matching signal (possibly complex).

  • rel_type (str) – Visualisation style forwarded to plot_relevance().

  • save_path (Path, optional) – File path to save the figure; shown interactively if None.

  • **kwargs (object) – Extra keyword arguments forwarded to plot_relevance().

Returns:

Path to the last saved file, or None if not saved.

Return type:

Path or None

xai4tsc.utils.plot.plot_relevance_tf(signal: numpy.ndarray, relevance: numpy.ndarray, save_path: pathlib.Path | None = None, title: str | None = None, signal_cmap: str = 'viridis', relevance_cmap: str = 'Reds') → pathlib.Path | None

Plot a time-frequency explanation as side-by-side spectrogram heatmaps.

For each sample and channel, draws two panels — the magnitude spectrogram and the relevance — as 2-D imshow heatmaps (time on x, frequency on y). This is the time-frequency counterpart of plot_relevance(); a spectrogram is 2-D and cannot use the 1-D add_relevance() overlay styles.

Parameters:

  • signal (np.ndarray) – Spectrograms of shape (B, C, n_freq, n_time) (possibly complex).

  • relevance (np.ndarray) – Relevance of shape (B, C, n_freq, n_time) (possibly complex).

  • save_path (Path, optional) – File path to save the figure. With more than one sample a directory is created and per-sample files are written. Shown interactively if None.

  • title (str, optional) – Figure title.

  • signal_cmap (str) – Colourmap for the spectrogram panel.

  • relevance_cmap (str) – Colourmap for the relevance panel.

Returns:

Path to the last saved file, or None if not saved.

Return type:

Path or None

xai4tsc.utils.plot.plot_perturbation_curve(scores: numpy.ndarray, labels: numpy.ndarray | None = None, title: str | None = None, save_path: pathlib.Path | None = None) → pathlib.Path | None

Plot a perturbation (pixel-flipping) curve from per-sample metric scores.

Draws the mean predicted probability against the fraction of coefficients perturbed: one line per class when labels are given, plus the overall mean. A faithful explanation makes the curve drop quickly. Pairs with the frequency / time-frequency perturbation metrics, which return per-sample curves of shape (n_samples, n_steps).

Parameters:

  • scores (np.ndarray) – Per-sample perturbation curves of shape (n_samples, n_steps).

  • labels (np.ndarray, optional) – Class label per sample; when given, a mean curve is drawn per class.

  • title (str, optional) – Figure title.

  • save_path (Path, optional) – File path to save the figure; shown interactively if None.

Returns:

The saved file path, or None if not saved.

Return type:

Path or None