Add regression metrics (#547)

* Add regression support

* update docstrings

* Ignore `no-any-return` errors

Author: fcogidi

cyclops/evaluate/metrics/experimental/__init__.py

@@ -22,7 +22,10 @@
     MultilabelF1Score,
     MultilabelFBetaScore,
 )
+from cyclops.evaluate.metrics.experimental.mae import MeanAbsoluteError
+from cyclops.evaluate.metrics.experimental.mape import MeanAbsolutePercentageError
 from cyclops.evaluate.metrics.experimental.metric_dict import MetricDict
+from cyclops.evaluate.metrics.experimental.mse import MeanSquaredError
 from cyclops.evaluate.metrics.experimental.negative_predictive_value import (
     BinaryNPV,
     MulticlassNPV,
@@ -55,6 +58,9 @@
     MulticlassROC,
     MultilabelROC,
 )
+from cyclops.evaluate.metrics.experimental.smape import (
+    SymmetricMeanAbsolutePercentageError,
+)
 from cyclops.evaluate.metrics.experimental.specificity import (
     BinarySpecificity,
     BinaryTNR,
@@ -63,3 +69,6 @@
     MultilabelSpecificity,
     MultilabelTNR,
 )
+from cyclops.evaluate.metrics.experimental.wmape import (
+    WeightedMeanAbsolutePercentageError,
+)

cyclops/evaluate/metrics/experimental/functional/__init__.py

@@ -22,6 +22,11 @@
     multilabel_f1_score,
     multilabel_fbeta_score,
 )
+from cyclops.evaluate.metrics.experimental.functional.mae import mean_absolute_error
+from cyclops.evaluate.metrics.experimental.functional.mape import (
+    mean_absolute_percentage_error,
+)
+from cyclops.evaluate.metrics.experimental.functional.mse import mean_squared_error
 from cyclops.evaluate.metrics.experimental.functional.negative_predictive_value import (
     binary_npv,
     multiclass_npv,
@@ -51,6 +56,9 @@
     multiclass_roc,
     multilabel_roc,
 )
+from cyclops.evaluate.metrics.experimental.functional.smape import (
+    symmetric_mean_absolute_percentage_error,
+)
 from cyclops.evaluate.metrics.experimental.functional.specificity import (
     binary_specificity,
     binary_tnr,
@@ -59,3 +67,6 @@
     multilabel_specificity,
     multilabel_tnr,
 )
+from cyclops.evaluate.metrics.experimental.functional.wmape import (
+    weighted_mean_absolute_percentage_error,
+)

cyclops/evaluate/metrics/experimental/functional/mae.py

@@ -0,0 +1,88 @@
+"""Functional interface for the mean absolute error metric."""
+from typing import Tuple, Union
+
+import array_api_compat as apc
+
+from cyclops.evaluate.metrics.experimental.utils.types import Array
+from cyclops.evaluate.metrics.experimental.utils.validation import (
+    _basic_input_array_checks,
+    _check_same_shape,
+    is_floating_point,
+)
+
+
+def _mean_absolute_error_update(target: Array, preds: Array) -> Tuple[Array, int]:
+    """Update and return variables required to compute Mean Absolute Error."""
+    _basic_input_array_checks(target, preds)
+    _check_same_shape(target, preds)
+    xp = apc.array_namespace(target, preds)
+
+    target = target if is_floating_point(target) else xp.astype(target, xp.float32)
+    preds = preds if is_floating_point(preds) else xp.astype(preds, xp.float32)
+
+    sum_abs_error = xp.sum(xp.abs(preds - target), dtype=xp.float32)
+    num_obs = int(apc.size(target) or 0)
+    return sum_abs_error, num_obs
+
+
+def _mean_absolute_error_compute(
+    sum_abs_error: Array,
+    num_obs: Union[int, Array],
+) -> Array:
+    """Compute Mean Absolute Error.
+
+    Parameters
+    ----------
+    sum_abs_error : Array
+        Sum of absolute value of errors over all observations.
+    num_obs : int, Array
+        Total number of observations.
+
+    Returns
+    -------
+    Array
+        The mean absolute error.
+
+    """
+    return sum_abs_error / num_obs  # type: ignore[no-any-return]
+
+
+def mean_absolute_error(target: Array, preds: Array) -> Array:
+    """Compute the mean absolute error.
+
+    Parameters
+    ----------
+    target : Array
+        Ground truth target values.
+    preds : Array
+        Estimated target values.
+
+    Return
+    ------
+    Array
+        The mean absolute error.
+
+    Raises
+    ------
+    TypeError
+        If `target` or `preds` is not an array object that is compatible with
+        the Python array API standard.
+    ValueError
+        If `target` or `preds` is empty.
+    ValueError
+        If `target` or `preds` is not a numeric array.
+    ValueError
+        If the shape of `target` and `preds` are not the same.
+
+    Examples
+    --------
+    >>> import numpy.array_api as anp
+    >>> from cyclops.evaluate.metrics.experimental.functional import mean_absolute_error
+    >>> target = anp.asarray([0.009, 1.05, 2., 3.])
+    >>> preds = anp.asarray([0., 1., 2., 2.])
+    >>> mean_absolute_error(target, preds)
+    Array(0.26475, dtype=float32)
+
+    """
+    sum_abs_error, num_obs = _mean_absolute_error_update(target, preds)
+    return _mean_absolute_error_compute(sum_abs_error, num_obs)

