statsmodels.stats.correlation_tools.cov_nearest

statsmodels.stats.correlation_tools.cov_nearest(cov, method='clipped', threshold=1e-15, n_fact=100, return_all=False, *, min_diag=None, use_namedtuple=None)

Find the nearest covariance matrix that is positive (semi-) definite

This leaves the diagonal, i.e. the variance, unchanged, unless min_diag is used to enforce a strictly positive diagonal (see below).

Parameters:

covndarray, (k,k)

initial covariance matrix

methodstr

if “clipped”, then the faster but less accurate corr_clipped is used. If “nearest”, then corr_nearest is used

thresholdfloat

clipping threshold for smallest eigen value, see Notes

n_factint or float

factor to determine the maximum number of iterations in corr_nearest. See its doc string

return_allbool

if False (default), then only the covariance matrix is returned. If True, then correlation matrix and standard deviation are additionally returned.

min_diagNone or float

If None (default), the diagonal of cov is left unchanged. This function converts the covariance matrix to a correlation matrix, which is not defined if a diagonal element (variance) is zero or negative and results in a matrix that contains nan. If min_diag is a positive float, then diagonal elements that are smaller than min_diag are raised to min_diag before the conversion, and a SpecificationWarning is issued. This makes it possible to correct matrices with a zero or negative diagonal, at the cost of changing those variances.

use_namedtuplebool, optional

Flag controlling whether a CovNearestResult NamedTuple is returned. When return_all=True a CovNearestResult is always returned; it holds the same three elements as the legacy tuple, so it unpacks and indexes identically. When return_all=False a bare covariance matrix is returned unless use_namedtuple=True, which yields a CovNearestResult carrying the correlation matrix and standard deviations too.

Returns:

CovNearestResult or ndarray

When return_all=True (or use_namedtuple=True), a NamedTuple with fields:

covndarray

corrected covariance matrix

corrndarray

corrected correlation matrix

stdndarray

standard deviation

CovNearestResult has the same length and contents as the plain (cov_, corr_, std_) tuple it replaces, so it unpacks and indexes identically. See CovNearestResult.

When return_all=False a bare corrected covariance matrix is returned instead.

See also

corr_nearest

corr_clipped

Notes

This converts the covariance matrix to a correlation matrix. Then, finds the nearest correlation matrix that is positive semidefinite and converts it back to a covariance matrix using the initial standard deviation.

The smallest eigenvalue of the intermediate correlation matrix is approximately equal to the threshold. If the threshold=0, then the smallest eigenvalue of the correlation matrix might be negative, but zero within a numerical error, for example in the range of -1e-16.

Assumes input covariance matrix is symmetric.