xai4tsc.utils.plot ================== .. py:module:: xai4tsc.utils.plot .. autoapi-nested-parse:: Relevance visualisation: ``plot_relevance()`` and ``add_relevance()``. Attributes ---------- .. autoapisummary:: xai4tsc.utils.plot.logger Functions --------- .. autoapisummary:: xai4tsc.utils.plot.plot_relevance xai4tsc.utils.plot.add_relevance xai4tsc.utils.plot.plot_relevance_f xai4tsc.utils.plot.plot_relevance_tf xai4tsc.utils.plot.plot_perturbation_curve Module Contents --------------- .. py:data:: logger .. py:function:: 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 :func:`plot_relevance_f`, the frequency domain (magnitude spectrum vs frequency). :param signal: Signal data of shape ``(B, C, T)``, ``(C, T)``, or ``(T,)``. :type signal: np.ndarray :param relevance: Relevance values matching the shape of *signal*. Defaults to zeros. :type relevance: np.ndarray, optional :param rel_type: Visualisation style: ``"bubbles"`` (default), ``"background"``, ``"intensity"``, ``"graph"``, ``"bar"``, or ``None``. :type rel_type: str :param rel_type_kwargs: Extra keyword arguments forwarded to :func:`add_relevance`. :type rel_type_kwargs: dict :param linewidth: Line width for the signal plot. :type linewidth: float :param threshold: Relevance values below this absolute magnitude are suppressed. :type threshold: float :param cmap_boost: Value added (with sign) to non-zero relevances before colourmap mapping. :type cmap_boost: float :param title: Figure title. :type title: str, optional :param colorbar: Whether to add a colourbar to the figure. :type colorbar: bool :param graph_only: If ``True``, hide all axes decorations. :type graph_only: bool :param save_path: File path to save the figure. If ``None``, the figure is shown interactively. :type save_path: Path or str, optional :param xlabel: Label for the x-axis (``"Time [ms]"`` by default; ``"Frequency"`` for frequency-domain plots). :type xlabel: str :returns: Path to the last saved file, or ``None`` if not saved. :rtype: Path or None .. py:function:: 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. :param ax: The axes to draw on. :type ax: Axes :param signal: 1-D time series for this channel. :type signal: np.ndarray :param relevance: 1-D relevance values matching *signal*. :type relevance: np.ndarray :param rel_type: Visualisation style: ``"bubbles"`` (default), ``"background"``, ``"intensity"``, ``"graph"``, ``"bar"``, or ``None``. :type rel_type: str :param threshold: Relevance values below this absolute magnitude are suppressed. :type threshold: float :param cmap: Matplotlib colourmap used for relevance colouring. :type cmap: str or Colormap :param cmap_boost: Value added (with sign) to non-zero relevances before colour mapping. :type cmap_boost: float :param \*\*kwargs: Style overrides forwarded to the chosen visualisation type (e.g. ``bubble_size``, ``bar_height``, ``linewidth``). :returns: The modified axes. :rtype: Axes .. py:function:: 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 :func:`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. :param signal: Frequency coefficients of shape ``(B, C, F)`` (possibly complex). :type signal: np.ndarray :param relevance: Relevance values matching *signal* (possibly complex). :type relevance: np.ndarray, optional :param rel_type: Visualisation style forwarded to :func:`plot_relevance`. :type rel_type: str :param save_path: File path to save the figure; shown interactively if ``None``. :type save_path: Path, optional :param \*\*kwargs: Extra keyword arguments forwarded to :func:`plot_relevance`. :type \*\*kwargs: object :returns: Path to the last saved file, or ``None`` if not saved. :rtype: Path or None .. py:function:: 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 :func:`plot_relevance`; a spectrogram is 2-D and cannot use the 1-D :func:`add_relevance` overlay styles. :param signal: Spectrograms of shape ``(B, C, n_freq, n_time)`` (possibly complex). :type signal: np.ndarray :param relevance: Relevance of shape ``(B, C, n_freq, n_time)`` (possibly complex). :type relevance: np.ndarray :param save_path: 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``. :type save_path: Path, optional :param title: Figure title. :type title: str, optional :param signal_cmap: Colourmap for the spectrogram panel. :type signal_cmap: str :param relevance_cmap: Colourmap for the relevance panel. :type relevance_cmap: str :returns: Path to the last saved file, or ``None`` if not saved. :rtype: Path or None .. py:function:: 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)``. :param scores: Per-sample perturbation curves of shape ``(n_samples, n_steps)``. :type scores: np.ndarray :param labels: Class label per sample; when given, a mean curve is drawn per class. :type labels: np.ndarray, optional :param title: Figure title. :type title: str, optional :param save_path: File path to save the figure; shown interactively if ``None``. :type save_path: Path, optional :returns: The saved file path, or ``None`` if not saved. :rtype: Path or None