naginterfaces.library.rand.copula_​normal

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

copula_normal sets up a reference vector and generates an array of pseudorandom numbers from a Normal (Gaussian) copula with covariance matrix $C$.

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

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

$mode=2$

Set up reference vector and generate variates.

nint

$n$, the number of random variates required.

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

The covariance matrix 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_normal.

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 Gaussian 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, $m=⟨value⟩$.

Constraint: $m>0$.

(errno $4$)

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

(errno $6$)

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

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

Notes

The Gaussian copula, $G$, is defined by

$$G(u_1,u_2,\dots ,u_m;C)={\Phi }_C({\varphi }_{C_{11}}^{-1}\left(u_1\right),{\varphi }_{C_{22}}^{-1}\left(u_2\right),\dots ,{\varphi }_{C_{\text{mm}}}^{-1}\left(u_m\right))$$

where $m$ is the number of dimensions, ${\Phi }_C$ is the multivariate Normal density function with mean zero and covariance matrix $C$ and ${\varphi }_{C_{\text{ii}}}^{-1}$ is the inverse of the univariate Normal density function with mean zero and variance $C_{\text{ii}}$.

multivar_normal() is used to generate a vector from a multivariate Normal distribution and stat.prob_normal 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_normal.

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