# naginterfaces.library.rand.matrix_​corr¶

naginterfaces.library.rand.matrix_corr(d, statecomm, eps=1e-05)[source]

matrix_corr generates a random correlation matrix with given eigenvalues.

For full information please refer to the NAG Library document for g05py

https://www.nag.com/numeric/nl/nagdoc_27.1/flhtml/g05/g05pyf.html

Parameters
dfloat, array-like, shape

The eigenvalues, , for .

statecommdict, RNG communication object, modified in place

RNG communication structure.

This argument must have been initialized by a prior call to init_repeat() or init_nonrepeat().

epsfloat, optional

The maximum acceptable error in the diagonal elements.

Returns
cfloat, ndarray, shape

A random correlation matrix, , of dimension .

Raises
NagValueError
(errno )

On entry, .

Constraint: .

(errno )

On entry, an eigenvalue is negative.

(errno )

On entry, the eigenvalues do not sum to .

(errno )

On entry, .

Constraint: .

(errno )

On entry, [‘state’] vector has been corrupted or not initialized.

(errno )

The diagonals of the returned matrix are not unity, try increasing the value of , or rerun the code using a different seed.

Notes

Given eigenvalues, , such that

and

matrix_corr will generate a random correlation matrix, , of dimension , with eigenvalues .

The method used is based on that described by Lin and Bendel (1985). Let be the diagonal matrix with values and let be a random orthogonal matrix generated by matrix_orthog() then the matrix is a random covariance matrix with eigenvalues . The matrix is transformed into a correlation matrix by means of elementary rotation matrices such that . The restriction on the sum of eigenvalues implies that for any diagonal element of , there is another diagonal element . The are constructed from such pairs, chosen at random, to produce a unit diagonal element corresponding to the first element. This is repeated until all diagonal elements are to within a given tolerance .

The randomness of should be interpreted only to the extent that is a random orthogonal matrix and is computed from using the which are chosen as arbitrarily as possible.

One of the initialization functions init_repeat() (for a repeatable sequence if computed sequentially) or init_nonrepeat() (for a non-repeatable sequence) must be called prior to the first call to matrix_corr.

References

Lin, S P and Bendel, R B, 1985, Algorithm AS 213: Generation of population correlation on matrices with specified eigenvalues, Appl. Statist. (34), 193–198