statsmodels.stats.covariance.transform_corr_normal#

statsmodels.stats.covariance.transform_corr_normal(corr, method, return_var=False, possdef=True, *, result_object=None)[source]#

Transform correlation matrix to be consistent at normal distribution

Parameters:

corrarray_like: correlation matrix, either Pearson, Gaussian-rank, Spearman, Kendall or quadrant correlation matrix
methodstr: type of covariance matrix supported types are ‘pearson’, ‘gauss_rank’, ‘kendal’, ‘spearman’ and ‘quadrant’
return_varbool: If true, then the asymptotic variance of the normalized correlation is also returned. The variance of the spearman correlation requires numerical integration which is calculated with scipy’s odeint.
possdefnot implemented yet: Check whether resulting correlation matrix for positive semidefinite and return a positive semidefinite approximation if not.
result_objectbool, optional: Flag controlling whether a TransformCorrNormalResult NamedTuple is returned. When return_var=True a TransformCorrNormalResult is always returned; it holds the same two elements as the legacy tuple, so it unpacks and indexes identically. When return_var=False a bare correlation matrix is returned unless result_object=True, which yields a TransformCorrNormalResult with var set to None.

Returns:

TransformCorrNormalResult or ndarray

When return_var=True (or result_object=True), a NamedTuple with fields:

corrndarray: correlation matrix, consistent with correlation for a multivariate normal distribution
varndarray or None: asymptotic variance of the correlation. None when return_var is False, since it is not computed in that case.

TransformCorrNormalResult has the same length and contents as the plain (corr_n, var) tuple it replaces, so it unpacks and indexes identically. See TransformCorrNormalResult.

When return_var=False and result_object is not True, a bare correlation matrix is returned instead.

Notes

Pearson and Gaussian-rank correlation are consistent at the normal distribution and will be returned without changes.

The other correlation matrices are not guaranteed to be positive semidefinite in small sample after conversion, even if the underlying untransformed correlation matrix is positive (semi)definite. Croux and Dehon mention that nobs / k_vars should be larger than 3 for kendall and larger than 2 for spearman.

References

[1]

Boudt, Kris, Jonathan Cornelissen, and Christophe Croux. “The Gaussian Rank Correlation Estimator: Robustness Properties.” Statistics and Computing 22, no. 2 (April 5, 2011): 471-83. https://doi.org/10.1007/s11222-011-9237-0.

[2]

Croux, Christophe, and Catherine Dehon. “Influence Functions of the Spearman and Kendall Correlation Measures.” Statistical Methods & Applications 19, no. 4 (May 12, 2010): 497-515. https://doi.org/10.1007/s10260-010-0142-z.