xai4tsc.xai.freqrise

FreqRISE — explaining time series by random frequency masking.

Perturbation-based attribution that masks coefficients in the frequency (real FFT) or time-frequency (STFT) domain and measures the effect on the model’s predicted class probability. Univariate series (C == 1) are the validated path; multivariate inputs are masked with a shared coefficient mask broadcast across channels.

Method

For an invertible spectral transform g and a random binary mask M over the coefficient grid, the masked signal fed to the classifier is x̂(M) = g⁻¹(g(x) ⊙ M). Averaging the masked predictions weighted by the masks gives the per-coefficient relevance for class c (Brüsch et al., Eq. 3):

R_c = 1 / (N · E[M]) · Σ_n ŷ_c(x̂(M_n)) · M_n

where N is the number of masks, ŷ_c is the softmax probability of the target class, and E[M] is the Bernoulli keep probability. Masks are sampled on a coarse num_cells grid and interpolated up to the coefficient grid to make them smooth.

Reference

T. Brüsch, K. K. Wickstrøm, M. N. Schmidt, T. S. Alstrøm, and R. Jenssen, “FreqRISE: Explaining time series using frequency masking,” in Proc. 6th Northern Lights Deep Learning Conf. (NLDL), PMLR vol. 265, 2025, pp. 16-31. https://proceedings.mlr.press/v265/brusch25a.html (arXiv:2406.13584)

This is an independent reimplementation written from the published algorithm (Eq. 3 and the masking procedure above); it does not derive from any third-party FreqRISE source code.

Attributes

logger

Classes

FreqRISEExplainer

FreqRISE: attribution via random masking in the frequency / TF domain.

Module Contents

xai4tsc.xai.freqrise.logger
class xai4tsc.xai.freqrise.FreqRISEExplainer(batch_size: int = 10, num_batches: int = 300, domain: str = 'stft', transform: xai4tsc.utils.fourier_transforms.DomainTransform | dict | None = None, num_cells: int = 50, probability_of_drop: float = 0.5, seed: int | None = None)

Bases: xai4tsc.xai.base.PerturbationExplainer

FreqRISE: attribution via random masking in the frequency / TF domain.

Parameters:

  • batch_size (int) – Number of masks evaluated per forward pass.

  • num_batches (int) – Number of mask batches; the total mask count is num_batches * batch_size.

  • domain (str) – "fft" (frequency, via real FFT) or "stft" (time-frequency).

  • transform (DomainTransform or dict, optional) – Transform used for domain="stft" (an STFTransform). Required for "stft"; ignored for "fft" (which uses torch.fft.rfft).

  • num_cells (int) – Resolution of the coarse mask grid before it is interpolated up to the coefficient grid. num_cells // 2 must be smaller than the smallest transform dimension.

  • probability_of_drop (float) – Bernoulli probability that a coarse cell is kept; equals E[M] in the relevance normalisation (default 0.5, as in the paper).

  • seed (int, optional) – Seed for reproducible mask sampling.

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.

batch_size = 10
num_batches = 300
domain = 'stft'
transform = None
num_cells = 50
probability_of_drop = 0.5
seed = None
explain(model: torch.nn.Module, exp: xai4tsc.xai._types.Explanation, device: str | torch.device, targets: list | None, **kwargs: object) → numpy.ndarray

Compute FreqRISE relevance for the samples in exp.