skfolio.metrics.portfolio_variance_calibration_ratio#

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

Portfolio variance calibration ratio.

Let \(r_t\) be the one-period realized return vector at time \(t\) and \(w^\top r_t\) the corresponding one-period portfolio return for weights \(w\). This metric compares the sum of squared portfolio returns over an evaluation window of \(h\) observations to the horizon-scaled forecast portfolio variance:

\[s = \frac{\sum_{t=1}^{h} (w^\top r_t)^2} {h\, w^\top \Sigma\, w}\]

If the projected portfolio variance is correctly specified and portfolio returns are centered, then \(\mathbb{E}[s] = 1\).

When X_test contains NaNs (e.g. holidays, pre-listing, or post-delisting periods), NaN returns for active assets contribute zero to the realized portfolio return. The forecast covariance is scaled by the pairwise observation count matrix \(H\) (Hadamard product \(H \odot \Sigma\)) so that the realized portfolio variance and forecast variance follow the same missing-data convention. In skfolio, NaN diagonal entries in the forecast covariance mark inactive assets, which are excluded before the score is computed.

When multiple portfolios are provided (2D weights), the ratio is computed independently for each and the mean is returned. This produces a more robust diagnostic by averaging across multiple portfolio directions.

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.
portfolio_weightsarray-like of shape (n_assets,) or (n_portfolios, n_assets), optional: Portfolio weights. If None (default), inverse-volatility weights are used, which neutralizes volatility dispersion so that high-volatility assets do not dominate the diagnostic. If a 2D array is provided, each row defines a test portfolio and the mean ratio across portfolios is returned. For equal-weight calibration, pass portfolio_weights=np.ones(n_assets) / n_assets.

Returns:

float: Calibration ratio. Values near 1.0 indicate that the projected portfolio variance is well calibrated on average.