xai4tsc.xai.base ================ .. py:module:: xai4tsc.xai.base .. autoapi-nested-parse:: Explainer ABCs: ``ExplainerBase``, ``GradientExplainer``, and friends. Classes ------- .. autoapisummary:: xai4tsc.xai.base.ExplainerBase xai4tsc.xai.base.GradientExplainer xai4tsc.xai.base.PerturbationExplainer xai4tsc.xai.base.SurrogateExplainer xai4tsc.xai.base.WrapperExplainer Module Contents --------------- .. py:class:: ExplainerBase Bases: :py:obj:`abc.ABC` Base class for all XAI explainer methods. Subclass one of the mid-level classes (:class:`GradientExplainer`, :class:`PerturbationExplainer`, or :class:`SurrogateExplainer`) to add a custom explainer. Register the subclass with :func:`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. .. py:attribute:: explanation_type :type: str Type of explanation produced by this explainer. .. py:attribute:: data_applicability :type: ClassVar[set[xai4tsc.xai._types.DataType]] Data domains this explainer applies to. A set of :class:`~xai4tsc.xai.DataType` members — ``{DataType.AGNOSTIC}`` (any input) or ``{DataType.TIME_SERIES}``. .. py:attribute:: explanation_domains :type: ClassVar[set[xai4tsc.xai._types.Domain]] Signal domains this explainer *can* produce explanations in. A set of :class:`~xai4tsc.xai.Domain` members (capability declaration, mirroring :attr:`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. .. py:method:: explain(model: torch.nn.Module, exp: xai4tsc.xai._types.Explanation, device: str | torch.device, targets: list | None, **kwargs: object) -> numpy.ndarray :abstractmethod: Generate explanations for the samples in *exp*. :param model: The PyTorch model to explain (an :class:`~torch.nn.Module`). :param exp: :class:`~xai4tsc.xai.Explanation` dataclass holding the data, labels, and encoder for the samples to explain. :param device: Compute device (e.g. ``"cpu"`` or ``"cuda"``). :param targets: Target class indices to explain, or ``None`` for all classes. :param \*\*kwargs: Additional explainer-specific options. :returns: Explanation values with the same leading dimensions as ``exp.data``. :rtype: np.ndarray .. py:class:: GradientExplainer Bases: :py:obj:`ExplainerBase`, :py:obj:`abc.ABC` Base class for gradient-based attribution methods (Captum). Provides a shared :meth:`explain` implementation that calls the abstract :meth:`_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. .. py:attribute:: explanation_type :value: 'feature_attribution' Type of explanation produced by this explainer. .. py:method:: 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*. .. py:class:: PerturbationExplainer Bases: :py:obj:`ExplainerBase`, :py:obj:`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. .. py:attribute:: explanation_type :value: 'feature_attribution' Type of explanation produced by this explainer. .. py:class:: SurrogateExplainer Bases: :py:obj:`ExplainerBase`, :py:obj:`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. .. py:attribute:: explanation_type :value: 'feature_attribution' Type of explanation produced by this explainer. .. py:class:: WrapperExplainer(base: dict | str) Bases: :py:obj:`ExplainerBase`, :py:obj:`abc.ABC` Base class for explainers that wrap and extend another explainer. A wrapper takes a *base* explainer (any entry in :data:`~xai4tsc.xai.explain.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 :meth:`_run_base` to (re-)invoke the wrapped method. Subclasses needing a true in-pass modification (e.g. an LRP input-layer rule) may override :meth:`explain` without using :meth:`_run_base` at all. The base is instantiated via :func:`~xai4tsc.xai.explain.build_explainer`, so it is configured exactly as it would be when invoked directly by name. :param base: The base explainer to wrap. Either a bare method name, or a config dict with a ``"method"`` key plus that method's hyperparameters. :type base: dict or str .. py:attribute:: explanation_type Type of explanation produced by this explainer. .. py:attribute:: data_applicability Data domains this explainer applies to. A set of :class:`~xai4tsc.xai.DataType` members — ``{DataType.AGNOSTIC}`` (any input) or ``{DataType.TIME_SERIES}``. .. py:attribute:: explanation_domains Signal domains this explainer *can* produce explanations in. A set of :class:`~xai4tsc.xai.Domain` members (capability declaration, mirroring :attr:`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.