NAG Library Function Document

nag_rngs_corr_matrix (g05qbc)

+− 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_rngs_corr_matrix (g05qbc) generates a random correlation matrix with given eigenvalues.

2 Specification

#include <nag.h>

#include <nagg05.h>

void	nag_rngs_corr_matrix (Nag_OrderType order, Integer n, const double d[], double c[], Integer pdc, double eps, Integer igen, Integer iseed[], 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_rngs_corr_matrix (g05qbc) 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_rngs_orthog_matrix (g05qac) 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_rngs_init_repeatable (g05kbc) (for a repeatable sequence if computed sequentially) or nag_rngs_init_nonrepeatable (g05kcc) (for a non-repeatable sequence) must be called prior to the first call to nag_rngs_corr_matrix (g05qbc).

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: order – Nag_OrderTypeInput

On entry: the order argument specifies the two-dimensional storage scheme being used, i.e., row-major ordering or column-major ordering. C language defined storage is specified by

order = Nag_RowMajor

. See Section 3.2.1.3 in the Essential Introduction for a more detailed explanation of the use of this argument.

Constraint:

order = Nag_RowMajor

or Nag_ColMajor.

2: n – IntegerInput

On entry:

n

, the dimension of the correlation matrix to be generated.

Constraint:

n \geq 1

3: 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.

4: c[ $\dim$ ] – doubleOutput

Note: the dimension, dim, of the array c must be at least

pdc \times n

The

(i, j)

th element of the matrix

C

is stored in

$c [(j - 1) \times pdc + i - 1]$ when $order = Nag_ColMajor$ ;
$c [(i - 1) \times pdc + j - 1]$ when $order = Nag_RowMajor$ .

On exit: a random correlation matrix,

C

, of dimension

n

5: pdc – IntegerInput

On entry: the stride separating row or column elements (depending on the value of order) in the array c.

Constraint:

pdc \geq n

6: 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).

7: igen – IntegerInput

On entry: must contain the identification number for the generator to be used to return a pseudorandom number and should remain unchanged following initialization by a prior call to nag_rngs_init_repeatable (g05kbc) or nag_rngs_init_nonrepeatable (g05kcc).

8: iseed[ $4$ ] – IntegerCommunication Array

On entry: contains values which define the current state of the selected generator.

On exit: contains updated values defining the new state of the selected generator.

9: 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 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 nag_rngs_init_repeatable (g05kbc) or nag_rngs_init_nonrepeatable (g05kcc).
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_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_rngs_corr_matrix (g05qbc) is approximately proportional to

n^{2}

9 Example

Following initialization of the pseudorandom number generator by a call to nag_rngs_init_repeatable (g05kbc), a

3

3

correlation matrix with eigenvalues of

0.7

0.9

and

1.4

is generated and printed.

NAG Library Function Documentnag_rngs_corr_matrix (g05qbc)

+− 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_rngs_corr_matrix (g05qbc)