naginterfaces.library.rand.copula_​plackett_​bivar

naginterfaces.library.rand.copula_plackett_bivar(n, theta, sorder, statecomm)

copula_plackett_bivar generates pseudorandom uniform bivariates with joint distribution of a Plackett copula.

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

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

Parameters

nint

$n$, the number of bivariates to generate.

thetafloat

$\theta$, the copula parameter.

sorderint

Determines the storage order of variates; the $(\text{i},\text{j})$th variate is stored in $x[\text{i}-1,\text{j}-1]$ if $sorder=1$, and $x[\text{j}-1,\text{i}-1]$ if $sorder=2$, for $\text{j}=1,2,\dots ,2$, for $\text{i}=1,2,\dots ,n$.

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

xfloat, ndarray, shape $(:,:)$

The $n$ bivariate uniforms with joint distribution described by $C_{\theta }$, with $x[i-1,j-1]$ holding the $i$th value for the $j$th dimension if $sorder=1$ and the $j$th value for the $i$th dimension if $sorder=2$.

Raises

NagValueError

(errno $1$)

On entry, corrupt $statecomm$[‘state’] argument.

(errno $2$)

On entry, invalid $theta$: $theta=⟨value⟩$.

Constraint: $theta\ge 0.0$.

(errno $3$)

On entry, $n=⟨value⟩$.

Constraint: $n\ge 0$.

(errno $4$)

On entry, invalid $sorder$.

Constraint: $sorder=1$ or $2$.

Notes

Generates pseudorandom uniform bivariates $\{u_1,u_2\}\in {[0,1]}^2$ whose joint distribution is the Plackett copula $C_{\theta }$ with parameter $\theta$, given by

$$C_{\theta }=\frac{[1+(\theta -1)(u_1+u_2)]-\sqrt{{[1+(\theta -1)(u_1+u_2)]}^2-4u_1{u}_2\theta (\theta -1)}}{2(\theta -1)}\text{,}\theta \in (0,\infty )\setminus \left\{1\right\}$$

with the special cases:

$C_0=max(u_1+u_2-1,0)$, the Fréchet–Hoeffding lower bound;

$C_1=u_1{u}_2$, the product copula;

$C_{\infty }=min(u_1,u_2)$, the Fréchet–Hoeffding upper bound.

The generation method uses conditional sampling.

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

References

Nelsen, R B, 2006, An Introduction to Copulas, (2nd Edition), Springer Series in Statistics