skfolio.utils.stats.cov_nearest

skfolio.utils.stats.cov_nearest(cov, higham=False, higham_max_iteration=100, warn=False)

Compute the nearest covariance matrix that is positive definite and admits a Cholesky decomposition. The variances are unchanged.

Non-positive-definite covariance matrices can occur in high-dimensional problems due to multicollinearity, floating-point inaccuracies, or fewer observations than assets.

The covariance matrix is converted to a correlation matrix, repaired using eigenvalue clipping or Higham’s nearest-correlation algorithm, and converted back using the original standard deviations.

Cholesky decomposition can fail for a symmetric positive-definite matrix or succeed for a non-positive-definite matrix due to floating-point error. Both Cholesky decomposition and symmetric eigenvalue checks are therefore used, with Cholesky checked first because it is faster. The input is returned unchanged if Cholesky succeeds, covariance eigenvalues are positive, and the minimum correlation eigenvalue is at least 5e-14.

Both methods clip correlation eigenvalues at 1e-13 and normalize the diagonal to one. Failed validation triggers one retry at 1e-12. After the retry, nonpositive covariance eigenvalues within n * eps * max(abs(eigenvalues)) of zero are accepted only if Cholesky decomposition succeeds, where eps is double-precision machine epsilon.

Parameters:

covndarray of shape (n, n)

Finite, symmetric covariance matrix with strictly positive variances.

highambool, default=False

If True, apply Higham’s algorithm [1] before eigenvalue clipping. Otherwise, use eigenvalue clipping only. Clipping is the default because Higham’s algorithm can be slow for large datasets.

higham_max_iterationint, default=100

Maximum number of iterations when higham=True.

warnbool, default=False

If True, emit a UserWarning when the input requires repair.

Returns:

covndarray of shape (n, n)

Repaired covariance matrix. The input is returned unchanged if it satisfies the numerical acceptance criteria.

Raises:

ValueError

If cov is not square, symmetric, or finite, has nonpositive variances, or cannot be repaired within the iteration and retry limits.

References

[1]

“Computing the nearest correlation matrix - a problem from finance” IMA Journal of Numerical Analysis Higham (2002)