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_multivar_students_t (g05ry)

## Purpose

nag_rand_multivar_students_t (g05ry) sets up a reference vector and generates an array of pseudorandom numbers from a multivariate Student's t$t$ distribution with ν$\nu$ degrees of freedom, mean vector a$a$ and covariance matrix ν/(ν2) C $\frac{\nu }{\nu -2}C$.

## Syntax

[r, state, x, ifail] = g05ry(mode, n, df, xmu, c, r, state, 'm', m, 'lr', lr)
[r, state, x, ifail] = nag_rand_multivar_students_t(mode, n, df, xmu, c, r, state, 'm', m, 'lr', lr)

## Description

When the covariance matrix is nonsingular (i.e., strictly positive definite), the distribution has probability density function
 f(x) = ( Γ (((ν + m))/2) )/( (πv)m / 2 Γ (ν / 2) |C|(1/2) ) [1 + ( (x − a)T C − 1 (x − a) )/ν]( − (ν + m))/2 $f(x) = Γ ( (ν+m) 2 ) (πv) m/2 Γ ( ν/2 ) |C| 12 [ 1 + (x-a)T C-1 (x-a) ν ] -(ν+m) 2$
where m$m$ is the number of dimensions, ν$\nu$ is the degrees of freedom, a$a$ is the vector of means, x$x$ is the vector of positions and ν/(ν2) C $\frac{\nu }{\nu -2}C$ is the covariance matrix.
The function returns the value
 x = a + sqrt(ν/s) z $x = a + νs z$
