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

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_rand_copula_clayton_bivar (g05re)

## Purpose

nag_rand_copula_clayton_bivar (g05re) generates pseudorandom uniform bivariates with joint distribution of a Clayton/Cook–Johnson Archimedean copula.

## Syntax

[state, x, ifail] = g05re(n, theta, sorder, state)
[state, x, ifail] = nag_rand_copula_clayton_bivar(n, theta, sorder, state)

## Description

Generates pseudorandom uniform bivariates {u1,u2}(0,1]2$\left\{{u}_{1},{u}_{2}\right\}\in {\left(0,1\right]}^{2}$ whose joint distribution is the Clayton/Cook–Johnson Archimedean copula Cθ${C}_{\theta }$ with parameter θ$\theta$, given by
 Cθ = [max ( u1 − θ + u2 − θ − 1 ,0)] − 1 / θ ,   θ ∈ ( − 1,∞) ∖ {0} $Cθ = [ max( u1 -θ + u2 -θ -1 ,0) ] -1/θ , θ ∈ (-1,∞) ∖ {0}$
with the special cases:
• C1 = max ( u1 + u2 1 ,0) ${C}_{-1}=\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({u}_{1}+{u}_{2}-1,0\right)$, the Fréchet–Hoeffding lower bound;
• C0 = u1u2${C}_{0}={u}_{1}{u}_{2}$, the product copula;
• C = min (u1,u2)${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_clayton_bivar (g05re).

## References

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

## Parameters

### Compulsory Input Parameters

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

ldx sdx

### Output Parameters

1:     state( : $:$) – 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 updated information on the state of the generator.
2:     x(ldx,sdx) – double array
The n$n$ bivariate uniforms with joint distribution described by Cθ${C}_{\theta }$, with x(i,j)${\mathbf{x}}\left(i,j\right)$ holding the i$i$th value for the j$j$th dimension if sorder = 1${\mathbf{sorder}}=1$ and the j$j$th value for the i$i$th dimension of sorder = 2${\mathbf{sorder}}=2$.
3:     ifail – int64int32nag_int scalar
${\mathrm{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:
ifail = 1${\mathbf{ifail}}=1$
On entry, corrupt state parameter.
ifail = 2${\mathbf{ifail}}=2$
Constraint: theta1.0${\mathbf{theta}}\ge -1.0$.
ifail = 3${\mathbf{ifail}}=3$
Constraint: n0${\mathbf{n}}\ge 0$.
ifail = 4${\mathbf{ifail}}=4$
On entry, invalid sorder.
Constraint: sorder = 1${\mathbf{sorder}}=1$ or 2$2$.
ifail = 6${\mathbf{ifail}}=6$
On entry, ldx is too small: .
ifail = 7${\mathbf{ifail}}=7$
On entry, sdx is too small: .
ifail = 999${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.

## Accuracy

Not applicable.

In practice, the need for numerical stability restricts the range of θ$\theta$ such that:
• if (θ + 1) < ε$\left(\theta +1\right)<\epsilon$, the function returns pseudorandom uniform variates with C1${C}_{-1}$ joint distribution;
• if |θ| < 1.0 × 106$|\theta |<1.0×{10}^{-6}$, the function returns pseudorandom uniform variates with C0${C}_{0}$ joint distribution;
• if θ > lnεs / ln(1.0 × 102)$\theta >\mathrm{ln}{\epsilon }_{s}/\mathrm{ln}\left(1.0×{10}^{-2}\right)$, the function returns pseudorandom uniform variates with C${C}_{\infty }$ joint distribution;
where εs${\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

```function nag_rand_copula_clayton_bivar_example
% Initialize the seed
seed = [int64(1762543)];
% genid and subid identify the base generator
genid = int64(1);
subid =  int64(1);
% Sample size
n = int64(13);
% Sample order
sorder = int64(1);
% Parameter
theta = -0.8;

% Initialize the generator to a repeatable sequence
[state, ifail] = nag_rand_init_repeat(genid, subid, seed);

% Generate variates
[state, x, ifail] = nag_rand_copula_clayton_bivar(n, theta, sorder, state)
```
```

state =

17
1234
1
0
28214
15039
27035
23461
17917
13895
19930
8
0
1234
1
1
1234

x =

0.6400    0.2223
0.1154    0.8101
0.7486    0.1439
0.8003    0.1062
0.1135    0.9946
0.4975    0.7655
0.3904    0.4925
0.7892    0.1196
0.5032    0.4116
0.6750    0.2093
0.0600    0.9055
0.2655    0.7085
0.6276    0.2370

ifail =

0

```
```function g05re_example
% Initialize the seed
seed = [int64(1762543)];
% genid and subid identify the base generator
genid = int64(1);
subid =  int64(1);
% Sample size
n = int64(13);
% Sample order
sorder = int64(1);
% Parameter
theta = -0.8;

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

% Generate variates
[state, x, ifail] = g05re(n, theta, sorder, state)
```
```

state =

17
1234
1
0
28214
15039
27035
23461
17917
13895
19930
8
0
1234
1
1
1234

x =

0.6400    0.2223
0.1154    0.8101
0.7486    0.1439
0.8003    0.1062
0.1135    0.9946
0.4975    0.7655
0.3904    0.4925
0.7892    0.1196
0.5032    0.4116
0.6750    0.2093
0.0600    0.9055
0.2655    0.7085
0.6276    0.2370

ifail =

0

```