xai4tsc.evaluation.evaluate
===========================

.. py:module:: xai4tsc.evaluation.evaluate

.. autoapi-nested-parse::

   ``evaluate()`` entry point and the ``METRICS`` / ``QUANTUS_METRICS`` registries.



Attributes
----------

.. autoapisummary::

   xai4tsc.evaluation.evaluate.logger
   xai4tsc.evaluation.evaluate.QUANTUS_METRICS
   xai4tsc.evaluation.evaluate.METRICS


Functions
---------

.. autoapisummary::

   xai4tsc.evaluation.evaluate.evaluate
   xai4tsc.evaluation.evaluate.register_metric


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

.. py:data:: logger

.. py:function:: evaluate(model: torch.nn.Module, metric: str, explanation: xai4tsc.xai.explain.Explanation, data: numpy.ndarray | None = None, labels: numpy.ndarray | None = None, metric_class_params: dict | None = None, metric_call_params: dict | None = None, device: str = 'cpu') -> float | numpy.ndarray | None

   Evaluate an explanation using the named metric from the METRICS registry.

   :param model: A :class:`~torch.nn.Module` (typically a :class:`~xai4tsc.ModelBase`
                 instance).
   :param metric: Registry key for the metric to run.
   :type metric: str
   :param explanation: Explanation dataclass containing ``exp_values``.
   :type explanation: Explanation
   :param data: Input samples.
   :type data: np.ndarray, optional
   :param labels: Ground-truth labels.
   :type labels: np.ndarray, optional
   :param metric_class_params: Keyword arguments for the metric constructor.
   :type metric_class_params: dict, optional
   :param metric_call_params: Keyword arguments for the metric ``__call__``.
   :type metric_call_params: dict, optional
   :param device: Compute device.
   :type device: str

   :returns: Metric score, or ``None`` if the metric is not registered.
   :rtype: float or np.ndarray or None


.. py:function:: register_metric(name: str, metric_class: type) -> None

   Register a custom metric class.

   Mirrors :func:`~xai4tsc.register_model` / :func:`~xai4tsc.register_explainer`:
   *metric_class* must be an :class:`~xai4tsc.evaluation.base.EvaluatorBase` subclass
   (instantiated with its constructor params at evaluation time). The fixed set of
   Quantus-library metrics is wired in package-side (via ``QUANTUS_METRICS`` and the
   single :class:`~xai4tsc.evaluation.base.QuantusEvaluator`), so users only ever
   register their own ``EvaluatorBase`` subclasses.

   :param name: Key used to reference the metric in experiment configs.
   :param metric_class: The metric class to register.

   :raises TypeError: If *metric_class* is not an :class:`~xai4tsc.evaluation.base.EvaluatorBase`
       subclass.


.. py:data:: QUANTUS_METRICS

.. py:data:: METRICS
   :type:  dict[str, type | collections.abc.Callable]