xai4tsc.evaluation.timefrequency_perturbation
=============================================

.. py:module:: xai4tsc.evaluation.timefrequency_perturbation

.. autoapi-nested-parse::

   Time-frequency perturbation metrics (STFT pixel-flipping).

   Like :class:`~xai4tsc.evaluation.frequency_evaluate.FrequencyEvaluator` but in the
   time-frequency (STFT) domain. The plain variant (:class:`TimeFrequencyEvaluator`) zeroes
   the most-important coefficients; the Gaussian variant
   (:class:`TimeFrequencyEvaluatorGaussian`) smears each removed coefficient with a
   Gaussian kernel before blending toward the baseline (a softer, spectrogram-aware
   perturbation). Both are
   :class:`~xai4tsc.evaluation.frequency_evaluate.PerturbationEvaluator` subclasses.



Classes
-------

.. autoapisummary::

   xai4tsc.evaluation.timefrequency_perturbation.TimeFrequencyEvaluator
   xai4tsc.evaluation.timefrequency_perturbation.TimeFrequencyEvaluatorGaussian


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

.. py:class:: TimeFrequencyEvaluator(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.frequency_evaluate.PerturbationEvaluator`


   Time-frequency perturbation curve (STFT pixel-flipping).

   Like :class:`~xai4tsc.evaluation.frequency_evaluate.FrequencyEvaluator` but in the
   time-frequency (STFT) domain: the most-important STFT coefficients are zeroed. See
   :class:`~xai4tsc.evaluation.frequency_evaluate.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.


.. py:class:: TimeFrequencyEvaluatorGaussian(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, sigma: collections.abc.Sequence[float] = (5.0, 1.0))

   Bases: :py:obj:`TimeFrequencyEvaluator`


   Time-frequency perturbation with a Gaussian-smeared baseline replacement.

   :param sigma: Standard deviations ``(freq, time)`` of the Gaussian kernel applied around
                 each removed coefficient.
   :type sigma: sequence of float
   :param transform: See :class:`~xai4tsc.evaluation.frequency_evaluate.PerturbationEvaluator`.
   :param features_in_step: See :class:`~xai4tsc.evaluation.frequency_evaluate.PerturbationEvaluator`.
   :param perturb_baseline: See :class:`~xai4tsc.evaluation.frequency_evaluate.PerturbationEvaluator`.
   :param return_aoc_per_sample: See :class:`~xai4tsc.evaluation.frequency_evaluate.PerturbationEvaluator`.


   .. py:attribute:: sigma
      :value: (5.0, 1.0)