xai4tsc.utils.perturbation
==========================

.. py:module:: xai4tsc.utils.perturbation

.. autoapi-nested-parse::

   Perturbation helpers: ``baseline_replacement`` and ``resolve_perturb_func``.

   A perturbation function follows the canonical signature
   ``(arr, indices, **kwargs) -> arr``: it returns a copy of *arr* with the
   positions named by *indices* replaced by a baseline value.  This mirrors the
   Quantus convention already used in :mod:`xai4tsc.evaluation` and lets
   perturbation-based explainers (e.g. TSHAP) treat "missingness" as a pluggable
   strategy.



Attributes
----------

.. autoapisummary::

   xai4tsc.utils.perturbation.logger
   xai4tsc.utils.perturbation.BASELINES


Functions
---------

.. autoapisummary::

   xai4tsc.utils.perturbation.baseline_replacement
   xai4tsc.utils.perturbation.resolve_perturb_func


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

.. py:data:: logger

.. py:data:: BASELINES
   :type:  frozenset[str]

.. py:function:: baseline_replacement(arr: numpy.ndarray, indices: numpy.ndarray, baseline: str = 'centroid', reference: numpy.ndarray | None = None, prng: numpy.random.Generator | None = None, **kwargs: object) -> numpy.ndarray

   Return a copy of *arr* with *indices* replaced by a *baseline* value.

   :param arr: Single series of shape ``(C, T)``.
   :type arr: np.ndarray
   :param indices: Time indices (along the last axis) to replace.  An empty array returns
                   an unmodified copy.
   :type indices: np.ndarray
   :param baseline: One of :data:`BASELINES`:

                    - ``"centroid"`` — replace with the matching columns of *reference*
                      (a precomputed ``(C, T)`` background waveform, e.g. a class/dataset
                      centroid).  Falls back to ``"mean"`` if *reference* is ``None``.
                    - ``"black"`` — replace with zeros.
                    - ``"white"`` — replace with ones.
                    - ``"mean"`` — replace with each channel's own temporal mean.
                    - ``"random"`` — replace with Gaussian noise matched to each channel's
                      mean and standard deviation (uses *prng* when supplied).
   :type baseline: str
   :param reference: Background waveform of shape ``(C, T)`` used by ``"centroid"``.
   :type reference: np.ndarray, optional
   :param prng: Random generator for ``"random"``; a default generator is used when
                ``None``.
   :type prng: np.random.Generator, optional
   :param \*\*kwargs: Ignored; accepted so callers can pass through extra perturbation
                      options uniformly.
   :type \*\*kwargs: object

   :returns: A copy of *arr* with the requested replacement applied.
   :rtype: np.ndarray

   :raises ValueError: If *baseline* is not one of :data:`BASELINES`.


.. py:function:: resolve_perturb_func(value: str | collections.abc.Callable) -> collections.abc.Callable | None

   Resolve *value* to a perturbation callable.

   A callable is returned unchanged.  A string is resolved by trying, in order:
   the names in :data:`BASELINES` (bound to :func:`baseline_replacement`), the
   top-level ``quantus`` namespace, then a dotted import path
   (e.g. ``"my_module.my_perturb"``).

   :param value: A callable, a baseline name, a ``quantus`` attribute name, or a dotted
                 import path.
   :type value: str or callable

   :returns: The resolved callable, or ``None`` if a string could not be resolved.
   :rtype: callable or None