xai4tsc.xai.explanation_domains
===============================

.. py:module:: xai4tsc.xai.explanation_domains

.. autoapi-nested-parse::

   Explanation-space wrappers: lift a time-domain attributor into freq / TF space.

   Wraps any base feature-attribution method (e.g. Integrated Gradients, Guided
   Backpropagation) and maps its time-domain relevance into the frequency or
   time-frequency domain via a :class:`~xai4tsc.utils.fourier_transforms.DomainTransform`.

   Reference
   ---------
   S. Rezaei and X. Liu, "Explanation Space: A New Perspective into Time Series
   Interpretability." arXiv, Sep. 2024. doi: 10.48550/ARXIV.2409.01354.



Classes
-------

.. autoapisummary::

   xai4tsc.xai.explanation_domains.FrequencyExplainer
   xai4tsc.xai.explanation_domains.TimeFrequencyExplainer


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

.. py:class:: FrequencyExplainer(base: dict | str = 'integrated_gradients', transform: xai4tsc.utils.fourier_transforms.DomainTransform | dict | None = None)

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


   Map a base method's relevance into the frequency domain.

   Runs the wrapped time-domain attributor, then transforms its relevance with
   a Fourier transform. The base is configured exactly as if invoked by name.

   :param base: The base explainer to wrap (method name or config dict). Defaults to
                ``"integrated_gradients"``.
   :type base: dict or str
   :param transform: Transform to the frequency domain. Defaults to a full
                     :class:`~xai4tsc.utils.fourier_transforms.FourierTransform`.
   :type transform: DomainTransform or dict, optional


   .. 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:attribute:: transform


   .. 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 map its relevance to the frequency domain.



.. py:class:: TimeFrequencyExplainer(base: dict | str = 'guided_backpropagation', transform: xai4tsc.utils.fourier_transforms.DomainTransform | dict | None = None)

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


   Map a base method's relevance into the time-frequency domain.

   Runs the wrapped time-domain attributor, then transforms its relevance with
   a short-time Fourier transform.

   :param base: The base explainer to wrap (method name or config dict). Defaults to
                ``"guided_backpropagation"``.
   :type base: dict or str
   :param transform: Transform to the time-frequency domain (e.g. an
                     :class:`~xai4tsc.utils.fourier_transforms.STFTransform`). Required — there
                     is no sensible default window configuration.
   :type transform: DomainTransform or dict


   .. 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:attribute:: transform
      :value: None



   .. 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 map its relevance to time-frequency space.