naginterfaces.library.rand.matrix_​corr

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

matrix_corr generates a random correlation matrix with given eigenvalues.

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

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/g05/g05pyf.html

Parameters

dfloat, array-like, shape $\left(n\right)$

The $n$ eigenvalues, ${\lambda }_{\text{i}}$, for $\text{i}=1,2,\dots ,n$.

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 $(n,n)$

A random correlation matrix, $C$, of dimension $n$.

Raises

NagValueError

(errno $1$)

On entry, $n=⟨value⟩$.

Constraint: $n\ge 1$.

(errno $2$)

On entry, an eigenvalue is negative.

(errno $2$)

On entry, the eigenvalues do not sum to $\text{n}$.

(errno $3$)

On entry, $eps=⟨value⟩$.

Constraint: $eps\ge n\times \text{machine precision}$.

(errno $4$)

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

(errno $5$)

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

Notes

Given $n$ eigenvalues, ${\lambda }_1,{\lambda }_2,\dots ,{\lambda }_n$, such that

$$\sum _{i=1}^n{\lambda }_i=n$$

and

$${\lambda }_i\ge 0\text{,}i=1,2,\dots ,n\text{,}$$

matrix_corr will generate a random correlation matrix, $C$, of dimension $n$, with eigenvalues ${\lambda }_1,{\lambda }_2,\dots ,{\lambda }_n$.

The method used is based on that described by Lin and Bendel (1985). Let $D$ be the diagonal matrix with values ${\lambda }_1,{\lambda }_2,\dots ,{\lambda }_n$ and let $A$ be a random orthogonal matrix generated by matrix_orthog() then the matrix $C_0=AD{A}^T$ is a random covariance matrix with eigenvalues ${\lambda }_1,{\lambda }_2,\dots ,{\lambda }_n$. The matrix $C_0$ is transformed into a correlation matrix by means of $n-1$ elementary rotation matrices $P_i$ such that $C=P_{n-1}{P}_{n-2}\dots P_1{C}_0{P}_1^T\dots P_{n-2}^T{P}_{n-1}^T$. The restriction on the sum of eigenvalues implies that for any diagonal element of $C_0>1$, there is another diagonal element $<1$. The $P_i$ 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 $1$ to within a given tolerance $ϵ$.

The randomness of $C$ should be interpreted only to the extent that $A$ is a random orthogonal matrix and $C$ is computed from $A$ using the $P_i$ 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