AbsoluteGammaResidual

yohou.metrics.conformity.AbsoluteGammaResidual

Bases: GammaResidual

Absolute gamma residual scorer using absolute relative errors.

Computes conformity scores as the absolute relative error:

\[s = \left|\frac{y - \hat{y}}{\hat{y} + \epsilon}\right|\]

Produces symmetric prediction intervals that are proportional to the prediction magnitude.

Parameters

Name	Type	Description	Default
epsilon	float	Small constant added to the denominator to prevent division by zero.	1e-8

See Also

• GammaResidual : Asymmetric variant using signed relative errors.
• AbsoluteResidual : Scale-independent symmetric variant.

Examples

>>> import polars as pl
>>> from datetime import date
>>> from yohou.metrics.conformity import AbsoluteGammaResidual
>>> scorer = AbsoluteGammaResidual(epsilon=1e-8).fit(
...     pl.DataFrame({"time": [date(2020, 1, 1), date(2020, 1, 2)], "y": [1.0, 2.0]})
... )
>>> y_truth = pl.DataFrame({"time": [date(2020, 1, 3)], "y": [6.0]})
>>> y_pred = pl.DataFrame({"time": [date(2020, 1, 3)], "y": [8.0]})
>>> scores = scorer.score(y_truth, y_pred)
>>> round(scores.drop("time").to_series().item(), 4)
0.25

Source Code

View on GitHub

Show/Hide source

class AbsoluteGammaResidual(GammaResidual):
    r"""Absolute gamma residual scorer using absolute relative errors.

    Computes conformity scores as the absolute relative error:

    $$s = \left|\frac{y - \hat{y}}{\hat{y} + \epsilon}\right|$$

    Produces **symmetric** prediction intervals that are proportional
    to the prediction magnitude.

    Parameters
    ----------
    epsilon : float, default=1e-8
        Small constant added to the denominator to prevent division by
        zero.

    See Also
    --------
    - [`GammaResidual`][yohou.metrics.conformity.GammaResidual] : Asymmetric variant using signed relative errors.
    - [`AbsoluteResidual`][yohou.metrics.conformity.AbsoluteResidual] : Scale-independent symmetric variant.

    Examples
    --------
    >>> import polars as pl
    >>> from datetime import date
    >>> from yohou.metrics.conformity import AbsoluteGammaResidual
    >>> scorer = AbsoluteGammaResidual(epsilon=1e-8).fit(
    ...     pl.DataFrame({"time": [date(2020, 1, 1), date(2020, 1, 2)], "y": [1.0, 2.0]})
    ... )
    >>> y_truth = pl.DataFrame({"time": [date(2020, 1, 3)], "y": [6.0]})
    >>> y_pred = pl.DataFrame({"time": [date(2020, 1, 3)], "y": [8.0]})
    >>> scores = scorer.score(y_truth, y_pred)
    >>> round(scores.drop("time").to_series().item(), 4)
    0.25

    """

    def __sklearn_tags__(self):
        """Get the tags for this estimator."""
        tags = super().__sklearn_tags__()
        assert tags.scorer_tags is not None
        tags.scorer_tags.symmetric = True
        return tags

    def score(self, y_truth: pl.DataFrame, y_pred: pl.DataFrame, /, **score_params) -> pl.DataFrame:
        r"""Compute absolute gamma residual conformity scores.

        Parameters
        ----------
        y_truth : pl.DataFrame
            True target values.

        y_pred : pl.DataFrame
            Predicted values.

        Returns
        -------
        pl.DataFrame
            Absolute relative conformity scores with \"time\" column preserved.

        """
        check_is_fitted(self, ["_is_fitted"])

        # Get parent scores (includes "time" column)
        scores = GammaResidual.score(self, y_truth, y_pred)

        # Apply abs to non-time columns only
        scores = scores.select(
            "time",  # Keep time as-is
            cs.exclude("time").abs(),  # Apply abs to value columns
        )

        return scores

Methods

__sklearn_tags__()

Get the tags for this estimator.

Source Code

View on GitHub

Show/Hide source

def __sklearn_tags__(self):
    """Get the tags for this estimator."""
    tags = super().__sklearn_tags__()
    assert tags.scorer_tags is not None
    tags.scorer_tags.symmetric = True
    return tags

score(y_truth, y_pred, /, **score_params)

Compute absolute gamma residual conformity scores.

Parameters

Name	Type	Description	Default
y_truth	DataFrame	True target values.	required
y_pred	DataFrame	Predicted values.	required

Returns

Type	Description
DataFrame	Absolute relative conformity scores with \"time\" column preserved.

Source Code

View on GitHub

Show/Hide source

def score(self, y_truth: pl.DataFrame, y_pred: pl.DataFrame, /, **score_params) -> pl.DataFrame:
    r"""Compute absolute gamma residual conformity scores.

    Parameters
    ----------
    y_truth : pl.DataFrame
        True target values.

    y_pred : pl.DataFrame
        Predicted values.

    Returns
    -------
    pl.DataFrame
        Absolute relative conformity scores with \"time\" column preserved.

    """
    check_is_fitted(self, ["_is_fitted"])

    # Get parent scores (includes "time" column)
    scores = GammaResidual.score(self, y_truth, y_pred)

    # Apply abs to non-time columns only
    scores = scores.select(
        "time",  # Keep time as-is
        cs.exclude("time").abs(),  # Apply abs to value columns
    )

    return scores

Tutorials

The following example notebooks use this component:

• How to Use Conformity Scorers

  ---

  Evaluation-Search

  Compare Residual, AbsoluteResidual, GammaResidual, and AbsoluteGammaResidual conformity scorers with coverage/width analysis and DistanceSimilarity interaction.

  View · Open in marimo