xai4tsc.xai.random_baseline

Random-baseline explainers in the frequency and time-frequency domains.

Sanity baselines for evaluation: they ignore the model and return uniform-random relevance shaped like the transformed input. A faithful explainer should beat these on perturbation metrics.

Classes

RandomFrequencyExplainer	Uniform-random baseline relevance in the frequency domain.
RandomTimeFreqExplainer	Uniform-random baseline relevance in the time-frequency domain.

Module Contents

class xai4tsc.xai.random_baseline.RandomFrequencyExplainer(transform: xai4tsc.utils.fourier_transforms.DomainTransform | dict | None = None, seed: int | None = DEFAULT_SEED)

Bases: xai4tsc.xai.base.PerturbationExplainer

Uniform-random baseline relevance in the frequency domain.

Parameters:

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

• seed (int or None) – Seed for the relevance draw, DEFAULT_SEED by default. A local generator is built from it on every explain() call, so repeated explanations of one input agree. None draws from OS entropy and is not reproducible.

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. Only read when explains_in_data_domain is False; a domain-changing explainer (frequency / time-frequency) overrides both. The realized domain of a produced explanation (Explanation.explanation_domain) must be a member of this set.

explains_in_data_domain: ClassVar[bool] = False

Whether the relevance comes out in the same domain as the input.

True for a plain attributor: it assigns relevance to the input features it was given, so the explanation is in the model-native domain - the time domain for a model trained on raw series, the frequency domain for one trained on spectra (xai4tsc.Explanation.data_domain). Explainers that deliberately change domain set this to False and name their output in explanation_domains instead.

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

Data domains this explainer can consume; empty means any.

A domain-changing explainer transforms its input, so it declares the domain it can transform from. Pointing one at data already in its target domain would transform it a second time, which is why that pairing is refused.

transform

seed = 3735928559

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

Return uniform-random relevance shaped like the frequency transform.

class xai4tsc.xai.random_baseline.RandomTimeFreqExplainer(transform: xai4tsc.utils.fourier_transforms.DomainTransform | dict | None = None, seed: int | None = DEFAULT_SEED)

Bases: xai4tsc.xai.base.PerturbationExplainer

Uniform-random baseline relevance in the time-frequency domain.

Parameters:

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

• seed (int or None) – Seed for the relevance draw, DEFAULT_SEED by default. A local generator is built from it on every explain() call, so repeated explanations of one input agree. None draws from OS entropy and is not reproducible.

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. Only read when explains_in_data_domain is False; a domain-changing explainer (frequency / time-frequency) overrides both. The realized domain of a produced explanation (Explanation.explanation_domain) must be a member of this set.

explains_in_data_domain: ClassVar[bool] = False

Whether the relevance comes out in the same domain as the input.

True for a plain attributor: it assigns relevance to the input features it was given, so the explanation is in the model-native domain - the time domain for a model trained on raw series, the frequency domain for one trained on spectra (xai4tsc.Explanation.data_domain). Explainers that deliberately change domain set this to False and name their output in explanation_domains instead.

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

Data domains this explainer can consume; empty means any.

A domain-changing explainer transforms its input, so it declares the domain it can transform from. Pointing one at data already in its target domain would transform it a second time, which is why that pairing is refused.

transform = None

seed = 3735928559

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

Return uniform-random relevance shaped like the time-frequency transform.