NAG Library Function Document

nag_rand_corr_matrix (g05pyc)

+− Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Further Comments

+− 9 Example

9.1 Program Text

9.2 Program Data

9.3 Program Results

1 Purpose

nag_rand_corr_matrix (g05pyc) generates a random correlation matrix with given eigenvalues.

2 Specification

#include <nag.h>

#include <nagg05.h>

void	nag_rand_corr_matrix (Integer n, const double d[], double eps, Integer state[], double c[], Integer pdc, NagError *fail)

3 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,

nag_rand_corr_matrix (g05pyc) 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 nag_rand_orthog_matrix (g05pxc) 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 functions nag_rand_init_repeatable (g05kfc) (for a repeatable sequence if computed sequentially) or nag_rand_init_nonrepeatable (g05kgc) (for a non-repeatable sequence) must be called prior to the first call to nag_rand_corr_matrix (g05pyc).

4 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

5 Arguments

1: n – IntegerInput

On entry:

n

, the dimension of the correlation matrix to be generated.

Constraint:

n \geq 1

2: d[n] – const doubleInput

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.

3: eps – doubleInput

On entry: the maximum acceptable error in the diagonal elements.

Suggested value:

eps = 0.00001

Constraint:

eps \geq n \times machine precision

(see Chapter x02).

4: state[ $\dim$ ] – IntegerCommunication Array

Note: the actual argument supplied must be the array state supplied to the initialization functions 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: c[ $n \times pdc$ ] – doubleOutput

On exit: a random correlation matrix,

C

, of dimension

n

6: pdc – IntegerInput

On entry: the stride separating row elements of the matrix

C

in the array c.

Constraint:

pdc \geq n

7: fail – NagError *Input/Output

The NAG error argument (see Section 3.6 in the Essential Introduction).

6 Error Indicators and Warnings

NE_ALLOC_FAIL: Dynamic memory allocation failed.
NE_BAD_PARAM: On entry, argument $〈value〉$ had an illegal value.
NE_DIAG_ELEMENTS: The diagonals of the returned matrix are not unity, try increasing the value of eps, or rerun the code using a different seed.
NE_EIGVAL_SUM: On entry, the eigenvalues do not sum to n.
NE_INT: On entry, $n = 〈value〉$ .
Constraint: $n \geq 1$ .; On entry, $pdc = 〈value〉$ .
Constraint: $pdc > 0$ .
NE_INT_2: On entry, $pdc = 〈value〉$ and $n = 〈value〉$ .
Constraint: $pdc \geq n$ .
NE_INTERNAL_ERROR: An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
NE_INVALID_STATE: On entry, state vector has been corrupted or not initialized.
NE_NEGATIVE_EIGVAL: On entry, an eigenvalue is negative.
NE_REAL: On entry, $eps = 〈value〉$ .
Constraint: $eps \geq n \times machine precision$ .

7 Accuracy

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

8 Further Comments

The time taken by nag_rand_corr_matrix (g05pyc) is approximately proportional to

n^{2}

9 Example

Following initialization of the pseudorandom number generator by a call to nag_rand_init_repeatable (g05kfc), a

3

3

correlation matrix with eigenvalues of

0.7

0.9

and

1.4

is generated and printed.

NAG Library Function Documentnag_rand_corr_matrix (g05pyc)

+− Contents

1 Purpose

2 Specification

3 Description

4 References

5 Arguments

6 Error Indicators and Warnings

7 Accuracy

8 Further Comments

9 Example

9.1 Program Text

9.2 Program Data

9.3 Program Results

NAG Library Function Document

nag_rand_corr_matrix (g05pyc)