naginterfaces.library.rand.multivar_​students_​t

naginterfaces.library.rand.multivar_students_t(mode, n, df, xmu, c, comm, statecomm)

multivar_students_t sets up a reference vector and generates an array of pseudorandom numbers from a multivariate Student’s $t$ distribution with $\nu$ degrees of freedom, mean vector $a$ and covariance matrix $\frac{\nu }{\nu -2}C$.

For full information please refer to the NAG Library document for g05ry

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/g05/g05ryf.html

Parameters

modeint

A code for selecting the operation to be performed by the function.

$mode=0$

Set up reference vector only.

$mode=1$

Generate variates using reference vector set up in a prior call to multivar_students_t.

$mode=2$

Set up reference vector and generate variates.

nint

$n$, the number of random variates required.

dfint

$\nu$, the number of degrees of freedom of the distribution.

xmufloat, array-like, shape $\left(m\right)$

$a$, the vector of means of the distribution.

cfloat, array-like, shape $(m,m)$

Matrix which, along with $df$, defines the covariance of the distribution. Only the upper triangle need be set.

commdict, communication object, modified in place

Communication structure for the reference vector.

If $mode=1$, this argument must have been initialized by a prior call to multivar_students_t.

statecommdict, RNG communication object, modified in place

RNG communication structure.

This argument must have been initialized by a prior call to init_repeat() or init_nonrepeat().

Returns

xNone or float, ndarray, shape $(n,:)$

The array of pseudorandom multivariate Student’s $t$ vectors generated by the function, with $x[i-1,j-1]$ holding the $j$th dimension for the $i$th variate.

Raises

NagValueError

(errno $1$)

On entry, $mode=⟨value⟩$.

Constraint: $mode=0$, $1$ or $2$.

(errno $2$)

On entry, $n=⟨value⟩$.

Constraint: $n\ge 0$.

(errno $3$)

On entry, $df=⟨value⟩$.

Constraint: $df\ge 3$.

(errno $4$)

On entry, $m=⟨value⟩$.

Constraint: $m>0$.

(errno $6$)

On entry, the covariance matrix $C$ is not positive semidefinite to machine precision.

(errno $8$)

$\text{m}$ is not the same as when $comm$[‘r’] was set up in a previous call.

Previous value of $m=⟨value⟩$ and $m=⟨value⟩$.

(errno $10$)

On entry, $statecomm$[‘state’] vector has been corrupted or not initialized.

Notes

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

$$f\left(x\right)=\frac{\Gamma \left(\frac{(\nu +m)}{2}\right)}{{\left(\pi v\right)}^{m/2}\Gamma \left(\nu /2\right){\left|C\right|}^{\frac{1}{2}}}{[1+\frac{{(x-a)}^T{C}^{-1}(x-a)}{\nu }]}^{\frac{-(\nu +m)}{2}}$$

where $m$ is the number of dimensions, $\nu$ is the degrees of freedom, $a$ is the vector of means, $x$ is the vector of positions and $\frac{\nu }{\nu -2}C$ is the covariance matrix.

The function returns the value

$$x=a+\sqrt{\frac{\nu }{s}}z$$

where $z$ is generated by dist_normal() from a Normal distribution with mean zero and covariance matrix $C$ and $s$ is generated by dist_chisq() from a ${\chi }^2$-distribution with $\nu$ degrees of freedom.

One of the initialization functions init_repeat() (for a repeatable sequence if computed sequentially) or init_nonrepeat() (for a non-repeatable sequence) must be called prior to the first call to multivar_students_t.

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