Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_rand_copula_plackett_bivar (g05rg)

## Purpose

nag_rand_copula_plackett_bivar (g05rg) generates pseudorandom uniform bivariates with joint distribution of a Plackett copula.

## Syntax

[state, x, ifail] = g05rg(n, theta, sorder, state)
[state, x, ifail] = nag_rand_copula_plackett_bivar(n, theta, sorder, state)

## Description

Generates pseudorandom uniform bivariates $\left\{{u}_{1},{u}_{2}\right\}\in {\left[0,1\right]}^{2}$ whose joint distribution is the Plackett copula ${C}_{\theta }$ with parameter $\theta$, given by
 $Cθ = 1 + θ-1 u1 + u2 - 1 + θ-1 u1 + u2 2 - 4 u1 u2 θ θ-1 2θ-1 , θ ∈ 0,∞ ∖ 1$
with the special cases:
• ${C}_{0}=\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({u}_{1}+{u}_{2}-1,0\right)$, the Fréchet–Hoeffding lower bound;
• ${C}_{1}={u}_{1}{u}_{2}$, the product copula;
• ${C}_{\infty }=\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left({u}_{1},{u}_{2}\right)$, the Fréchet–Hoeffding upper bound.
The generation method uses conditional sampling.
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_copula_plackett_bivar (g05rg).

## References

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

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{n}$int64int32nag_int scalar
$n$, the number of bivariates to generate.
Constraint: ${\mathbf{n}}\ge 0$.
2:     $\mathrm{theta}$ – double scalar
$\theta$, the copula parameter.
Constraint: ${\mathbf{theta}}\ge 0.0$.
3:     $\mathrm{sorder}$int64int32nag_int scalar
Determines the storage order of variates; the $\left(\mathit{i},\mathit{j}\right)$th variate is stored in ${\mathbf{x}}\left(\mathit{i},\mathit{j}\right)$ if ${\mathbf{sorder}}=1$, and ${\mathbf{x}}\left(\mathit{j},\mathit{i}\right)$ if ${\mathbf{sorder}}=2$, for $\mathit{i}=1,2,\dots ,n$ and $\mathit{j}=1,2$.
Constraint: ${\mathbf{sorder}}=1$ or $2$.
4:     $\mathrm{state}\left(:\right)$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.

None.

### Output Parameters

1:     $\mathrm{state}\left(:\right)$int64int32nag_int array
Contains updated information on the state of the generator.
2:     $\mathrm{x}\left(\mathit{ldx},\mathit{sdx}\right)$ – double array
The $n$ bivariate uniforms with joint distribution described by ${C}_{\theta }$, with ${\mathbf{x}}\left(i,j\right)$ holding the $i$th value for the $j$th dimension if ${\mathbf{sorder}}=1$ and the $j$th value for the $i$th dimension if ${\mathbf{sorder}}=2$.
3:     $\mathrm{ifail}$int64int32nag_int scalar
${\mathbf{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:
${\mathbf{ifail}}=1$
On entry, corrupt state argument.
${\mathbf{ifail}}=2$
Constraint: ${\mathbf{theta}}\ge 0.0$.
${\mathbf{ifail}}=3$
Constraint: ${\mathbf{n}}\ge 0$.
${\mathbf{ifail}}=4$
On entry, invalid sorder.
Constraint: ${\mathbf{sorder}}=1$ or $2$.
${\mathbf{ifail}}=6$
On entry, ldx is too small: $\mathit{ldx}=_$.
${\mathbf{ifail}}=7$
On entry, sdx is too small: $\mathit{sdx}=_$.
${\mathbf{ifail}}=-99$
An unexpected error has been triggered by this routine. Please contact NAG.
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.

Not applicable.

## Further Comments

In practice, the need for numerical stability restricts the range of $\theta$ such that:
• if $\theta <{\epsilon }_{s}$, the function returns pseudorandom uniform variates with ${C}_{0}$ joint distribution;
• if $\left|\theta -1\right|<\epsilon$, the function returns pseudorandom uniform variates with ${C}_{1}$ joint distribution;
• if $\theta >{\epsilon }_{s}^{-1/2}$, the function returns pseudorandom uniform variates with ${C}_{\infty }$ joint distribution;
where ${\epsilon }_{s}$ is the safe-range parameter, the value of which is returned by nag_machine_real_safe (x02am); and $\epsilon$ is the machine precision returned by nag_machine_precision (x02aj).

## Example

This example generates thirteen variates for copula ${C}_{2.0}$.
```function g05rg_example

fprintf('g05rg example results\n\n');

% Initialize the base generator to a repeatable sequence
seed  = [int64(1762543)];
genid = int64(1);
subid = int64(1);
[state, ifail] = g05kf( ...
genid, subid, seed);

% Sample size and order
n      = int64(13);
sorder = int64(1);

% Parameter
theta = 2;

% Generate variates
[state, x, ifail] = g05rg( ...
n, theta, sorder, state);

disp('Variates from a bivariate Plackett copula');
disp(x);

```
```g05rg example results

Variates from a bivariate Plackett copula
0.6364    0.0695
0.1065    0.4586
0.7460    0.3586
0.7983    0.3267
0.1046    0.9888
0.4925    0.8920
0.3843    0.4903
0.7871    0.4248
0.4982    0.5783
0.6717    0.4419
0.0505    0.5802
0.2580    0.6629
0.6238    0.3291

```

PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

© The Numerical Algorithms Group Ltd, Oxford, UK. 2009–2015