g05py generates a random correlation matrix with given eigenvalues.

Syntax

C#
public static void g05py(
	int n,
	double[] d,
	double eps,
	G05..::..G05State g05state,
	double[,] c,
	out int ifail
)
Visual Basic
Public Shared Sub g05py ( _
	n As Integer, _
	d As Double(), _
	eps As Double, _
	g05state As G05..::..G05State, _
	c As Double(,), _
	<OutAttribute> ByRef ifail As Integer _
)
Visual C++
public:
static void g05py(
	int n, 
	array<double>^ d, 
	double eps, 
	G05..::..G05State^ g05state, 
	array<double,2>^ c, 
	[OutAttribute] int% ifail
)
F#
static member g05py : 
        n : int * 
        d : float[] * 
        eps : float * 
        g05state : G05..::..G05State * 
        c : float[,] * 
        ifail : int byref -> unit 

Parameters

n
Type: System..::..Int32
On entry: n, the dimension of the correlation matrix to be generated.
Constraint: n1.
d
Type: array<System..::..Double>[]()[][]
An array of size [n]
On entry: the n eigenvalues, λi, for i=1,2,,n.
Constraints:
  • d[i-1]0.0, for i=1,2,,n;
  • i=1nd[i-1]=n to within eps.
eps
Type: System..::..Double
On entry: the maximum acceptable error in the diagonal elements.
Suggested value: eps=0.00001.
Constraint: epsn×machine precision (see X02 class).
g05state
Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.
c
Type: array<System..::..Double,2>[,](,)[,][,]
An array of size [dim1, n]
Note: dim1 must satisfy the constraint: dim1n
On exit: a random correlation matrix, C, of dimension n.
ifail
Type: System..::..Int32%
On exit: ifail=0 unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

Description

Given n eigenvalues, λ1,λ2,,λn, such that
i=1nλi=n
and
λi0,  i=1,2,,n,
g05py will generate a random correlation matrix, C, of dimension n, with eigenvalues λ1,λ2,,λn.
The method used is based on that described by Lin and Bendel (1985). Let D be the diagonal matrix with values λ1,λ2,,λn and let A be a random orthogonal matrix generated by g05px then the matrix C0=ADAT is a random covariance matrix with eigenvalues λ1,λ2,,λn. The matrix C0 is transformed into a correlation matrix by means of n-1 elementary rotation matrices Pi such that C=Pn-1Pn-2P1C0P1TPn-2TPn-1T. The restriction on the sum of eigenvalues implies that for any diagonal element of C0>1, there is another diagonal element <1. The Pi 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 Pi which are chosen as arbitrarily as possible.
One of the initialization methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to 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

Error Indicators and Warnings

Errors or warnings detected by the method:
Some error messages may refer to parameters that are dropped from this interface (LDC) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.
ifail=1
On entry,n<1.
ifail=2
On entry,d[i-1]<0.0 for some i,
ori=1nd[i-1]n.
ifail=3
On entry,eps<n×machine precision.
ifail=4
On entry,state vector was not initialized or has been corrupted.
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 (G05KFF not in this release) (G05KGF not in this release).
ifail=-9000
An error occured, see message report.
ifail=-6000
Invalid Parameters value
ifail=-4000
Invalid dimension for array value
ifail=-8000
Negative dimension for array value
ifail=-6000
Invalid Parameters value

Accuracy

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

Parallelism and Performance

None.

Further Comments

The time taken by g05py is approximately proportional to n2.

Example

See Also