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$ eigenvalues, ${\lambda }_{1},{\lambda }_{2},\dots ,{\lambda }_{n}$, such that
 $∑i=1nλi=n$
and
 $λi≥ 0, i= 1,2,…,n,$
nag_rand_matrix_corr (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 nag_rand_matrix_orthog (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 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:     $\mathrm{d}\left({\mathbf{n}}\right)$ – double array
The $n$ eigenvalues, ${\lambda }_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,n$.
Constraints:
• ${\mathbf{d}}\left(\mathit{i}\right)\ge 0.0$, for $\mathit{i}=1,2,\dots ,n$;
• $\sum _{i=1}^{n}{\mathbf{d}}\left(i\right)=n$ to within eps.
2:     $\mathrm{state}\left(:\right)$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:     $\mathrm{n}$int64int32nag_int scalar
Default: the dimension of the array d.
$n$, the dimension of the correlation matrix to be generated.
Constraint: ${\mathbf{n}}\ge 1$.
2:     $\mathrm{eps}$ – double scalar
Default: $0.00001$
The maximum acceptable error in the diagonal elements.
Constraint:  (see Chapter X02).

### Output Parameters

1:     $\mathrm{state}\left(:\right)$int64int32nag_int array
Contains updated information on the state of the generator.
2:     $\mathrm{c}\left(\mathit{ldc},{\mathbf{n}}\right)$ – double array
A random correlation matrix, $C$, of dimension $n$.
3:     $\mathrm{ifail}$int64int32nag_int scalar
${\mathbf{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:
${\mathbf{ifail}}=1$
Constraint: ${\mathbf{n}}\ge 1$.
${\mathbf{ifail}}=2$
On entry, an eigenvalue is negative.
On entry, the eigenvalues do not sum to n.
${\mathbf{ifail}}=3$
Constraint: .
${\mathbf{ifail}}=4$
On entry, state vector has been corrupted or not initialized.
${\mathbf{ifail}}=5$
The diagonals of the returned matrix are not unity, try increasing the value of eps, or rerun the code using a different seed.
${\mathbf{ifail}}=6$
Constraint: $\mathit{ldc}\ge {\mathbf{n}}$.
${\mathbf{ifail}}=-99$
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.

## 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 ${n}^{2}$.

## Example

Following initialization of the pseudorandom number generator by a call to nag_rand_init_repeat (g05kf), a $3$ by $3$ correlation matrix with eigenvalues of $0.7$, $0.9$ and $1.4$ is generated and printed.
```function g05py_example

fprintf('g05py example results\n\n');

% Initialize the base generator to a repeatable sequence
seed  = [int64(1762543)];
genid = int64(1);
subid = int64(1);
[state, ifail] = g05kf( ...
genid, subid, seed);

% Eigenvalues
d = [0.7; 0.9; 1.4];

% Generate the correlation matrix with eigenvalues d
[state, c, ifail] = g05py( ...
d, state);

disp('Correlation Matrix');
disp(c);

```
```g05py example results

Correlation Matrix
1.0000   -0.2549   -0.1004
-0.2549    1.0000    0.2343
-0.1004    0.2343    1.0000

```