xai4tsc.xai.feature_attribution

Captum-backed feature attribution explainers (IG, DeepLIFT, Occlusion, …).

Also hosts TSHAPExplainer, a pure-NumPy perturbation method (exact 2-player Shapley over time windows) that only queries model.predict.

Attributes

logger

Classes

`IntegratedGradientsExplainer`	Feature attribution via Integrated Gradients (Captum).
`DeepLiftExplainer`	Feature attribution via DeepLIFT (Captum).
`DeconvolutionExplainer`	Feature attribution via Deconvolution (Captum).
`GuidedBackpropagationExplainer`	Feature attribution via Guided Backpropagation (Captum).
`OcclusionExplainer`	Feature attribution via Occlusion (Captum).
`TSHAPExplainer`	Feature attribution via TSHAP — exact 2-player Shapley over time windows.

Module Contents

xai4tsc.xai.feature_attribution.logger

class xai4tsc.xai.feature_attribution.IntegratedGradientsExplainer(multiply_by_inputs: bool = True, n_steps: int = 50, integration_method: str = 'gausslegendre', baselines: int = 0, internal_batch_size: int | None = None)

Bases: xai4tsc.xai.base.GradientExplainer

Feature attribution via Integrated Gradients (Captum).

Parameters:

multiply_by_inputs (bool) – Multiply attributions by (input - baseline). Matches the standard IG formulation.
n_steps (int) – Number of steps along the integration path. Higher values give more accurate approximations at the cost of compute.
integration_method (str) – Quadrature rule for approximating the integral. One of "gausslegendre" (default), "riemann_trapezoid", "riemann_middle", "riemann_right", "riemann_left".
baselines (int or float) – Reference input value used as the integration baseline.
internal_batch_size (int or None) – Split the integration steps into sub-batches of this size to reduce memory usage. None processes all steps at once.

data_applicability: ClassVar[set[xai4tsc.xai._types.DataType]]: Gradient attribution is domain-agnostic — applies to any input.

class xai4tsc.xai.feature_attribution.DeepLiftExplainer(multiply_by_inputs: bool = True, eps: float = 1e-10)

Bases: xai4tsc.xai.base.GradientExplainer

Feature attribution via DeepLIFT (Captum).

Parameters:

multiply_by_inputs (bool) – Multiply contribution scores by (input - reference). Matches the original DeepLIFT paper formulation.
eps (float) – Small constant added for numerical stability in gradient computation.

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}.

class xai4tsc.xai.feature_attribution.DeconvolutionExplainer

Bases: xai4tsc.xai.base.GradientExplainer

Feature attribution via Deconvolution (Captum).

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}.

class xai4tsc.xai.feature_attribution.GuidedBackpropagationExplainer

Bases: xai4tsc.xai.base.GradientExplainer

Feature attribution via Guided Backpropagation (Captum).

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}.

class xai4tsc.xai.feature_attribution.OcclusionExplainer(window_shape: list | None = None, baseline: int = 0, strides: int = 4)

Bases: xai4tsc.xai.base.PerturbationExplainer

Feature attribution via Occlusion (Captum).

Parameters:

window_shape (list) – Shape of the sliding occlusion window, e.g. [1, 5].
baseline (int or float) – Value used to fill the occluded region.
strides (int) – Step size of the sliding window.

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}.

window_shape

baseline = 0

strides = 4

explain(model: torch.nn.Module, exp: xai4tsc.xai._types.Explanation, device: str | torch.device, targets: list | None, **kwargs: object) → numpy.ndarray: Compute occlusion attributions for the samples in exp.

class xai4tsc.xai.feature_attribution.TSHAPExplainer(window_length: float | int = 0.1, stride: int = 5, perturb_baseline: str = 'centroid', perturb_func: str | collections.abc.Callable | None = None, n_perturb_samples: int = 1, channel_mode: str = 'shared', roi: bool = False, background_data: numpy.ndarray | None = None, seed: int | None = None)

Bases: xai4tsc.xai.base.PerturbationExplainer

Feature attribution via TSHAP — exact 2-player Shapley over time windows.

For a sample x and a background series x̄, the exact Shapley value of a window w (the timesteps inside it, with w̄ the rest) is

\[\varphi(w) = \tfrac12\,[\,f(x) - f(\{\bar x_w, x_{\bar w}\}) + f(\{x_w, \bar x_{\bar w}\}) - f(\bar x)\,]\]

where f is the predicted probability of the per-sample target class. {x̄_w, x_w̄} masks the window (inside replaced by background, rest original) and {x_w, x̄_w̄} keeps only the window (rest replaced by background). Per-timestep relevance is the mean of φ(w) / window_length over all windows containing that timestep. With stride > 1 the Shapley value is computed only at strided window starts and linearly interpolated in between.

Note

The per-window Shapley values are identical to the original mlgig/tshap reference implementation (verified to machine precision). The per-timestep aggregation here follows the paper’s Eq. 9 — the mean over the windows covering each timestep (i.e. divided by the coverage count). The reference code instead sums φ(w) / window_length without dividing by the coverage count, so its per-timestep magnitudes equal these multiplied by the per-timestep coverage count. This implementation is the paper-faithful one.

Parameters:

window_length (float or int) – Window size. A float in (0, 1] is a fraction of the series length T; an int is an absolute number of timesteps.
stride (int) – Compute the Shapley value every stride window starts and interpolate the rest. 1 evaluates every window.
perturb_baseline (str) – Background strategy (see xai4tsc.utils.perturbation.baseline_replacement()): "centroid" (default), "black", "white", "mean" or "random". "centroid" requires background_data; without it a warning is emitted and "mean" is used.
perturb_func (str or callable, optional) – Override the perturbation function. A callable, a baseline name, a quantus attribute name, or a dotted import path. None uses the built-in baseline_replacement().
n_perturb_samples (int) – Number of background draws to average over (Eq. 8). Only meaningful for the stochastic "random" baseline.
channel_mode (str) – "shared" (default) — a window spans all channels and one Shapley value is broadcast to every channel (cost independent of C). "per_channel" — each (channel, window) is its own player, giving a channel-resolved map at C times the cost (an extension beyond the paper’s univariate scope).
roi (bool) – If True apply TSHAP-ROI (Algorithm 2): keep only windows whose |φ(w)| exceeds 0.1 · max|φ(w)|, merge consecutive kept windows into regions, recompute one Shapley value per region, and assign it uniformly inside the region (zero elsewhere).
background_data (np.ndarray, optional) – Background samples of shape (n, C, T). The centroid background_data.mean(axis=0) is used as the "centroid" reference. The runner resolves the YAML background_data selector to this array; passing a non-array raises (selectors are a runner-only concept).
seed (int, optional) – Seed for the random baseline, for reproducible draws.

explanation_type = 'feature_attribution': Type of explanation produced by this explainer.

data_applicability: ClassVar[set[xai4tsc.xai._types.DataType]]: TSHAP is a time-series-specific perturbation method (windows over time).

window_length = 0.1

stride

channel_mode = 'shared'

roi = False

n_perturb_samples

prng

perturb_baseline = 'centroid'

centroid: numpy.ndarray | None = None

explain(model: torch.nn.Module, exp: xai4tsc.xai._types.Explanation, device: str | torch.device, targets: list | None, **kwargs: object) → numpy.ndarray: Compute TSHAP attributions for the samples in exp.