Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_rand_matrix_corr (g05py)

## Purpose

nag_rand_matrix_corr (g05py) generates a random correlation matrix with given eigenvalues.

## Syntax

[state, c, ifail] = g05py(d, state, 'n', n, 'eps', eps)
[state, c, ifail] = nag_rand_matrix_corr(d, state, 'n', n, 'eps', eps)

## Description

Given n$n$ eigenvalues, λ1,λ2,,λn${\lambda }_{1},{\lambda }_{2},\dots ,{\lambda }_{n}$, such that
 n ∑ λi = n i = 1
$∑i=1nλi=n$
and
 λi ≥ 0,   i = 1,2, … ,n, $λi≥ 0, i= 1,2,…,n,$
nag_rand_matrix_corr (g05py) will generate a random correlation matrix, C$C$, of dimension n$n$, with eigenvalues λ1,λ2,,λn${\lambda }_{1},{\lambda }_{2},\dots ,{\lambda }_{n}$.
The method used is based on that described by Lin and Bendel (1985). Let D$D$ be the diagonal matrix with values λ1,λ2,,λn${\lambda }_{1},{\lambda }_{2},\dots ,{\lambda }_{n}$ and let A$A$ be a random orthogonal matrix generated by nag_rand_matrix_orthog (g05px) then the matrix C0 = A D AT${C}_{0}=AD{A}^{\mathrm{T}}$ is a random covariance matrix with eigenvalues λ1,λ2,,λn${\lambda }_{1},{\lambda }_{2},\dots ,{\lambda }_{n}$. The matrix C0${C}_{0}$ is transformed into a correlation matrix by means of n1$n-1$ elementary rotation matrices Pi${P}_{i}$ such that C = Pn1 Pn2 P1 C0 P1T Pn2T Pn1T $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 C0 > 1${C}_{0}>1$, there is another diagonal element < 1$\text{}<1$. The Pi${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$1$ to within a given tolerance ε$\epsilon$.
The randomness of C$C$ should be interpreted only to the extent that A$A$ is a random orthogonal matrix and C$C$ is computed from A$A$ using the Pi${P}_{i}$ which are chosen as arbitrarily as possible.
One of the initialization functions nag_rand_init_repeat (g05kf) (for a repeatable sequence if computed sequentially) or nag_rand_init_nonrepeat (g05kg) (for a non-repeatable sequence) must be called prior to the first call to nag_rand_matrix_corr (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

## Parameters

### Compulsory Input Parameters

1:     d(n) – double array
n, the dimension of the array, must satisfy the constraint n1${\mathbf{n}}\ge 1$.
The n$n$ eigenvalues, λi${\lambda }_{\mathit{i}}$, for i = 1,2,,n$\mathit{i}=1,2,\dots ,n$.
Constraints:
• d(i)0.0${\mathbf{d}}\left(\mathit{i}\right)\ge 0.0$, for i = 1,2,,n$\mathit{i}=1,2,\dots ,n$;
• i = 1nd(i) = n$\sum _{i=1}^{n}{\mathbf{d}}\left(i\right)=n$ to within eps.
2:     state( : $:$) – int64int32nag_int array
Note: the actual argument supplied must be the array state supplied to the initialization routines nag_rand_init_repeat (g05kf) or nag_rand_init_nonrepeat (g05kg).
Contains information on the selected base generator and its current state.

### Optional Input Parameters

1:     n – int64int32nag_int scalar
Default: The dimension of the array d.
n$n$, the dimension of the correlation matrix to be generated.
Constraint: n1${\mathbf{n}}\ge 1$.
2:     eps – double scalar
The maximum acceptable error in the diagonal elements.
Default: 0.00001$0.00001$
Constraint: epsn × machine precision (see Chapter X02).

ldc

### Output Parameters

1:     state( : $:$) – int64int32nag_int array
Note: the actual argument supplied must be the array state supplied to the initialization routines nag_rand_init_repeat (g05kf) or nag_rand_init_nonrepeat (g05kg).
Contains updated information on the state of the generator.
2:     c(ldc,n) – double array
ldcn$\mathit{ldc}\ge {\mathbf{n}}$.
A random correlation matrix, C$C$, of dimension n$n$.
3:     ifail – int64int32nag_int scalar
${\mathrm{ifail}}={\mathbf{0}}$ unless the function detects an error (see [Error Indicators and Warnings]).

## Error Indicators and Warnings

Errors or warnings detected by the function:
ifail = 1${\mathbf{ifail}}=1$
 On entry, n < 1${\mathbf{n}}<1$.
ifail = 2${\mathbf{ifail}}=2$
 On entry, d(i) < 0.0${\mathbf{d}}\left(i\right)<0.0$ for some i$i$, or ∑ i = 1n d(i) ≠ n$\sum _{i=1}^{n}{\mathbf{d}}\left(i\right)\ne n$.
ifail = 3${\mathbf{ifail}}=3$
 On entry, eps < n × machine precision.
ifail = 4${\mathbf{ifail}}=4$
 On entry, state vector was not initialized or has been corrupted.
ifail = 5${\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 nag_rand_init_repeat (g05kf) or nag_rand_init_nonrepeat (g05kg).
ifail = 6${\mathbf{ifail}}=6$
 On entry, ldc < n$\mathit{ldc}<{\mathbf{n}}$.

## Accuracy

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

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

## Example

```function nag_rand_matrix_corr_example
% Initialize the seed
seed = [int64(1762543)];
% genid and subid identify the base generator
genid = int64(1);
subid =  int64(1);

d = [0.7; 0.9; 1.4];
% Initialize the generator to a repeatable sequence
[state, ifail] = nag_rand_init_repeat(genid, subid, seed);
[state, c, ifail] = nag_rand_matrix_corr(d, state)
```
```

state =

17
1234
1
0
9910
16740
20386
10757
17917
13895
19930
8
0
1234
1
1
1234

c =

1.0000   -0.2549   -0.1004
-0.2549    1.0000    0.2343
-0.1004    0.2343    1.0000

ifail =

0

```
```function g05py_example
% Initialize the seed
seed = [int64(1762543)];
% genid and subid identify the base generator
genid = int64(1);
subid =  int64(1);

d = [0.7; 0.9; 1.4];
% Initialize the generator to a repeatable sequence
[state, ifail] = g05kf(genid, subid, seed);
[state, c, ifail] = g05py(d, state)
```
```

state =

17
1234
1
0
9910
16740
20386
10757
17917
13895
19930
8
0
1234
1
1
1234

c =

1.0000   -0.2549   -0.1004
-0.2549    1.0000    0.2343
-0.1004    0.2343    1.0000

ifail =

0

```