xai4tsc.evaluation.frequency_evaluate
=====================================

.. py:module:: xai4tsc.evaluation.frequency_evaluate

.. autoapi-nested-parse::

   Frequency-domain perturbation metric (frequency pixel-flipping).

   Ranks the explanation's frequency coefficients by importance, progressively
   replaces the most-important ones with a baseline, inverts back to the time domain,
   and tracks the model's predicted probability for the target class. A faithful
   explanation makes the prediction drop quickly.

   Implemented as :class:`FrequencyEvaluator`, an
   :class:`~xai4tsc.evaluation.base.EvaluatorBase` subclass that reads the domain transform
   from the explanation. The shared perturbation-curve logic lives in
   :class:`PerturbationEvaluator`.



Classes
-------

.. autoapisummary::

   xai4tsc.evaluation.frequency_evaluate.PerturbationEvaluator
   xai4tsc.evaluation.frequency_evaluate.FrequencyEvaluator


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

.. py:class:: PerturbationEvaluator(transform: xai4tsc.utils.fourier_transforms.DomainTransform | None = None, features_in_step: int | None = None, perturb_baseline: float = 0.0, return_aoc_per_sample: bool = False)

   Bases: :py:obj:`xai4tsc.evaluation.base.EvaluatorBase`, :py:obj:`abc.ABC`


   Shared base for domain perturbation-curve metrics (frequency / time-frequency).

   Subclasses declare :attr:`required_domains`, a default ``features_in_step``
   (:attr:`_default_features_in_step`), and supply a :meth:`_perturb_func` and a
   :meth:`_animation_cls`. The domain ``transform`` is read from the explanation at
   evaluation time, or taken from the constructor for :meth:`animate`.

   :param transform: Domain transform. Usually left ``None`` for scoring (read from the
                     explanation) and set explicitly only for :meth:`animate`.
   :type transform: DomainTransform, optional
   :param features_in_step: Number of coefficients perturbed per step; falls back to
                            :attr:`_default_features_in_step` when ``None``.
   :type features_in_step: int, optional
   :param perturb_baseline: Value the perturbed coefficients are set to (``0.0`` removes them).
   :type perturb_baseline: float
   :param return_aoc_per_sample: Return per-sample AOC instead of the raw perturbation curves.
   :type return_aoc_per_sample: bool


   .. py:attribute:: data_applicability
      :type:  ClassVar[set[xai4tsc.xai._types.DataType]]

      Data domains this evaluator applies to (Quantus-style; defaults to agnostic).


   .. py:attribute:: required_domains
      :type:  ClassVar[set[xai4tsc.xai._types.Domain]]

      Explanation domains this evaluator requires; empty means any domain.


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



   .. py:attribute:: features_in_step
      :value: 1



   .. py:attribute:: perturb_baseline
      :value: 0.0



   .. py:attribute:: return_aoc_per_sample
      :value: False



   .. py:method:: evaluate(model: torch.nn.Module, explanation: xai4tsc.xai._types.Explanation, data: numpy.ndarray, labels: numpy.ndarray, device: str = 'cpu', **kwargs: object) -> list

      Compute the domain perturbation curve (or AOC) for the batch.

      The domain ``transform`` is taken from the constructor if set, else from the
      explanation; complex attributions are reduced to magnitude first.



   .. py:method:: animate(model: object, x_batch: numpy.ndarray, y_batch: numpy.ndarray, a_batch: numpy.ndarray, save_path: pathlib.Path | str, sample: int = 0, fps: int = 20) -> pathlib.Path

      Render one sample's perturbation process as a GIF (does not affect scoring).

      :param model: A model exposing ``predict(x) -> (classes, probs)``.
      :param x_batch: Time-domain inputs, target classes, and attributions (complex
                      attributions are reduced to magnitude).
      :type x_batch: np.ndarray
      :param y_batch: Time-domain inputs, target classes, and attributions (complex
                      attributions are reduced to magnitude).
      :type y_batch: np.ndarray
      :param a_batch: Time-domain inputs, target classes, and attributions (complex
                      attributions are reduced to magnitude).
      :type a_batch: np.ndarray
      :param save_path: Output GIF path (a ``.gif`` suffix is enforced).
      :type save_path: Path or str
      :param sample: Index of the sample to animate.
      :type sample: int
      :param fps: Frames per second.
      :type fps: int

      :returns: The written GIF path.
      :rtype: Path



.. py:class:: FrequencyEvaluator(transform: xai4tsc.utils.fourier_transforms.DomainTransform | None = None, features_in_step: int | None = None, perturb_baseline: float = 0.0, return_aoc_per_sample: bool = False)

   Bases: :py:obj:`PerturbationEvaluator`


   Frequency-domain perturbation curve (frequency pixel-flipping).

   Ranks the explanation's frequency coefficients by importance, progressively
   replaces the most-important ones with a baseline, inverts back to the time
   domain, and tracks the model's predicted probability for the target class.
   See :class:`PerturbationEvaluator` for the constructor parameters.


   .. py:attribute:: required_domains
      :type:  ClassVar[set[xai4tsc.xai._types.Domain]]

      Explanation domains this evaluator requires; empty means any domain.