kdiagram.utils.compute_pinball_loss

kdiagram.utils.compute_pinball_loss(y_true, y_pred_quantile, quantile)[source]

Computes the Pinball Loss for a single quantile forecast.

The Pinball Loss is a metric used to evaluate the accuracy of a specific quantile forecast. It is the foundational component of the Continuous Ranked Probability Score (CRPS). A lower score is better.

Parameters:
y_truenp.ndarray

1D array of the true observed values.

y_pred_quantilenp.ndarray

1D array of the predicted values for a single quantile.

quantilefloat

The quantile level (must be between 0 and 1) for which the predictions were made.

Returns:
float

The average Pinball Loss over all observations.

Parameters:
Return type:

float

See also

compute_crps

A score calculated by averaging the pinball loss.

plot_crps_comparison

A visualization of the CRPS.

Notes

The Pinball Loss, \(\mathcal{L}_{\tau}\), is a proper scoring rule for evaluating a single quantile forecast \(q\) at level \(\tau\) against an observation \(y\). It asymmetrically penalizes errors, giving a weight of \(\tau\) to under-predictions and \((1 - \tau)\) to over-predictions.

(1)\[\begin{split}\mathcal{L}_{\tau}(q, y) = \begin{cases} (y - q) \tau & \text{if } y \ge q \\ (q - y) (1 - \tau) & \text{if } y < q \end{cases}\end{split}\]

This function calculates the average of this loss over all provided observations.

References

Examples

>>> import numpy as np
>>> from kdiagram.utils.mathext import compute_pinball_loss
>>>
>>> y_true = np.array([10, 10, 5])
>>> y_pred_q90 = np.array([8, 12, 5]) # Under-predict, over-predict, exact
>>> quantile = 0.9
>>>
>>> # Loss for y=10, q=8: (10-8) * 0.9 = 1.8
>>> # Loss for y=10, q=12: (12-10) * (1-0.9) = 0.2
>>> # Loss for y=5, q=5: (5-5) * 0.9 = 0.0
>>> # Average = (1.8 + 0.2 + 0.0) / 3 = 0.667
>>>
>>> loss = compute_pinball_loss(y_true, y_pred_q90, quantile)
>>> print(f"Average Pinball Loss for Q90: {loss:.3f}")
Expected Output
Average Pinball Loss for Q90: 0.667