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) → 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) – Random number generator to sample random indices, by default None

  • 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 ["bubbles"].

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.

One sub-directory per sample index is created under save_path. 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. For multi-target (time-domain) explanations one plot per class is written.

Parameters:

  • exp (Explanation) – _description_

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

  • save_path (Path | str | None, optional) – Path to save explanations too, by default None

  • visualization_type (list | None, optional) – Type of visualization can be any of “bubbles”` (default), "background", "intensity", "graph", or "bar", by default None

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.