hide long namesshow long names
hide short namesshow short names
Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

PDF version (NAG web site, 64-bit version, 64-bit version)
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 nn eigenvalues, λ1,λ2,,λnλ1,λ2,,λ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, CC, of dimension nn, with eigenvalues λ1,λ2,,λnλ1,λ2,,λn.
The method used is based on that described by Lin and Bendel (1985). Let DD be the diagonal matrix with values λ1,λ2,,λnλ1,λ2,,λn and let AA be a random orthogonal matrix generated by nag_rand_matrix_orthog (g05px) then the matrix C0 = A D ATC0=A D AT is a random covariance matrix with eigenvalues λ1,λ2,,λnλ1,λ2,,λn. The matrix C0C0 is transformed into a correlation matrix by means of n1n-1 elementary rotation matrices PiPi such that C = Pn1 Pn2 P1 C0 P1T Pn2T Pn1T C = Pn-1 Pn-2 P1 C0 P1T Pn-2T Pn-1T . The restriction on the sum of eigenvalues implies that for any diagonal element of C0 > 1C0>1, there is another diagonal element < 1<1. The PiPi 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 11 to within a given tolerance εε.
The randomness of CC should be interpreted only to the extent that AA is a random orthogonal matrix and CC is computed from AA using the PiPi 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 n1n1.
The nn eigenvalues, λiλi, for i = 1,2,,ni=1,2,,n.
Constraints:
  • d(i)0.0di0.0, for i = 1,2,,ni=1,2,,n;
  • i = 1nd(i) = ni=1ndi=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.
nn, the dimension of the correlation matrix to be generated.
Constraint: n1n1.
2:     eps – double scalar
The maximum acceptable error in the diagonal elements.
Default: 0.000010.00001
Constraint: epsn × machine precisionepsn×machine precision (see Chapter X02).

Input Parameters Omitted from the MATLAB Interface

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
ldcnldcn.
A random correlation matrix, CC, of dimension nn.
3:     ifail – int64int32nag_int scalar
ifail = 0ifail=0 unless the function detects an error (see [Error Indicators and Warnings]).

Error Indicators and Warnings

Errors or warnings detected by the function:
  ifail = 1ifail=1
On entry,n < 1n<1.
  ifail = 2ifail=2
On entry,d(i) < 0.0di<0.0 for some ii,
ori = 1n d(i)ni=1n din.
  ifail = 3ifail=3
On entry,eps < n × machine precisioneps<n×machine precision.
  ifail = 4ifail=4
On entry,state vector was not initialized or has been corrupted.
  ifail = 5ifail=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 = 6ifail=6
On entry,ldc < nldc<n.

Accuracy

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

Further Comments

The time taken by nag_rand_matrix_corr (g05py) is approximately proportional to n2n2.

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



PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

© The Numerical Algorithms Group Ltd, Oxford, UK. 2009–2013