xai4tsc.xai.explain

generate_explanation() entry point, EXPLAINERS registry, plot helpers.

Attributes

logger

EXPLAINERS

Functions

generate_explanation(...)

Generate an explanation for the given indices or for random samples.

plot_exp(→ None)

Render and save relevance plots for every sample in exp.

build_explainer(→ xai4tsc.xai.base.ExplainerBase)

Instantiate a registered explainer, filtering params to its __init__.

register_explainer(→ None)

Register a custom ExplainerBase subclass.

Module Contents

xai4tsc.xai.explain.logger
xai4tsc.xai.explain.generate_explanation(method: str, model: xai4tsc.models.base.ModelBase, data: numpy.ndarray, labels: numpy.ndarray | None = None, targets: str = 'predicted', params: dict | None = None, encoder: sklearn.preprocessing.OneHotEncoder | sklearn.preprocessing.LabelEncoder | sklearn.preprocessing.OrdinalEncoder | None = None, indices: list | None = None, samples: int = 5, prng: numpy.random.Generator | None = None, device: str = 'cpu', save_path: pathlib.Path | str | None = None, visualization_type: list | None = None, data_domain: str | xai4tsc.xai._types.Domain = Domain.TIME) → xai4tsc.xai._types.Explanation | None

Generate an explanation for the given indices or for random samples.

Set indices to an empty list or None to choose random samples.

Parameters:

  • method (str) – Explanation method to use. Have a look at the support.yaml file.

  • model (ModelBase) – Model to explain.

  • data (np.ndarray) – Dataset to generate an explanation for.

  • labels (np.ndarray, optional) – Labels of the dataset, by default None

  • targets (str, optional) – Which class to explain: "predicted" (default), "label" (ground truth), or "all" (one explanation per class).

  • params (dict, optional) – Parameters for the explanation method, by default None

  • encoder (OneHotEncoder | LabelEncoder | OrdinalEncoder, optional) – Encoder used to encode the labels, by default None

  • indices (list, optional) – Indices of samples to explain, by default None

  • samples (int, optional) – Number of random samples to explain if no indices supplied, by default 5

  • prng (np.random.Generator, optional) – Generator used to pick random sample indices. When None a generator seeded with DEFAULT_SEED is used, so the selection is reproducible; the runner passes a per-dataset generator so every explainer scores the same samples.

  • device (str, optional) – Device to calculate on, by default "cpu".

  • save_path (Path | str, optional) – Path to save the explanation visualisation to, by default None

  • visualization_type (list, optional) – Plot styles to render when saving, by default ["points"].

  • data_domain (str or Domain, optional) – Signal domain data is expressed in, i.e. the domain the model consumes ("time" by default; see xai4tsc.data.DatasetBase.data_domain). A plain attributor explains in this domain; a domain-changing explainer is refused on data it cannot transform from.

Returns:

An object of the Explanation dataclass.

Return type:

Explanation

xai4tsc.xai.explain.plot_exp(exp: xai4tsc.xai._types.Explanation, norm: bool = True, save_path: pathlib.Path | str | None = None, visualization_type: list | None = None) → None

Render and save relevance plots for every sample in exp.

Plots are written flat under save_path, one file per sample (and, for targets="all" explanations, per class), named relevance_index_<idx>_class_<label>... so samples sharing a directory do not overwrite one another. The renderer is chosen by exp.explanation_domain: time-domain explanations use the 1-D plot_relevance() overlay styles; frequency and time-frequency explanations use plot_relevance_f() and plot_relevance_tf() respectively. Frequency and time-frequency explanations plot against the transformed signal, derived on demand via exp.transform.

Parameters:

  • exp (Explanation) – The explanation to render. Multi-target (“all”) explanations are detected via is_multi_target() (domain-aware), so a single-target time-frequency explanation is not mistaken for a multi-target one.

  • norm (bool, optional) – Whether to normalize explanation values, by default True.

  • save_path (Path | str | None, optional) – Directory to save the plots to, by default None.

  • visualization_type (list | None, optional) – Overlay styles for time / frequency plots: any of "points" (default), "background", "intensity", "graph", or "bar". Ignored for time-frequency, which renders a single fixed heatmap view.

Raises:

ValueError – If exp is a frequency / time-frequency explanation but carries no exp.transform to derive the transformed signal from.

xai4tsc.xai.explain.EXPLAINERS
xai4tsc.xai.explain.build_explainer(method: str, params: dict | None) → xai4tsc.xai.base.ExplainerBase

Instantiate a registered explainer, filtering params to its __init__.

Shared by _get_explanation() and by wrapper explainers (WrapperExplainer) that need to build their wrapped base method the same way the runner does.

Parameters:

  • method (str) – Explainer name; looked up case-insensitively in EXPLAINERS.

  • params (dict or None) – Parameters to pass to the explainer’s __init__. Keys not matching the constructor signature are dropped via dict_to_args(). If the class defines no __init__, no parameters are passed.

Returns:

A ready-to-use explainer instance.

Return type:

ExplainerBase

Raises:

NotImplementedError – If method is not registered in EXPLAINERS.

xai4tsc.xai.explain.register_explainer(name: str, explainer_class: type) → None

Register a custom ExplainerBase subclass.

After registration the explainer is available by name in experiment configs and via _get_explanation().

Parameters:

  • name – Key used to look up the explainer (case-insensitive).

  • explainer_class – A concrete subclass of ExplainerBase (or one of its mid-level subclasses).

Raises:

TypeError – If explainer_class is not an ExplainerBase subclass.