PinballLoss¶

Defined in fynance.models.loss

class PinballLoss(taus=(0.1, 0.5, 0.9), **kwargs)[source]

Bases: BaseLoss

Pinball (quantile / check) loss for multi-quantile regression.

For a target quantile \(\tau \in (0, 1)\) and error \(e = y - \hat{y}_\tau\):

\[\mathcal{L}_\tau(e) = \max(\tau e,\ (\tau - 1) e)\]

an asymmetric penalty: under-prediction (\(e > 0\)) is penalized by \(\tau\) and over-prediction (\(e < 0\)) by \(1 - \tau\). At \(\tau = 0.5\) it reduces to \(0.5 |e|\), i.e. half the mean absolute error. Minimizing it over a batch drives pred toward the \(\tau\)-th conditional quantile of target.

With several taus at once, pred carries one column per quantile and the reported loss is the mean over quantiles and samples of the per-quantile pinball loss — the standard way to train a single multi-quantile head such as QuantileModel.

Parameters:

tausfloat or sequence of float, optional: Target quantile(s) in (0, 1). Default (0.1, 0.5, 0.9).
**kwargs: Forwarded to BaseLoss (rf, period, eps) — not used by this loss (it is not a ratio/annualized objective), kept only for API consistency across fynance.models.loss.

Raises:

ValueError: If taus is empty or any value is not strictly in (0, 1).

See also

fynance.models.quantile.QuantileModel

Notes

taus are sorted ascending internally (see _validate_taus), so pred’s trailing axis is expected in that same ascending order. This loss does not enforce non-crossing quantiles (q10 <= q50 <= q90) — it is the plain per-column pinball loss; monotonicity is a predict-time concern (see predict_quantiles).

Examples

>>> import torch
>>> from fynance.models.loss import PinballLoss
>>> target = torch.tensor([1.0, 2.0, 3.0])
>>> pred = torch.tensor([[1.0], [2.0], [3.0]])   # perfect single-tau fit
>>> PinballLoss(taus=0.5)(pred, target).item()
0.0
>>> pred_off = pred + 1.0
>>> loss = PinballLoss(taus=0.5)(pred_off, target)
>>> loss.item() == 0.5   # tau=0.5 -> half the (constant) absolute error
True

forward(pred, target)[source]

Compute the mean pinball loss across quantiles and samples.

Parameters:

predtorch.Tensor: Predicted quantiles, shape (..., n_taus).
targettorch.Tensor: True values, shape (...,) — pred without its trailing quantile axis — broadcast against every quantile column.

Returns:

torch.Tensor: Scalar loss: the mean over quantiles and samples of \(\max(\tau e, (\tau - 1) e)\).

Raises:

TypeError: If pred or target is not a torch.Tensor.
ValueError: If pred’s trailing dimension does not equal the number of taus, or target’s shape does not match pred’s shape without that trailing dimension.