pinball_loss_multi_objective#
- openstef_models.utils.loss_functions.pinball_loss_multi_objective(y_true: ndarray[tuple[Any, ...], dtype[floating]], y_pred: ndarray[tuple[Any, ...], dtype[floating]], quantiles: list[Quantile], sample_weight: ndarray[tuple[Any, ...], dtype[floating]] | None = None) tuple[ndarray[tuple[Any, ...], dtype[floating]], ndarray[tuple[Any, ...], dtype[floating]]][source]#
Multi-quantile pinball loss objective function for XGBoost.
Computes first-order derivatives of pinball loss for multiple quantiles and non-degenerate substitutes for second-order derivatives. This implementation scales gradients by error magnitude, making it effective with both scaled and unscaled data.
The pinball loss is the standard loss function for quantile regression, where underestimation errors are penalized by the quantile level and overestimation errors by (1 - quantile). This ensures unbiased quantile estimates when the model converges.
Gradient scaling by error magnitude addresses convergence issues with large-scale unscaled data (e.g., values in millions) by making the objective function responsive to error scale.
Non-zero second-order derivatives are returned instead of zeros because XGBoost requires non-degenerate hessian values for proper convergence. See XGBoost issue #1825 for details on why this approximation is mathematically valid. Ensure that the hyperparameter max_delta_step satisfies: 0.5 * max_delta_step <= min(quantile, 1 - quantile) for all quantiles.
- Parameters:
y_true (ndarray[tuple[Any, ...], dtype[floating]]) – True target values, shape (n_samples, n_quantiles)
y_pred (ndarray[tuple[Any, ...], dtype[floating]]) – Predicted values, shape (n_samples, n_quantiles)
quantiles (list[Quantile]) – List of validated quantiles corresponding to predictions
sample_weight (ndarray[tuple[Any, ...], dtype[floating]] | None) – Optional sample weights, shape (n_samples,). If provided, gradients and hessians are scaled by these weights to give different importance to different samples in the loss computation.
- Returns:
(gradient, hessian) arrays in 2D format for XGBoost multi-output
gradient: First derivative scaled by error magnitude, shape (n_samples, n_quantiles)
hessian: Constant positive values for numerical stability, shape (n_samples, n_quantiles)
Both arrays are normalized by n_quantiles for consistent loss values.
- Return type:
- Mathematical Formulation:
Magnitude-aware pinball loss gradient: ∇L = (τ * I(error < 0) + (1 - τ) * I(error >= 0)) * error
Where τ is the quantile level, I(·) is the indicator function, and error = y_pred - y_true. The gradient is scaled by error magnitude to handle unscaled data effectively.
References
Original pinball loss: Koenker & Bassett (1978), “Regression Quantiles”
XGBoost hessian approximation: dmlc/xgboost#1825
Implementation reference: https://gist.github.com/Nikolay-Lysenko/06769d701c1d9c9acb9a66f2f9d7a6c7