xai4tsc.utils.perturbation

Perturbation helpers: baseline_replacement and resolve_perturb_func.

A perturbation function follows the canonical signature (arr, indices, **kwargs) -> arr: it returns a copy of arr with the positions named by indices replaced by a baseline value. This mirrors the Quantus convention already used in xai4tsc.evaluation and lets perturbation-based explainers (e.g. TSHAP) treat “missingness” as a pluggable strategy.

Attributes

logger
BASELINES

Functions

baseline_replacement(→ numpy.ndarray)	Return a copy of arr with indices replaced by a baseline value.
resolve_perturb_func(→ collections.abc.Callable | None)	Resolve value to a perturbation callable.

Module Contents

xai4tsc.utils.perturbation.logger

xai4tsc.utils.perturbation.BASELINES: frozenset[str]

xai4tsc.utils.perturbation.baseline_replacement(arr: numpy.ndarray, indices: numpy.ndarray, baseline: str = 'centroid', reference: numpy.ndarray | None = None, prng: numpy.random.Generator | None = None, **kwargs: object) → numpy.ndarray

Return a copy of arr with indices replaced by a baseline value.

Parameters:

• arr (np.ndarray) – Single series of shape (C, T).

• indices (np.ndarray) – Time indices (along the last axis) to replace. An empty array returns an unmodified copy.

• baseline (str) –

  One of BASELINES:

  • "centroid" — replace with the matching columns of reference (a precomputed (C, T) background waveform, e.g. a class/dataset centroid). Falls back to "mean" if reference is None.

  • "black" — replace with zeros.

  • "white" — replace with ones.

  • "mean" — replace with each channel’s own temporal mean.

  • "random" — replace with Gaussian noise matched to each channel’s mean and standard deviation (uses prng when supplied).

• reference (np.ndarray, optional) – Background waveform of shape (C, T) used by "centroid".

• prng (np.random.Generator, optional) – Random generator for "random"; a default generator is used when None.

• **kwargs (object) – Ignored; accepted so callers can pass through extra perturbation options uniformly.

Returns:

A copy of arr with the requested replacement applied.

Return type:

np.ndarray

Raises:

ValueError – If baseline is not one of BASELINES.

xai4tsc.utils.perturbation.resolve_perturb_func(value: str | collections.abc.Callable) → collections.abc.Callable | None

Resolve value to a perturbation callable.

A callable is returned unchanged. A string is resolved by trying, in order: the names in BASELINES (bound to baseline_replacement()), the top-level quantus namespace, then a dotted import path (e.g. "my_module.my_perturb").

Parameters:

value (str or callable) – A callable, a baseline name, a quantus attribute name, or a dotted import path.

Returns:

The resolved callable, or None if a string could not be resolved.

Return type:

callable or None