credit.metrics
==============

.. py:module:: credit.metrics

.. autoapi-nested-parse::

   credit.metrics — verification metrics for CREDIT training and rollout.

   This package hosts two metric generations:

   * ``credit.metrics.gen_1.metrics`` — the legacy flat-tensor metrics
     (``LatWeightedMetrics`` and friends) used by the Gen 1 / LES / WRF trainers.
     They are re-exported here so the historical import
     ``from credit.metrics import LatWeightedMetrics`` keeps working after the
     ``credit/metrics.py`` module was folded into this package.
   * ``credit.metrics.base`` — the Gen 2 per-variable metrics
     (``BaseVariableMetric`` / ``BaseCombinedMetric`` and the built-in
     ``RMSEMetric`` / ``MSEMetric`` / ``MAEMetric`` / ``BiasMetric``) that score
     the postblock ``full_data_dict`` in physical units, mirroring
     :class:`credit.losses.base.BaseLoss`.

   Construction is config-driven via :func:`load_metric`, dispatched on
   ``conf["metrics"]["type"]`` (mirroring :func:`credit.losses.load_loss`).



Submodules
----------

.. toctree::
   :maxdepth: 1

   /api/credit/metrics/anomaly/index
   /api/credit/metrics/base/index
   /api/credit/metrics/common/index
   /api/credit/metrics/gen_1/index


Attributes
----------

.. autoapisummary::

   credit.metrics.logger
   credit.metrics.DEFAULT_METRIC_TYPES


Functions
---------

.. autoapisummary::

   credit.metrics.__getattr__
   credit.metrics.register_metric
   credit.metrics.load_metric


Package Contents
----------------

.. py:data:: logger

.. py:data:: DEFAULT_METRIC_TYPES
   :value: ('rmse', 'r2score', 'bias')


.. py:function:: __getattr__(name)

.. py:function:: register_metric(metric_type)

   Decorator that adds an external metric class to the metric registry.

   The class must inherit from :class:`credit.metrics.base.BaseVariableMetric`
   (or otherwise accept the Gen 2 ``full_data_dict`` forward contract).

   :param metric_type: Key used in the config ``metrics`` section.

   Example (Python decorator)::

       from credit.metrics import register_metric
       from credit.metrics.base import BaseVariableMetric

       @register_metric("my_metric")
       class MyMetric(BaseVariableMetric):
           ...

   Example (config ``custom_objects``)::

       custom_objects:
         MyMetric:
           object_type: metric
           module_path: mypackage.metrics

       metrics:
         type: combined
         args:
           metrics: {rmse: {}, MyMetric: {}}


.. py:function:: load_metric(conf, validation=False)

   Load a metric (or combined metric) from the config.

   Dispatches on ``conf["metrics"]["type"]``, mirroring
   :func:`credit.losses.load_loss`. The Gen 2 ``combined`` type returns a
   :class:`credit.metrics.base.BaseCombinedMetric` holding one or more
   :class:`credit.metrics.base.BaseVariableMetric` subclasses; any other
   registered ``type`` returns a single metric instance. When the ``metrics``
   section is omitted, the default combined metric contains ``rmse``,
   ``r2score``, and ``bias`` with uniform variable weighting.

   :param conf: Configuration dictionary. An optional ``metrics``
                section uses the new-style ``{type, args}`` format; when omitted,
                ``rmse``, ``r2score``, and ``bias`` are loaded with uniform
                variable weighting::

                    metrics:
                      type: combined
                      args:
                        metrics: {rmse: {}, mae: {}, bias: {}}
                        var_weighting: "inverse_variance"
                        scaler_path: "/path/scaler.json"
                        use_latitude_weights: true
                        latitude_weights: "/path/static.zarr"
   :type conf: dict
   :param validation: Reserved for API symmetry with
                      :func:`credit.losses.load_loss`. Currently unused by the metric
                      classes (metrics are not optimized).
   :type validation: bool, optional

   :returns: A metric instance callable as
             ``metrics(full_data_dict) -> dict[str, float]``.
   :rtype: torch.nn.Module

   :raises ValueError: If the requested metric type is not in ``_METRIC_REGISTRY``.