`scipy.stats._multivariate:random_correlation_gen`

source: build-install/usr/lib/python3.14/site-packages/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)

✓

✗

array([[ 1.     ,  0.35669,  0.11743, -0.02327],
       [ 0.35669,  1.     , -0.19423,  0.27679],
       [ 0.11743, -0.19423,  1.     , -0.18468],
       [-0.02327,  0.27679, -0.18468,  1.     ]])

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

✓

✗

array([0.5, 0.8, 1.2, 1.5])

Aliases

scipy.stats._multivariate.random_correlation_gen