scipy.stats.random_correlation#

scipy.stats.random_correlation = <scipy.stats._multivariate.random_correlation_gen object>[source]#

A random correlation matrix.

Return a random correlation matrix, given a vector of eigenvalues.

The eigs keyword specifies the eigenvalues of the correlation matrix, and implies the dimension.

Parameters
eigs1d ndarray

Eigenvalues of correlation matrix

seed{None, int, numpy.random.Generator,

If seed is None (or np.random), the numpy.random.RandomState singleton is used. If seed is an int, a new RandomState instance is used, seeded with seed. If seed is already a Generator or RandomState instance then that instance is used.

tolfloat, optional

Tolerance for input parameter checks

diag_tolfloat, optional

Tolerance for deviation of the diagonal of the resulting matrix. Default: 1e-7

Returns
rvsndarray or scalar

Random size N-dimensional matrices, dimension (size, dim, dim), each having eigenvalues eigs.

Raises
RuntimeError

Floating point error prevented generating a valid correlation matrix.

Notes

Generates a random correlation matrix following a numerically stable algorithm spelled out by Davies & Higham. This algorithm uses a single O(N) similarity transformation to construct a symmetric positive semi-definite matrix, and applies a series of Givens rotations to scale it to have ones on the diagonal.

References

1

Davies, Philip I; Higham, Nicholas J; “Numerically stable generation of correlation matrices and their factors”, BIT 2000, Vol. 40, No. 4, pp. 640 651

Examples

>>> from scipy.stats import random_correlation
>>> rng = np.random.default_rng()
>>> x = random_correlation.rvs((.5, .8, 1.2, 1.5), random_state=rng)
>>> x
array([[ 1.        , -0.07198934, -0.20411041, -0.24385796],
       [-0.07198934,  1.        ,  0.12968613, -0.29471382],
       [-0.20411041,  0.12968613,  1.        ,  0.2828693 ],
       [-0.24385796, -0.29471382,  0.2828693 ,  1.        ]])
>>> import scipy.linalg
>>> e, v = scipy.linalg.eigh(x)
>>> e
array([ 0.5,  0.8,  1.2,  1.5])

Methods

rvs(eigs=None, random_state=None)

Draw random correlation matrices, all with eigenvalues eigs.