g05 Chapter Contents
g05 Chapter Introduction
NAG C Library Manual

# NAG Library Function Documentnag_rand_bivariate_copula_clayton (g05rec)

## 1  Purpose

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

## 2  Specification

 #include #include
 void nag_rand_bivariate_copula_clayton (Nag_OrderType order, Integer state[], double theta, Integer n, double x[], Integer pdx, Integer sdx, NagError *fail)

## 3  Description

Generates pseudorandom uniform bivariates $\left\{{u}_{1},{u}_{2}\right\}\in {\left(0,1\right]}^{2}$ whose joint distribution is the Clayton/Cook–Johnson Archimedean copula ${C}_{\theta }$ with parameter $\theta$, given by
 $Cθ = max u1 -θ + u2 -θ -1 ,0 -1/θ , θ ∈ -1,∞ ∖ 0$
with the special cases:
• ${C}_{-1}=\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left({u}_{1}+{u}_{2}-1,0\right)$, the Fréchet–Hoeffding lower bound;
• ${C}_{0}={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_repeatable (g05kfc) (for a repeatable sequence if computed sequentially) or nag_rand_init_nonrepeatable (g05kgc) (for a non-repeatable sequence) must be called prior to the first call to nag_rand_bivariate_copula_clayton (g05rec).

## 4  References

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

## 5  Arguments

1:     orderNag_OrderTypeInput
On entry: the order argument specifies the two-dimensional storage scheme being used, i.e., row-major ordering or column-major ordering. C language defined storage is specified by ${\mathbf{order}}=\mathrm{Nag_RowMajor}$. See Section 3.2.1.3 in the Essential Introduction for a more detailed explanation of the use of this argument.
Constraint: ${\mathbf{order}}=\mathrm{Nag_RowMajor}$ or Nag_ColMajor.
2:     state[$\mathit{dim}$]IntegerCommunication Array
Note: the actual argument supplied must be the array state supplied to the initialization functions nag_rand_init_repeatable (g05kfc) or nag_rand_init_nonrepeatable (g05kgc).
On entry: contains information on the selected base generator and its current state.
On exit: contains updated information on the state of the generator.
On entry: $\theta$, the copula parameter.
Constraint: ${\mathbf{theta}}\ge -1.0$.
4:     nIntegerInput
On entry: $n$, the number of bivariates to generate.
Constraint: ${\mathbf{n}}\ge 0$.
5:     x[${\mathbf{pdx}}×{\mathbf{sdx}}$]doubleOutput
Note: where ${\mathbf{X}}\left(i,j\right)$ appears in this document, it refers to the array element ${\mathbf{x}}\left[\left(j-1\right)×{\mathbf{pdx}}+i-1\right]$.
On exit: 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{order}}=\mathrm{Nag_ColMajor}$ and the $j$th value for the $i$th dimension of ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
6:     pdxIntegerInput
On entry: the stride separating matrix row elements in the array x.
Constraints:
• if ${\mathbf{order}}=\mathrm{Nag_ColMajor}$, ${\mathbf{pdx}}\ge {\mathbf{n}}$;
• if ${\mathbf{order}}=\mathrm{Nag_RowMajor}$, ${\mathbf{pdx}}\ge 2$.
7:     sdxIntegerInput
On entry: the secondary dimension of X.
Constraints:
• if ${\mathbf{order}}=\mathrm{Nag_ColMajor}$, ${\mathbf{sdx}}\ge 2$;
• if ${\mathbf{order}}=\mathrm{Nag_RowMajor}$, ${\mathbf{sdx}}\ge {\mathbf{n}}$.
8:     failNagError *Input/Output
The NAG error argument (see Section 3.6 in the Essential Introduction).

## 6  Error Indicators and Warnings

NE_ALLOC_FAIL
Dynamic memory allocation failed.
On entry, argument $〈\mathit{\text{value}}〉$ had an illegal value.
NE_INT
On entry, ${\mathbf{n}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{n}}\ge 0$.
NE_INT_2
On entry, pdx must be at least $〈\mathit{\text{value}}〉$: ${\mathbf{pdx}}=〈\mathit{\text{value}}〉$.
On entry, sdx must be at least $〈\mathit{\text{value}}〉$: ${\mathbf{sdx}}=〈\mathit{\text{value}}〉$.
NE_INTERNAL_ERROR
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.
NE_INVALID_STATE
On entry, corrupt state argument.
NE_REAL
On entry, invalid theta: ${\mathbf{theta}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{theta}}\ge -1.0$.

## 7  Accuracy

Not applicable.

In practice, the need for numerical stability restricts the range of $\theta$ such that:
• if $\left(\theta +1\right)<\epsilon$, the function returns pseudorandom uniform variates with ${C}_{-1}$ joint distribution;
• if $\left|\theta \right|<1.0×{10}^{-6}$, the function returns pseudorandom uniform variates with ${C}_{0}$ joint distribution;
• if $\theta >\mathrm{ln}{\epsilon }_{s}/\mathrm{ln}\left(1.0×{10}^{-2}\right)$, 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_real_safe_small_number (X02AMC); and $\epsilon$ is the machine precision returned by nag_machine_precision (X02AJC).

## 9  Example

This example generates thirteen variates for copula ${C}_{-0.8}$.

### 9.1  Program Text

Program Text (g05rece.c)

None.

### 9.3  Program Results

Program Results (g05rece.r)