xai4tsc.evaluation.frequency_evaluate

Frequency-domain perturbation metric (frequency pixel-flipping).

Ranks the explanation’s frequency coefficients by importance, progressively replaces the most-important ones with a baseline, inverts back to the time domain, and tracks the model’s predicted probability for the target class. A faithful explanation makes the prediction drop quickly.

Implemented as FrequencyEvaluator, an EvaluatorBase subclass that reads the domain transform from the explanation. The shared perturbation-curve logic lives in PerturbationEvaluator.

Classes

PerturbationEvaluator

Shared base for domain perturbation-curve metrics (frequency / time-frequency).

FrequencyEvaluator

Frequency-domain perturbation curve (frequency pixel-flipping).

Module Contents

class xai4tsc.evaluation.frequency_evaluate.PerturbationEvaluator(transform: xai4tsc.utils.fourier_transforms.DomainTransform | None = None, features_in_step: int | None = None, perturb_baseline: float = 0.0, return_aoc_per_sample: bool = False)

Bases: xai4tsc.evaluation.base.EvaluatorBase, abc.ABC

Shared base for domain perturbation-curve metrics (frequency / time-frequency).

Subclasses declare required_domains, a default features_in_step (_default_features_in_step), and supply a _perturb_func() and a _animation_cls(). The domain transform is read from the explanation at evaluation time, or taken from the constructor for animate().

Parameters:

  • transform (DomainTransform, optional) – Domain transform. Usually left None for scoring (read from the explanation) and set explicitly only for animate().

  • features_in_step (int, optional) – Number of coefficients perturbed per step; falls back to _default_features_in_step when None.

  • perturb_baseline (float) – Value the perturbed coefficients are set to (0.0 removes them).

  • return_aoc_per_sample (bool) – Return per-sample AOC instead of the raw perturbation curves.

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

Data domains this evaluator applies to (Quantus-style; defaults to agnostic).

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

Explanation domains this evaluator requires; empty means any domain.

transform = None
features_in_step = 1
perturb_baseline = 0.0
return_aoc_per_sample = False
evaluate(model: torch.nn.Module, explanation: xai4tsc.xai._types.Explanation, data: numpy.ndarray, labels: numpy.ndarray, device: str = 'cpu', **kwargs: object) → list

Compute the domain perturbation curve (or AOC) for the batch.

The domain transform is taken from the constructor if set, else from the explanation; complex attributions are reduced to magnitude first.

animate(model: object, x_batch: numpy.ndarray, y_batch: numpy.ndarray, a_batch: numpy.ndarray, save_path: pathlib.Path | str, sample: int = 0, fps: int = 20) → pathlib.Path

Render one sample’s perturbation process as a GIF (does not affect scoring).

Parameters:

  • model – A model exposing predict(x) -> (classes, probs).

  • x_batch (np.ndarray) – Time-domain inputs, target classes, and attributions (complex attributions are reduced to magnitude).

  • y_batch (np.ndarray) – Time-domain inputs, target classes, and attributions (complex attributions are reduced to magnitude).

  • a_batch (np.ndarray) – Time-domain inputs, target classes, and attributions (complex attributions are reduced to magnitude).

  • save_path (Path or str) – Output GIF path (a .gif suffix is enforced).

  • sample (int) – Index of the sample to animate.

  • fps (int) – Frames per second.

Returns:

The written GIF path.

Return type:

Path

class xai4tsc.evaluation.frequency_evaluate.FrequencyEvaluator(transform: xai4tsc.utils.fourier_transforms.DomainTransform | None = None, features_in_step: int | None = None, perturb_baseline: float = 0.0, return_aoc_per_sample: bool = False)

Bases: PerturbationEvaluator

Frequency-domain perturbation curve (frequency pixel-flipping).

Ranks the explanation’s frequency coefficients by importance, progressively replaces the most-important ones with a baseline, inverts back to the time domain, and tracks the model’s predicted probability for the target class. See PerturbationEvaluator for the constructor parameters.

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

Explanation domains this evaluator requires; empty means any domain.