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: $n \geq 1$ .

d

Type: array<System..::..Double>[]()[][]

An array of size [n]

On entry: the

n

eigenvalues,

λ_{i}

, for

i = 1, 2, \dots, n

Constraints:

$d [i - 1] \geq 0.0$ , for $i = 1, 2, \dots, n$ ;
$\sum_{i = 1}^{n} d [i - 1] = n$ to within eps.

eps: Type: System..::..Double
On entry: the maximum acceptable error in the diagonal elements.
Suggested value: $eps = 0.00001$ .

Constraint: $eps \geq n \times machine precision$ (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: $dim1 \geq n$
On exit: a random correlation matrix, $C$ , of dimension $n$ .

ifail: Type: System..::..Int32%
On exit: $ifail = 0$ unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Given

n

eigenvalues,

λ_{1}, λ_{2}, \dots, λ_{n}

, such that

\sum_{i = 1}^{n} λ_{i} = n

and

λ_{i} \geq 0, i = 1, 2, \dots, n,

g05py will generate a random correlation matrix,

C

, of dimension

n

, with eigenvalues

λ_{1}, λ_{2}, \dots, λ_{n}

The method used is based on that described by Lin and Bendel (1985). Let

D

be the diagonal matrix with values

λ_{1}, λ_{2}, \dots, λ_{n}

and let

A

be a random orthogonal matrix generated by g05px then the matrix

C_{0} = A D A^{T}

is a random covariance matrix with eigenvalues

λ_{1}, λ_{2}, \dots, λ_{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 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.

$ifail = 1$

On entry,

n < 1

$ifail = 2$

On entry,	$d [i - 1] < 0.0$ for some $i$ ,
or	$\sum_{i = 1}^{n} d [i - 1] \neq n$ .

$ifail = 3$

On entry,

eps < n \times machine precision

$ifail = 4$

On entry,

state vector was not initialized or has been corrupted.

$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).

$ifail = -9000$: An error occured, see message report.
$ifail = -6000$: Invalid Parameters $〈value〉$
$ifail = -4000$: Invalid dimension for array $〈value〉$
$ifail = -8000$: Negative dimension for array $〈value〉$
$ifail = -6000$: Invalid Parameters $〈value〉$