g05ry sets up a reference vector and generates an array of pseudorandom numbers from a multivariate Student's

t

distribution with

ν

degrees of freedom, mean vector

a

and covariance matrix

\frac{ν}{ν - 2} C

Syntax

C#
public static void g05ry( int mode, int n, int df, int m, double[] xmu, double[,] c, double[] r, G05..::..G05State g05state, double[,] x, out int ifail )

Visual Basic
Public Shared Sub g05ry ( _ mode As Integer, _ n As Integer, _ df As Integer, _ m As Integer, _ xmu As Double(), _ c As Double(,), _ r As Double(), _ g05state As G05..::..G05State, _ x As Double(,), _ <OutAttribute> ByRef ifail As Integer _ )

Visual Basic

Public Shared Sub g05ry ( _
	mode As Integer, _
	n As Integer, _
	df As Integer, _
	m As Integer, _
	xmu As Double(), _
	c As Double(,), _
	r As Double(), _
	g05state As G05..::..G05State, _
	x As Double(,), _
	<OutAttribute> ByRef ifail As Integer _
)

Visual C++
public: static void g05ry( int mode, int n, int df, int m, array<double>^ xmu, array<double,2>^ c, array<double>^ r, G05..::..G05State^ g05state, array<double,2>^ x, [OutAttribute] int% ifail )

F#
static member g05ry : mode : int * n : int * df : int * m : int * xmu : float[] * c : float[,] * r : float[] * g05state : G05..::..G05State * x : float[,] * ifail : int byref -> unit

Parameters

mode

Type: System..::..Int32

On entry: a code for selecting the operation to be performed by the method.

$mode = 0$: Set up reference vector only.
$mode = 1$: Generate variates using reference vector set up in a prior call to g05ry.
$mode = 2$: Set up reference vector and generate variates.

Constraint:

mode = 0

1

2

n: Type: System..::..Int32
On entry: $n$ , the number of random variates required.

Constraint: $n \geq 0$ .

df: Type: System..::..Int32
On entry: $ν$ , the number of degrees of freedom of the distribution.

Constraint: $df \geq 3$ .

m: Type: System..::..Int32
On entry: $m$ , the number of dimensions of the distribution.

Constraint: $m > 0$ .

xmu: Type: array<System..::..Double>[]()[][]
An array of size [m]
On entry: $a$ , the vector of means of the distribution.

c: Type: array<System..::..Double,2>[,](,)[,][,]
An array of size [dim1, m]
Note: dim1 must satisfy the constraint: $dim1 \geq m$
On entry: matrix which, along with df, defines the covariance of the distribution. Only the upper triangle need be set.

Constraint: c must be positive semidefinite to machine precision.

r: Type: array<System..::..Double>[]()[][]
An array of size [lr]
On entry: if $mode = 1$ , the reference vector as set up by g05ry in a previous call with $mode = 0$ or $2$ .
On exit: if $mode = 0$ or $2$ , the reference vector that can be used in subsequent calls to g05ry with $mode = 1$ .

g05state: Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.

x: Type: array<System..::..Double,2>[,](,)[,][,]
An array of size [dim1, _tdx]
Note: dim1 must satisfy the constraint: $dim1 \geq n$
On exit: the array of pseudorandom multivariate Student's $t$ vectors generated by the method, with $x [i - 1, j - 1]$ holding the $j$ th dimension for the $i$ th variate.

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

When the covariance matrix is nonsingular (i.e., strictly positive definite), the distribution has probability density function

f (x) = \frac{Γ (\frac{(ν + m)}{2})}{{(π v)}^{m / 2} Γ (ν / 2) {|C|}^{\frac{1}{2}}} {[1 + \frac{{(x - a)}^{T} C^{- 1} (x - a)}{ν}]}^{\frac{- (ν + m)}{2}}

where

m

is the number of dimensions,

ν

is the degrees of freedom,

a

is the vector of means,

x

is the vector of positions and

\frac{ν}{ν - 2} C

is the covariance matrix.

The method returns the value

x = a + \sqrt{\frac{ν}{s}} z

where

z

is generated by g05sk from a Normal distribution with mean zero and covariance matrix

C

and

s

is generated by g05sd from a

χ^{2}

-distribution with

ν

degrees of freedom.

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 g05ry.

References

Knuth D E (1981) The Art of Computer Programming (Volume 2) (2nd Edition) Addison–Wesley

Wilkinson J H (1965) The Algebraic Eigenvalue Problem Oxford University Press, Oxford

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, LDX) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.

$ifail = 1$: On entry, $mode \neq 0$ , $1$ or $2$ .

$ifail = 2$: On entry, $n < 0$ .

$ifail = 3$: On entry, $df \leq 2$ .

$ifail = 4$: On entry, $m < 1$ .

$ifail = 6$: The covariance matrix c is not positive semidefinite to machine precision.

$ifail = 7$: On entry, $ldc < m$ .

$ifail = 8$: The reference vector r has been corrupted or m has changed since r was set up in a previous call to g05ry with $mode = 0$ or $2$ .

$ifail = 9$: On entry, $lr \leq m \times (m + 1) + 1$ .

$ifail = 10$

On entry,

state vector was not initialized or has been corrupted.

$ifail = 12$: On entry, $ldx < n$ .

$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

Not applicable.

Parallelism and Performance

None.

Further Comments

The time taken by g05ry is of order

n m^{3}

It is recommended that the diagonal elements of

C

should not differ too widely in order of magnitude. This may be achieved by scaling the variables if necessary. The actual matrix decomposed is

C + E = L L^{T}

, where

E

is a diagonal matrix with small positive diagonal elements. This ensures that, even when

C

is singular, or nearly singular, the Cholesky factor

L

corresponds to a positive definite covariance matrix that agrees with

C

within machine precision.

Example

Example program (C#): g05rye.cs

Example program data: g05rye.d

Example program results: g05rye.r