skfolio.metrics.diagonal_calibration_ratio#

skfolio.metrics.diagonal_calibration_ratio(estimator, X_test, y=None)[source]#

Diagonal calibration ratio based on marginal variances.

Let \(r_t\) be the one-period realized return vector at time \(t\), and let \(R^{(h)} = \sum_{t=1}^{h} r_t\) be the aggregated return over an evaluation window of \(h\) observations. This metric uses only the diagonal of the covariance matrix, ignoring correlations, and compares each component \(R_i^{(h)}\) against the horizon-scaled variance \(h\,\sigma_i^2\):

\[s = \frac{1}{n}\sum_{i=1}^{n} \frac{(R_i^{(h)})^2}{h\,\sigma_i^2}\]

where \(n\) is the number of assets and \(\sigma_i^2\) is the forecast variance for asset \(i\).

If the marginal variance forecasts are correct and the aggregated returns are centered, then \(\mathbb{E}[s] = 1\) for any horizon \(h\). Because correlations are ignored, this metric diagnoses the calibration of marginal scales rather than the full covariance structure.

When X_test contains NaNs (e.g. holidays, pre-listing, or post-delisting periods), each asset uses its own effective horizon \(h_i\), equal to the number of finite observations for that asset, so the ratio retains the same target under missing data. In skfolio, NaN diagonal entries in the forecast covariance mark inactive assets, which are excluded from the evaluation.

Parameters:

estimatorBaseEstimator: Fitted estimator, must expose covariance_ or return_distribution_.covariance.
X_testarray-like of shape (n_observations, n_assets): Realized returns for the test window.
yIgnored: Present for scikit-learn API compatibility.

Returns:

float: Calibration ratio. Values near 1.0 indicate well-calibrated marginal variance forecasts.