xai4tsc.xai.wrappers
====================

.. py:module:: xai4tsc.xai.wrappers

.. autoapi-nested-parse::

   Wrapper explainers that extend a base method (e.g. SIGN).



Attributes
----------

.. autoapisummary::

   xai4tsc.xai.wrappers.logger


Classes
-------

.. autoapisummary::

   xai4tsc.xai.wrappers.SignExplainer


Module Contents
---------------

.. py:data:: logger

.. py:class:: SignExplainer(base: dict | str, mu: float = 0.0)

   Bases: :py:obj:`xai4tsc.xai.base.WrapperExplainer`


   SIGN extension of a gradient-based attribution method.

   Implements the SIGN rule of Gumpfer et al. (Information Fusion 2023,
   `doi:10.1016/j.inffus.2023.101883`): replace a gradient method's
   conventional "x input" weighting with the binarized sign of the input,
   ``raw_gradient * s_mu(input)`` where ``s_mu(x) = -1 if x < mu else +1``.

   For the gradient-attribution family this is exactly the paper's SIGN variant.
   The sign step is the *final* operation of these methods, so applying it to
   the raw-gradient output is mathematically identical to an in-pass rule.

   .. rubric:: Notes

   **Correctness condition.** The base must emit a *raw gradient-space* map,
   i.e. it must not already multiply by the input. SIGN therefore *enforces*
   ``multiply_by_inputs=False`` on the base (Integrated Gradients, DeepLIFT),
   overriding a user-supplied ``True`` with a warning; gradient-only methods
   (Guided Backpropagation, Deconvolution) already satisfy this. A non-gradient
   base cannot produce the SIGN variant and is flagged with a warning.

   LRP-SIGN is *not* expressible this way — for LRP, SIGN is an input-layer
   relevance rule applied during the backward pass. That variant would be a
   separate :class:`~xai4tsc.xai.base.WrapperExplainer` subclass and is out of
   scope here.

   :param base: The gradient base explainer to extend. Either a bare method name or a
                config dict with a ``"method"`` key plus that method's hyperparameters
                (e.g. ``{"method": "integrated_gradients", "multiply_by_inputs": False}``).
   :type base: dict or str
   :param mu: Sign threshold. Inputs ``< mu`` map to ``-1``, the rest to ``+1``.
   :type mu: float


   .. py:attribute:: mu
      :value: 0.0



   .. py:method:: explain(model: torch.nn.Module, exp: xai4tsc.xai._types.Explanation, device: str | torch.device, targets: list | None, **kwargs: object) -> numpy.ndarray

      Run the base method, then weight it by ``sign(input - mu)``.