<a id="skfolio-utils-stats-cov-nearest"></a>

# skfolio.utils.stats.cov_nearest

<a id="skfolio.utils.stats.cov_nearest"></a>

### 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:**
  **cov** *ndarray of shape (n, n)*
  : Finite, symmetric covariance matrix with strictly positive variances.

  **higham** *bool, default=False*
  : If True, apply Higham’s algorithm [[1]](#r06f528358d09-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_iteration** *int, default=100*
  : Maximum number of iterations when `higham=True`.

  **warn** *bool, default=False*
  : If True, emit a UserWarning when the input requires repair.
* **Returns:**
  **cov** *ndarray 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

* <a id='r06f528358d09-1'>**[1]**</a> “Computing the nearest correlation matrix - a problem from finance” IMA Journal of Numerical Analysis Higham (2002)