Skip to main content
`Ctrl`+`K`

# scipy.stats.random_correlation

scipy.stats.random_correlation = <scipy.stats._multivariate.random_correlation_gen object>

  A random correlation matrix.

  Return a random correlation matrix, given a vector of eigenvalues. The returned matrix is symmetric positive semidefinite with unit diagonal.

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

  Parameters:
    eigs 1d ndarray

      Eigenvalues of correlation matrix. All eigenvalues need to be non-negative and need to sum to the number of eigenvalues.

    seed{None, int, `numpy.random.Generator`, `numpy.random.RandomState`}, optional

      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.

    tol float, optional

      Tolerance for input parameter checks

    diag_tol float, optional

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

  Methods

  rvs(eigs=None, random_state=None) | Draw random correlation matrices, all with eigenvalues eigs.

  Returns:
    rvs ndarray 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

      >>> import numpy as np
      >>> 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.02423399,  0.03130519,  0.4946965 ],
             [-0.02423399,  1.        ,  0.20334736,  0.04039817],
             [ 0.03130519,  0.20334736,  1.        ,  0.02694275],
             [ 0.4946965 ,  0.04039817,  0.02694275,  1.        ]])
      >>> import scipy.linalg
      >>> e, v = scipy.linalg.eigh(x)
      >>> e
      array([ 0.5,  0.8,  1.2,  1.5])