cyclops/evaluate/metrics/experimental/functional/mape.py

@@ -0,0 +1,124 @@
+"""Functional interface for the mean absolute percentage error metric."""
+from typing import Tuple, Union
+
+import array_api_compat as apc
+
+from cyclops.evaluate.metrics.experimental.utils.types import Array
+from cyclops.evaluate.metrics.experimental.utils.validation import (
+    _basic_input_array_checks,
+    _check_same_shape,
+)
+
+
+def _mean_absolute_percentage_error_update(
+    target: Array,
+    preds: Array,
+    epsilon: float = 1.17e-06,
+) -> Tuple[Array, int]:
+    """Update and return variables required to compute the Mean Percentage Error.
+
+    Parameters
+    ----------
+    target : Array
+        Ground truth target values.
+    preds : Array
+        Estimated target values.
+    epsilon : float, optional, default=1.17e-06
+        Specifies the lower bound for target values. Any target value below epsilon
+        is set to epsilon (avoids division by zero errors).
+
+    Returns
+    -------
+    Tuple[Array, int]
+        Sum of absolute value of percentage errors over all observations and number
+        of observations.
+
+    """
+    _basic_input_array_checks(target, preds)
+    _check_same_shape(target, preds)
+    xp = apc.array_namespace(target, preds)
+
+    abs_diff = xp.abs(preds - target)
+    abs_target = xp.abs(target)
+    clamped_abs_target = xp.where(
+        abs_target < epsilon,
+        xp.asarray(epsilon, dtype=abs_target.dtype, device=apc.device(abs_target)),
+        abs_target,
+    )
+    abs_per_error = abs_diff / clamped_abs_target
+
+    sum_abs_per_error = xp.sum(abs_per_error, dtype=xp.float32)
+
+    num_obs = int(apc.size(target) or 0)
+
+    return sum_abs_per_error, num_obs
+
+
+def _mean_absolute_percentage_error_compute(
+    sum_abs_per_error: Array,
+    num_obs: Union[int, Array],
+) -> Array:
+    """Compute the Mean Absolute Percentage Error.
+
+    Parameters
+    ----------
+    sum_abs_per_error : Array
+        Sum of absolute value of percentage errors over all observations.
+        ``(percentage error = (target - prediction) / target)``
+    num_obs : int, Array
+        Number of observations.
+
+    Returns
+    -------
+    Array
+        The mean absolute percentage error.
+
+    """
+    return sum_abs_per_error / num_obs  # type: ignore[no-any-return]
+
+
+def mean_absolute_percentage_error(target: Array, preds: Array) -> Array:
+    """Compute the mean absolute percentage error.
+
+    Parameters
+    ----------
+    target : Array
+        Ground truth target values.
+    preds : Array
+        Estimated target values.
+
+    Returns
+    -------
+    Array
+        The mean absolute percentage error.
+
+    Raises
+    ------
+    TypeError
+        If `target` or `preds` is not an array object that is compatible with
+        the Python array API standard.
+    ValueError
+        If `target` or `preds` is empty.
+    ValueError
+        If `target` or `preds` is not a numeric array.
+    ValueError
+        If the shape of `target` and `preds` are not the same.
+
+    Notes
+    -----
+    The epsilon value is taken from `scikit-learn's implementation of MAPE`.
+
+    Examples
+    --------
+    >>> import numpy.array_api as anp
+    >>> from cyclops.evaluate.metrics.experimental.functional import (
+    ...     mean_absolute_percentage_error
+    ... )
+    >>> target = anp.asarray([1., 10., 1e6])
+    >>> preds = anp.asarray([0.9, 15., 1.2e6])
+    >>> mean_absolute_percentage_error(target, preds)
+    Array(0.26666668, dtype=float32)
+
+    """
+    sum_abs_per_error, num_obs = _mean_absolute_percentage_error_update(target, preds)
+    return _mean_absolute_percentage_error_compute(sum_abs_per_error, num_obs)