xai4tsc.xai.base

Explainer ABCs: ExplainerBase, GradientExplainer, and friends.

Classes

`ExplainerBase`	Base class for all XAI explainer methods.
`GradientExplainer`	Base class for gradient-based attribution methods (Captum).
`PerturbationExplainer`	Base class for perturbation-based attribution methods.
`SurrogateExplainer`	Base class for surrogate / proxy model attribution methods.
`WrapperExplainer`	Base class for explainers that wrap and extend another explainer.

Module Contents

class xai4tsc.xai.base.ExplainerBase

Bases: abc.ABC

Base class for all XAI explainer methods.

Subclass one of the mid-level classes (GradientExplainer, PerturbationExplainer, or SurrogateExplainer) to add a custom explainer. Register the subclass with xai4tsc.register_explainer() to make it available by name.

Example:

class MyExplainer(GradientExplainer):
    explanation_type = "feature_attribution"

    def _get_captum_attribution(self, model):
        from captum.attr import IntegratedGradients
        return IntegratedGradients(model)

xai4tsc.register_explainer("my_method", MyExplainer)

Use specific classes for explanation types, e.g. "feature_attribution" or "counterfactual" explanations.

explanation_type: str: Type of explanation produced by this explainer.

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.

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

Generate explanations for the samples in exp.

Parameters:

model – The PyTorch model to explain (an Module).
exp – Explanation dataclass holding the data, labels, and encoder for the samples to explain.
device – Compute device (e.g. "cpu" or "cuda").
targets – Target class indices to explain, or None for all classes.
**kwargs – Additional explainer-specific options.

Returns:

Explanation values with the same leading dimensions as exp.data.

Return type:

np.ndarray

class xai4tsc.xai.base.GradientExplainer

Bases: ExplainerBase, abc.ABC

Base class for gradient-based attribution methods (Captum).

Provides a shared explain() implementation that calls the abstract _get_captum_attribution() factory method. Subclasses only need to return the appropriate Captum Attribution object.

Suitable for: Integrated Gradients, DeepLIFT, Deconvolution, Guided Backpropagation, and any other Captum gradient method.

Subclasses may set _attribute_kwargs in their __init__ to pass extra keyword arguments to Captum’s attribute() call.

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

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

class xai4tsc.xai.base.PerturbationExplainer

Bases: ExplainerBase, abc.ABC

Base class for perturbation-based attribution methods.

Suitable for: Occlusion, RISE, and any method that masks or replaces parts of the input to estimate feature importance.

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

class xai4tsc.xai.base.SurrogateExplainer

Bases: ExplainerBase, abc.ABC

Base class for surrogate / proxy model attribution methods.

Suitable for: LIME, SHAP (KernelSHAP), and any method that fits a simpler interpretable model locally around the prediction.

Currently a placeholder — no concrete implementations yet.

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

class xai4tsc.xai.base.WrapperExplainer(base: dict | str)

Bases: ExplainerBase, abc.ABC

Base class for explainers that wrap and extend another explainer.

A wrapper takes a base explainer (any entry in EXPLAINERS) and modifies its computation: either at the final input-multiplication step (e.g. SIGN for gradient-family bases) or by re-invoking it on transformed inputs (e.g. Temporal Saliency Rescaling, Time Forward Tunnel). Use _run_base() to (re-)invoke the wrapped method. Subclasses needing a true in-pass modification (e.g. an LRP input-layer rule) may override explain() without using _run_base() at all.

The base is instantiated via build_explainer(), so it is configured exactly as it would be when invoked directly by name.

Parameters:: base (dict or str) – The base explainer to wrap. Either a bare method name, or a config dict with a "method" key plus that method’s hyperparameters.

explanation_type: Type of explanation produced by this explainer.

data_applicability: Data domains this explainer applies to. A set of DataType members — {DataType.AGNOSTIC} (any input) or {DataType.TIME_SERIES}.

explanation_domains: 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.