﻿ g05py Method
g05py generates a random correlation matrix with given eigenvalues.

# Syntax

C#
```public static void g05py(
int n,
double[] d,
double eps,
G05..::..G05State g05state,
double[,] c,
out int ifail
)```
Visual Basic
```Public Shared Sub g05py ( _
n As Integer, _
d As Double(), _
eps As Double, _
g05state As G05..::..G05State, _
c As Double(,), _
<OutAttribute> ByRef ifail As Integer _
)```
Visual C++
```public:
static void g05py(
int n,
array<double>^ d,
double eps,
G05..::..G05State^ g05state,
array<double,2>^ c,
[OutAttribute] int% ifail
)```
F#
```static member g05py :
n : int *
d : float[] *
eps : float *
g05state : G05..::..G05State *
c : float[,] *
ifail : int byref -> unit
```

#### Parameters

n
Type: System..::..Int32
On entry: $n$, the dimension of the correlation matrix to be generated.
Constraint: ${\mathbf{n}}\ge 1$.
d
Type: array<System..::..Double>[]()[][]
An array of size [n]
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[i-1\right]=n$ to within eps.
eps
Type: System..::..Double
On entry: the maximum acceptable error in the diagonal elements.
Suggested value: ${\mathbf{eps}}=0.00001$.
Constraint:  (see X02 class).
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
c
Type: array<System..::..Double,2>[,](,)[,][,]
An array of size [dim1, n]
Note: dim1 must satisfy the constraint: $\mathrm{dim1}\ge {\mathbf{n}}$
On exit: a random correlation matrix, $C$, of dimension $n$.
ifail
Type: System..::..Int32%
On exit: ${\mathbf{ifail}}={0}$ unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

# Description

Given $n$ eigenvalues, ${\lambda }_{1},{\lambda }_{2},\dots ,{\lambda }_{n}$, such that
 $∑i=1nλi=n$
and
 $λi≥0, i=1,2,…,n,$
g05py 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 g05px 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 $n-1$ elementary rotation matrices ${P}_{i}$ such that $C={P}_{n-1}{P}_{n-2}\dots {P}_{1}{C}_{0}{P}_{1}^{\mathrm{T}}\dots {P}_{n-2}^{\mathrm{T}}{P}_{n-1}^{\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$.
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 methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05py.

# 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

# Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDC) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
${\mathbf{ifail}}=1$
 On entry, ${\mathbf{n}}<1$.
${\mathbf{ifail}}=2$
 On entry, ${\mathbf{d}}\left[i-1\right]<0.0$ for some $i$, or $\sum _{i=1}^{n}{\mathbf{d}}\left[i-1\right]\ne n$.
${\mathbf{ifail}}=3$
 On entry, .
${\mathbf{ifail}}=4$
 On entry, state vector was not initialized or has been corrupted.
${\mathbf{ifail}}=5$
The error in a diagonal element is greater than eps. The value of eps should be increased. Otherwise the program could be rerun with a different value used for the seed of the random number generator, see (G05KFF not in this release) (G05KGF not in this release).
${\mathbf{ifail}}=-9000$
An error occured, see message report.
${\mathbf{ifail}}=-6000$
Invalid Parameters $〈\mathit{\text{value}}〉$
${\mathbf{ifail}}=-4000$
Invalid dimension for array $〈\mathit{\text{value}}〉$
${\mathbf{ifail}}=-8000$
Negative dimension for array $〈\mathit{\text{value}}〉$
${\mathbf{ifail}}=-6000$
Invalid Parameters $〈\mathit{\text{value}}〉$

# Accuracy

The maximum error in a diagonal element is given by eps.

# Parallelism and Performance

None.

The time taken by g05py is approximately proportional to ${n}^{2}$.