xai4tsc.xai.explain
===================

.. py:module:: xai4tsc.xai.explain

.. autoapi-nested-parse::

   ``generate_explanation()`` entry point, ``EXPLAINERS`` registry, plot helpers.



Attributes
----------

.. autoapisummary::

   xai4tsc.xai.explain.logger
   xai4tsc.xai.explain.EXPLAINERS


Functions
---------

.. autoapisummary::

   xai4tsc.xai.explain.generate_explanation
   xai4tsc.xai.explain.plot_exp
   xai4tsc.xai.explain.build_explainer
   xai4tsc.xai.explain.register_explainer


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

.. py:data:: logger

.. py:function:: generate_explanation(method: str, model: xai4tsc.models.base.ModelBase, data: numpy.ndarray, labels: numpy.ndarray | None = None, targets: str = 'predicted', params: dict | None = None, encoder: sklearn.preprocessing.OneHotEncoder | sklearn.preprocessing.LabelEncoder | sklearn.preprocessing.OrdinalEncoder | None = None, indices: list | None = None, samples: int = 5, prng: numpy.random.Generator | None = None, device: str = 'cpu', save_path: pathlib.Path | str | None = None, visualization_type: list | None = None) -> xai4tsc.xai._types.Explanation | None

   Generate an explanation for the given indices or for random samples.

   Set *indices* to an empty list or ``None`` to choose random samples.

   :param method: Explanation method to use. Have a look at the support.yaml file.
   :type method: str
   :param model: Model to explain.
   :type model: ModelBase
   :param data: Dataset to generate an explanation for.
   :type data: np.ndarray
   :param labels: Labels of the dataset, by default None
   :type labels: np.ndarray, optional
   :param targets: Which class to explain: ``"predicted"`` (default), ``"label"``
                   (ground truth), or ``"all"`` (one explanation per class).
   :type targets: str, optional
   :param params: Parameters for the explanation method, by default None
   :type params: dict, optional
   :param encoder: Encoder used to encode the labels, by default None
   :type encoder: OneHotEncoder | LabelEncoder | OrdinalEncoder, optional
   :param indices: Indices of samples to explain, by default None
   :type indices: list, optional
   :param samples: Number of random samples to explain if no indices supplied, by default 5
   :type samples: int, optional
   :param prng: Random number generator to sample random indices, by default None
   :type prng: np.random.Generator, optional
   :param device: Device to calculate on, by default ``"cpu"``.
   :type device: str, optional
   :param save_path: Path to save the explanation visualisation to, by default None
   :type save_path: Path | str, optional
   :param visualization_type: Plot styles to render when saving, by default ``["bubbles"]``.
   :type visualization_type: list, optional

   :returns: An object of the Explanation dataclass.
   :rtype: Explanation


.. py:function:: plot_exp(exp: xai4tsc.xai._types.Explanation, norm: bool = True, save_path: pathlib.Path | str | None = None, visualization_type: list | None = None) -> None

   Render and save relevance plots for every sample in *exp*.

   One sub-directory per sample index is created under *save_path*. The renderer
   is chosen by ``exp.explanation_domain``: time-domain explanations use the 1-D
   :func:`~xai4tsc.utils.plot.plot_relevance` overlay styles; frequency and
   time-frequency explanations use :func:`~xai4tsc.utils.plot.plot_relevance_f`
   and :func:`~xai4tsc.utils.plot.plot_relevance_tf` respectively. For
   multi-target (time-domain) explanations one plot per class is written.


   :param exp: _description_
   :type exp: Explanation
   :param norm: Whether to normalize explanation values, by default True
   :type norm: bool, optional
   :param save_path: Path to save explanations too, by default None
   :type save_path: Path | str | None, optional
   :param visualization_type: Type of visualization can be any of `"bubbles"`` (default), ``"background"``,
                              ``"intensity"``, ``"graph"``, or ``"bar"``, by default None
   :type visualization_type: list | None, optional


.. py:data:: EXPLAINERS

.. py:function:: build_explainer(method: str, params: dict | None) -> xai4tsc.xai.base.ExplainerBase

   Instantiate a registered explainer, filtering *params* to its ``__init__``.

   Shared by :func:`_get_explanation` and by wrapper explainers
   (:class:`~xai4tsc.xai.base.WrapperExplainer`) that need to build their
   wrapped base method the same way the runner does.

   :param method: Explainer name; looked up case-insensitively in :data:`EXPLAINERS`.
   :type method: str
   :param params: Parameters to pass to the explainer's ``__init__``. Keys not matching
                  the constructor signature are dropped via :func:`dict_to_args`. If the
                  class defines no ``__init__``, no parameters are passed.
   :type params: dict or None

   :returns: A ready-to-use explainer instance.
   :rtype: ExplainerBase

   :raises NotImplementedError: If *method* is not registered in :data:`EXPLAINERS`.


.. py:function:: register_explainer(name: str, explainer_class: type) -> None

   Register a custom :class:`~xai4tsc.xai.ExplainerBase` subclass.

   After registration the explainer is available by *name* in experiment
   configs and via :func:`_get_explanation`.

   :param name: Key used to look up the explainer (case-insensitive).
   :param explainer_class: A concrete subclass of :class:`~xai4tsc.xai.ExplainerBase` (or one of
                           its mid-level subclasses).

   :raises TypeError: If *explainer_class* is not an
       :class:`~xai4tsc.xai.ExplainerBase` subclass.