skfolio.metrics.mahalanobis_calibration_ratio#

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

Mahalanobis calibration ratio.

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 compares \(R^{(h)}\) against the horizon-scaled covariance \(h\,\Sigma\):

\[s = \frac{{R^{(h)}}^\top (h\,\Sigma)^{-1} R^{(h)}}{n}\]

where \(n\) is the number of assets.

If the forecast covariance is correct and the aggregated return is centered, then \(\mathbb{E}[s] = 1\) for any horizon \(h\). Under multivariate normality, \(n s \sim \chi^2(n)\).

For financial return series, heavy tails and regime changes can cause departures from the Gaussian reference. In practice, this ratio is often most useful as a relative diagnostic across estimators.

When X_test contains NaNs (e.g. holidays, pre-listing, or post-delisting periods), only finite observations are used in the aggregated return and the covariance is scaled by the pairwise observation count matrix \(H\) (Hadamard product \(H \odot \Sigma\)) so that the same target applies with 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 that the forecast covariance matches the scale of the realized aggregated return.