naginterfaces.library.rand.copula_​students_​t

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

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

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

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/g05/g05rcf.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 copula_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.

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 copula_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 values from a multivariate Student’s $t$ copula, 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 $5$)

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

(errno $7$)

$\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 $9$)

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

Notes

The Student’s $t$ copula, $G$, is defined by

$$G(u_1,u_2,\dots ,u_m;C)=T_{\nu ,C}^m(t_{\nu ,C_{11}}^{-1}\left(u_1\right),t_{\nu ,C_{22}}^{-1}\left(u_2\right),\dots ,t_{\nu ,C_{\text{mm}}}^{-1}\left(u_m\right))$$

where $m$ is the number of dimensions, $T_{\nu ,C}^m$ is the multivariate Student’s $t$ density function with $\nu$ degrees of freedom, mean zero and covariance matrix $\frac{\nu }{\nu -2}C$ and $t_{\nu ,C_{\text{ii}}}^{-1}$ is the inverse of the univariate Student’s $t$ density function with $\nu$ degrees of freedom, zero mean and variance $\frac{\nu }{\nu -2}{C}_{\text{ii}}$.

multivar_students_t() is used to generate a vector from a multivariate Student’s $t$ distribution and stat.prob_students_t is used to convert each element of that vector into a uniformly distributed value between zero and one.

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

References

Nelsen, R B, 1998, An Introduction to Copulas. Lecture Notes in Statistics 139, Springer

Sklar, A, 1973, Random variables: joint distribution functions and copulas, Kybernetika (9), 499–460

See also

naginterfaces.library.examples.rand.copula_students_t_ex.main()