where z$z$ is generated by nag_rand_dist_normal (g05sk) from a Normal distribution with mean zero and covariance matrix C$C$ and s$s$ is generated by nag_rand_dist_chisq (g05sd) from a χ2${\chi }^{2}$-distribution with ν$\nu$ degrees of freedom.
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_multivar_students_t (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

## Parameters

### Compulsory Input Parameters

1:     mode – int64int32nag_int scalar
A code for selecting the operation to be performed by the function.
mode = 0${\mathbf{mode}}=0$
Set up reference vector only.
mode = 1${\mathbf{mode}}=1$
Generate variates using reference vector set up in a prior call to nag_rand_multivar_students_t (g05ry).
mode = 2${\mathbf{mode}}=2$
Set up reference vector and generate variates.
Constraint: mode = 0${\mathbf{mode}}=0$, 1$1$ or 2$2$.
2:     n – int64int32nag_int scalar
n$n$, the number of random variates required.
Constraint: n0${\mathbf{n}}\ge 0$.
3:     df – int64int32nag_int scalar
ν$\nu$, the number of degrees of freedom of the distribution.
Constraint: df3 ${\mathbf{df}}\ge 3$.
4:     xmu(m) – double array
m, the dimension of the array, must satisfy the constraint m > 0${\mathbf{m}}>0$.
a$a$, the vector of means of the distribution.
5:     c(ldc,m) – double array
ldc, the first dimension of the array, must satisfy the constraint ldcm$\mathit{ldc}\ge {\mathbf{m}}$.
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.
6:     r(lr) – double array
lr, the dimension of the array, must satisfy the constraint lrm × (m + 1) + 2${\mathbf{lr}}\ge {\mathbf{m}}×\left({\mathbf{m}}+1\right)+2$.
If mode = 1${\mathbf{mode}}=1$, the reference vector as set up by nag_rand_multivar_students_t (g05ry) in a previous call with mode = 0${\mathbf{mode}}=0$ or 2$2$.
7:     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:     m – int64int32nag_int scalar
Default: The dimension of the array xmu and the first dimension of the array c and the second dimension of the array c. (An error is raised if these dimensions are not equal.)
m$m$, the number of dimensions of the distribution.
Constraint: m > 0${\mathbf{m}}>0$.
2:     lr – int64int32nag_int scalar
Default: The dimension of the array r.
The dimension of the array r as declared in the (sub)program from which nag_rand_multivar_students_t (g05ry) is called. If mode = 1${\mathbf{mode}}=1$, it must be the same as the value of lr specified in the prior call to nag_rand_multivar_students_t (g05ry) with mode = 0${\mathbf{mode}}=0$ or 2$2$.
Constraint: lrm × (m + 1) + 2${\mathbf{lr}}\ge {\mathbf{m}}×\left({\mathbf{m}}+1\right)+2$.

ldc ldx

### Output Parameters

1:     r(lr) – double array
If mode = 0${\mathbf{mode}}=0$ or 2$2$, the reference vector that can be used in subsequent calls to nag_rand_multivar_students_t (g05ry) with mode = 1${\mathbf{mode}}=1$.
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 updated information on the state of the generator.
3:     x(ldx,m) – double array
ldxn$\mathit{ldx}\ge {\mathbf{n}}$.
The array of pseudorandom multivariate Student's t$t$ vectors generated by the function, with x(i,j)${\mathbf{x}}\left(i,j\right)$ holding the j$j$th dimension for the i$i$th variate.
4:     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, mode0${\mathbf{mode}}\ne 0$, 1$1$ or 2$2$.
ifail = 2${\mathbf{ifail}}=2$
On entry, n < 0${\mathbf{n}}<0$.
ifail = 3${\mathbf{ifail}}=3$
On entry, df2${\mathbf{df}}\le 2$.
ifail = 4${\mathbf{ifail}}=4$
On entry, m < 1${\mathbf{m}}<1$.
ifail = 6${\mathbf{ifail}}=6$
The covariance matrix c is not positive semidefinite to machine precision.
ifail = 7${\mathbf{ifail}}=7$
On entry, ldc < m$\mathit{ldc}<{\mathbf{m}}$.
ifail = 8${\mathbf{ifail}}=8$
The reference vector r has been corrupted or m has changed since r was set up in a previous call to nag_rand_multivar_students_t (g05ry) with mode = 0${\mathbf{mode}}=0$ or 2$2$.
ifail = 9${\mathbf{ifail}}=9$
On entry, lrm × (m + 1) + 1${\mathbf{lr}}\le {\mathbf{m}}×\left({\mathbf{m}}+1\right)+1$.
ifail = 10${\mathbf{ifail}}=10$
 On entry, state vector was not initialized or has been corrupted.
ifail = 12${\mathbf{ifail}}=12$
On entry, ldx < n$\mathit{ldx}<{\mathbf{n}}$.

## Accuracy

Not applicable.

The time taken by nag_rand_multivar_students_t (g05ry) is of order nm3$n{m}^{3}$.
It is recommended that the diagonal elements of C$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 = LLT$C+E=L{L}^{\mathrm{T}}$, where E$E$ is a diagonal matrix with small positive diagonal elements. This ensures that, even when C$C$ is singular, or nearly singular, the Cholesky factor L$L$ corresponds to a positive definite covariance matrix that agrees with C$C$ within machine precision.

## Example

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

mode = int64(2);
n = int64(10);
df = int64(10);
xmu = [1; 2; -3; 0];
c = [1.69, 0.39, -1.86, 0.07;
0, 98.01, -7.07, -0.71;
0, 0, 11.56, 0.03;
0, 0, 0, 0.01];
r = zeros(32, 1);
% Initialize the generator to a repeatable sequence
[state, ifail] = nag_rand_init_repeat(genid, subid, seed);
[r, state, x, ifail] = nag_rand_multivar_students_t(mode, n, df, xmu, c, r, state)
```
```

r =

4.5000
1.3000
0.3000
-1.4308
0.0538
0
9.8955
-0.6711
-0.0734
0
0
3.0104
0.0192
0
0
0
0.0367
1.0000
2.0000
-3.0000
0
10.5000
0
0
0
0
0
0
0
0
0
0

state =

17
1234
1
0
8662
18721
15161
5250
17917
13895
19930
8
0
1234
1
1
1234

x =

1.4957  -15.6226   -3.8101    0.1294
-1.0827   -6.7473    0.6696   -0.0391
2.1369    6.3861   -5.7413    0.0140
2.2481  -16.0417   -1.0982    0.1641
-0.2550    3.5166   -0.2541   -0.0592
0.9731   -4.3553   -4.4181    0.0043
0.7098   -3.4281    1.1741    0.0586
1.8827   23.2619    1.5140   -0.0704
0.9904   22.7479    0.1811   -0.0893
1.5026    2.7753   -2.2805   -0.0112

ifail =

0

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

mode = int64(2);
n = int64(10);
df = int64(10);
xmu = [1; 2; -3; 0];
c = [1.69, 0.39, -1.86, 0.07;
0, 98.01, -7.07, -0.71;
0, 0, 11.56, 0.03;
0, 0, 0, 0.01];
r = zeros(32, 1);
% Initialize the generator to a repeatable sequence
[state, ifail] = g05kf(genid, subid, seed);
[r, state, x, ifail] = g05ry(mode, n, df, xmu, c, r, state)
```
```

r =

4.5000
1.3000
0.3000
-1.4308
0.0538
0
9.8955
-0.6711
-0.0734
0
0
3.0104
0.0192
0
0
0
0.0367
1.0000
2.0000
-3.0000
0
10.5000
0
0
0
0
0
0
0
0
0
0

state =

17
1234
1
0
8662
18721
15161
5250
17917
13895
19930
8
0
1234
1
1
1234

x =

1.4957  -15.6226   -3.8101    0.1294
-1.0827   -6.7473    0.6696   -0.0391
2.1369    6.3861   -5.7413    0.0140
2.2481  -16.0417   -1.0982    0.1641
-0.2550    3.5166   -0.2541   -0.0592
0.9731   -4.3553   -4.4181    0.0043
0.7098   -3.4281    1.1741    0.0586
1.8827   23.2619    1.5140   -0.0704
0.9904   22.7479    0.1811   -0.0893
1.5026    2.7753   -2.2805   -0.0112

ifail =

0

```