xai4tsc.xai.explanation_domains

Explanation-space wrappers: lift a time-domain attributor into freq / TF space.

Wraps any base feature-attribution method (e.g. Integrated Gradients, Guided Backpropagation) and maps its time-domain relevance into the frequency or time-frequency domain via a DomainTransform.

Reference

S. Rezaei and X. Liu, “Explanation Space: A New Perspective into Time Series Interpretability.” arXiv, Sep. 2024. doi: 10.48550/ARXIV.2409.01354.

Classes

FrequencyExplainer	Map a base method's relevance into the frequency domain.
TimeFrequencyExplainer	Map a base method's relevance into the time-frequency domain.

Module Contents

class xai4tsc.xai.explanation_domains.FrequencyExplainer(base: dict | str = 'integrated_gradients', transform: xai4tsc.utils.fourier_transforms.DomainTransform | dict | None = None)

Bases: xai4tsc.xai.base.WrapperExplainer

Map a base method’s relevance into the frequency domain.

Runs the wrapped time-domain attributor, then transforms its relevance with a Fourier transform. The base is configured exactly as if invoked by name.

Parameters:

• base (dict or str) – The base explainer to wrap (method name or config dict). Defaults to "integrated_gradients".

• transform (DomainTransform or dict, optional) – Transform to the frequency domain. Defaults to a full FourierTransform.

data_applicability: ClassVar[set[xai4tsc.xai._types.DataType]]

Data domains this explainer applies to. A set of DataType members — {DataType.AGNOSTIC} (any input) or {DataType.TIME_SERIES}.

explanation_domains: ClassVar[set[xai4tsc.xai._types.Domain]]

Signal domains this explainer can produce explanations in. A set of Domain members (capability declaration, mirroring data_applicability). Checked statically by the runner’s config sanity check before any explainer is instantiated. Defaults to {Domain.TIME}; frequency/time-frequency explainers override it. The realized domain of a produced explanation (Explanation.explanation_domain) must be a member of this set.

transform

explain(model: torch.nn.Module, exp: xai4tsc.xai._types.Explanation, device: str | torch.device, targets: list | None, **kwargs: object) → numpy.ndarray

Run the base method, then map its relevance to the frequency domain.

class xai4tsc.xai.explanation_domains.TimeFrequencyExplainer(base: dict | str = 'guided_backpropagation', transform: xai4tsc.utils.fourier_transforms.DomainTransform | dict | None = None)

Bases: xai4tsc.xai.base.WrapperExplainer

Map a base method’s relevance into the time-frequency domain.

Runs the wrapped time-domain attributor, then transforms its relevance with a short-time Fourier transform.

Parameters:

• base (dict or str) – The base explainer to wrap (method name or config dict). Defaults to "guided_backpropagation".

• transform (DomainTransform or dict) – Transform to the time-frequency domain (e.g. an STFTransform). Required — there is no sensible default window configuration.

data_applicability: ClassVar[set[xai4tsc.xai._types.DataType]]

Data domains this explainer applies to. A set of DataType members — {DataType.AGNOSTIC} (any input) or {DataType.TIME_SERIES}.

explanation_domains: ClassVar[set[xai4tsc.xai._types.Domain]]

Signal domains this explainer can produce explanations in. A set of Domain members (capability declaration, mirroring data_applicability). Checked statically by the runner’s config sanity check before any explainer is instantiated. Defaults to {Domain.TIME}; frequency/time-frequency explainers override it. The realized domain of a produced explanation (Explanation.explanation_domain) must be a member of this set.

transform = None

explain(model: torch.nn.Module, exp: xai4tsc.xai._types.Explanation, device: str | torch.device, targets: list | None, **kwargs: object) → numpy.ndarray

Run the base method, then map its relevance to time-frequency space.