xai4tsc.xai.random_baseline
===========================

.. py:module:: xai4tsc.xai.random_baseline

.. autoapi-nested-parse::

   Random-baseline explainers in the frequency and time-frequency domains.

   Sanity baselines for evaluation: they ignore the model and return uniform-random
   relevance shaped like the transformed input. A faithful explainer should beat
   these on perturbation metrics.



Classes
-------

.. autoapisummary::

   xai4tsc.xai.random_baseline.RandomFrequencyExplainer
   xai4tsc.xai.random_baseline.RandomTimeFreqExplainer


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

.. py:class:: RandomFrequencyExplainer(transform: xai4tsc.utils.fourier_transforms.DomainTransform | dict | None = None, seed: int | None = None)

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


   Uniform-random baseline relevance in the frequency domain.

   :param transform: Transform from time to frequency domain. Defaults to a full
                     :class:`~xai4tsc.utils.fourier_transforms.FourierTransform`.
   :type transform: DomainTransform or dict, optional
   :param seed: Seed for the random relevance, for reproducible draws.
   :type seed: int, 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:attribute:: prng


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

      Return uniform-random relevance shaped like the frequency transform.



.. py:class:: RandomTimeFreqExplainer(transform: xai4tsc.utils.fourier_transforms.DomainTransform | dict | None = None, seed: int | None = None)

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


   Uniform-random baseline relevance in the time-frequency domain.

   :param transform: Transform from time to 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
   :param seed: Seed for the random relevance, for reproducible draws.
   :type seed: int, 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
      :value: None



   .. py:attribute:: prng


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

      Return uniform-random relevance shaped like the time-frequency transform.