statsmodels.stats.correlation_tools.corr_clipped

statsmodels.stats.correlation_tools.corr_clipped(corr, threshold=1e-15)[source]

Find a near correlation matrix that is positive semi-definite

This function clips the eigenvalues, replacing eigenvalues smaller than the threshold by the threshold. The new matrix is normalized, so that the diagonal elements are one. Compared to corr_nearest, the distance between the original correlation matrix and the positive definite correlation matrix is larger, however, it is much faster since it only computes eigenvalues once.

Parameters:

corr : ndarray, (k, k)

initial correlation matrix

threshold : float

clipping threshold for smallest eigenvalue, see Notes

Returns:

corr_new : ndarray, (optional)

corrected correlation matrix

Notes

The smallest eigenvalue of the corrected correlation matrix is approximately equal to the threshold. In examples, the smallest eigenvalue can be by a factor of 10 smaller than the threshold, e.g. threshold 1e-8 can result in smallest eigenvalue in the range between 1e-9 and 1e-8. 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 correlation matrix is symmetric. The diagonal elements of returned correlation matrix is set to ones.

If the correlation matrix is already positive semi-definite given the threshold, then the original correlation matrix is returned.

cov_clipped is 40 or more times faster than cov_nearest in simple example, but has a slightly larger approximation error.