xai4tsc.xai.freqrise
====================

.. py:module:: xai4tsc.xai.freqrise

.. autoapi-nested-parse::

   FreqRISE — explaining time series by random frequency masking.

   Perturbation-based attribution that masks coefficients in the frequency (real
   FFT) or time-frequency (STFT) domain and measures the effect on the model's
   predicted class probability. Univariate series (``C == 1``) are the validated
   path; multivariate inputs are masked with a shared coefficient mask broadcast
   across channels.

   Method
   ------
   For an invertible spectral transform ``g`` and a random binary mask ``M`` over
   the coefficient grid, the masked signal fed to the classifier is
   ``x̂(M) = g⁻¹(g(x) ⊙ M)``. Averaging the masked predictions weighted by the masks
   gives the per-coefficient relevance for class ``c`` (Brüsch et al., Eq. 3):

       R_c = 1 / (N · E[M]) · Σ_n  ŷ_c(x̂(M_n)) · M_n

   where ``N`` is the number of masks, ``ŷ_c`` is the softmax probability of the
   target class, and ``E[M]`` is the Bernoulli keep probability. Masks are sampled
   on a coarse ``num_cells`` grid and interpolated up to the coefficient grid to
   make them smooth.

   Reference
   ---------
   T. Brüsch, K. K. Wickstrøm, M. N. Schmidt, T. S. Alstrøm, and R. Jenssen,
   "FreqRISE: Explaining time series using frequency masking," in Proc. 6th Northern
   Lights Deep Learning Conf. (NLDL), PMLR vol. 265, 2025, pp. 16-31.
   https://proceedings.mlr.press/v265/brusch25a.html (arXiv:2406.13584)

   This is an independent reimplementation written from the published algorithm
   (Eq. 3 and the masking procedure above); it does not derive from any third-party
   FreqRISE source code.



Attributes
----------

.. autoapisummary::

   xai4tsc.xai.freqrise.logger


Classes
-------

.. autoapisummary::

   xai4tsc.xai.freqrise.FreqRISEExplainer


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

.. py:data:: logger

.. py:class:: FreqRISEExplainer(batch_size: int = 10, num_batches: int = 300, domain: str = 'stft', transform: xai4tsc.utils.fourier_transforms.DomainTransform | dict | None = None, num_cells: int = 50, probability_of_drop: float = 0.5, seed: int | None = None)

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


   FreqRISE: attribution via random masking in the frequency / TF domain.

   :param batch_size: Number of masks evaluated per forward pass.
   :type batch_size: int
   :param num_batches: Number of mask batches; the total mask count is
                       ``num_batches * batch_size``.
   :type num_batches: int
   :param domain: ``"fft"`` (frequency, via real FFT) or ``"stft"`` (time-frequency).
   :type domain: str
   :param transform: Transform used for ``domain="stft"`` (an
                     :class:`~xai4tsc.utils.fourier_transforms.STFTransform`). Required for
                     ``"stft"``; ignored for ``"fft"`` (which uses ``torch.fft.rfft``).
   :type transform: DomainTransform or dict, optional
   :param num_cells: Resolution of the coarse mask grid before it is interpolated up to the
                     coefficient grid. ``num_cells // 2`` must be smaller than the smallest
                     transform dimension.
   :type num_cells: int
   :param probability_of_drop: Bernoulli probability that a coarse cell is kept; equals ``E[M]`` in the
                               relevance normalisation (default 0.5, as in the paper).
   :type probability_of_drop: float
   :param seed: Seed for reproducible mask sampling.
   :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:: batch_size
      :value: 10



   .. py:attribute:: num_batches
      :value: 300



   .. py:attribute:: domain
      :value: 'stft'



   .. py:attribute:: transform
      :value: None



   .. py:attribute:: num_cells
      :value: 50



   .. py:attribute:: probability_of_drop
      :value: 0.5



   .. py:attribute:: seed
      :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

      Compute FreqRISE relevance for the samples in *exp*.