Given
$n$ eigenvalues,
${\lambda}_{1},{\lambda}_{2},\dots ,{\lambda}_{n}$, such that
and
g05pyc 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
g05pxc then the matrix
${C}_{0}=AD{A}^{\mathrm{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
$n1$ elementary rotation matrices
${P}_{i}$ such that
$C={P}_{n1}{P}_{n2}\dots {P}_{1}{C}_{0}{P}_{1}^{\mathrm{T}}\dots {P}_{n2}^{\mathrm{T}}{P}_{n1}^{\mathrm{T}}$. The restriction on the sum of eigenvalues implies that for any diagonal element of
${C}_{0}>1$, there is another diagonal element
$\text{}<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
$\epsilon $.
One of the initialization functions
g05kfc (for a repeatable sequence if computed sequentially) or
g05kgc (for a nonrepeatable sequence) must be called prior to the first call to
g05pyc.
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

1:
$\mathbf{n}$ – Integer
Input

On entry: $n$, the dimension of the correlation matrix to be generated.
Constraint:
${\mathbf{n}}\ge 1$.

2:
$\mathbf{d}\left[{\mathbf{n}}\right]$ – const double
Input

On entry: the $n$ eigenvalues,
${\lambda}_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,n$.
Constraints:
 ${\mathbf{d}}\left[\mathit{i}1\right]\ge 0.0$, for $\mathit{i}=1,2,\dots ,n$;
 $\sum _{i=1}^{n}}{\mathbf{d}}\left[i1\right]=n$ to within eps.

3:
$\mathbf{eps}$ – double
Input

On entry: the maximum acceptable error in the diagonal elements.
Suggested value:
${\mathbf{eps}}=0.00001$.
Constraint:
${\mathbf{eps}}\ge {\mathbf{n}}\times \mathit{machineprecision}$ (see
Chapter X02).

4:
$\mathbf{state}\left[\mathit{dim}\right]$ – Integer
Communication Array
Note: the dimension,
$\mathit{dim}$, of this array is dictated by the requirements of associated functions that must have been previously called. This array MUST be the same array passed as argument
state in the previous call to
nag_rand_init_repeatable (g05kfc) or
nag_rand_init_nonrepeatable (g05kgc).
On entry: contains information on the selected base generator and its current state.
On exit: contains updated information on the state of the generator.

5:
$\mathbf{c}\left[{\mathbf{n}}\times {\mathbf{pdc}}\right]$ – double
Output

On exit: a random correlation matrix, $C$, of dimension $n$.

6:
$\mathbf{pdc}$ – Integer
Input
On entry: the stride separating row elements of the matrix
$C$ in the array
c.
Constraint:
${\mathbf{pdc}}\ge {\mathbf{n}}$.

7:
$\mathbf{fail}$ – NagError *
Input/Output

The NAG error argument (see
Section 7 in the Introduction to the NAG Library CL Interface).
The maximum error in a diagonal element is given by
eps.
Please consult the
X06 Chapter Introduction for information on how to control and interrogate the OpenMP environment used within this function. Please also consult the
Users' Note for your implementation for any additional implementationspecific information.
Following initialization of the pseudorandom number generator by a call to
g05kfc, a
$3$ by
$3$ correlation matrix with eigenvalues of
$0.7$,
$0.9$ and
$1.4$ is generated and printed.