`scipy.stats._multivariate:random_correlation_gen`

source: /scipy/stats/_multivariate.py :4582

Signature

class random_correlation_gen ( seed = None )

Members

Summary

A random correlation matrix.

Extended Summary

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.

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)

✓

✗

import scipy.linalg
e, v = scipy.linalg.eigh(x)

✓

✗

Aliases

scipy.stats._multivariate.random_correlation_gen