g05 Chapter Contents
g05 Chapter Introduction
NAG C Library Manual

# NAG Library Function Documentnag_rand_bivariate_copula_frank (g05rfc)

## 1  Purpose

nag_rand_bivariate_copula_frank (g05rfc) generates pseudorandom uniform bivariates with joint distribution of a Frank Archimedean copula.

## 2  Specification

 #include #include
 void nag_rand_bivariate_copula_frank (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 Frank Archimedean copula ${C}_{\theta }$ with parameter $\theta$, given by
 $Cθ = - 1θ ln 1 + e -θu1 -1 e -θu2 -1 e-θ-1 , θ ∈ -∞,∞ ∖ 0$
with the special cases:
• ${C}_{-\infty }=\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_frank (g05rfc).

## 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.
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]$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• ${\mathbf{x}}\left[\left(i-1\right)×{\mathbf{pdx}}+j-1\right]$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
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 row or column elements (depending on the value of order) 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.

Not applicable.

## 8  Further Comments

In practice, the need for numerical stability restricts the range of $\theta$ such that:
• if $\theta <\mathrm{ln}{\epsilon }_{s}$, the function returns pseudorandom uniform variates with ${C}_{-\infty }$ 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$, 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}_{-12.0}$.

### 9.1  Program Text

Program Text (g05rfce.c)

None.

### 9.3  Program Results

Program Results (g05rfce.r)