<a id="skfolio-metrics-mahalanobis-calibration-ratio"></a>

# skfolio.metrics.mahalanobis_calibration_ratio

<a id="skfolio.metrics.mahalanobis_calibration_ratio"></a>

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

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:**
  **estimator** *BaseEstimator*
  : Fitted estimator, must expose `covariance_` or `return_distribution_.covariance`.

  **X_test** *array-like of shape (n_observations, n_assets)*
  : Realized returns for the test window.

  **y** *Ignored*
  : 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.

#### SEE ALSO
[`mahalanobis_calibration_loss`](https://skfolio.org/generated/skfolio.metrics.mahalanobis_calibration_loss.html.md#skfolio.metrics.mahalanobis_calibration_loss)
: Absolute deviation from the calibration target of `1.0`.

[`diagonal_calibration_ratio`](https://skfolio.org/generated/skfolio.metrics.diagonal_calibration_ratio.html.md#skfolio.metrics.diagonal_calibration_ratio)
: Calibration ratio using only marginal variances.