nag_rand_copula_gumbel (g05rkc) (PDF version)
g05 Chapter Contents
g05 Chapter Introduction
NAG C Library Manual

# NAG Library Function Documentnag_rand_copula_gumbel (g05rkc)

## 1  Purpose

nag_rand_copula_gumbel (g05rkc) generates pseudorandom uniform variates with joint distribution of a Gumbel–Hougaard Archimedean copula.

## 2  Specification

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

## 3  Description

Generates $n$ pseudorandom uniform $m$-variates whose joint distribution is the Gumbel–Hougaard Archimedean copula ${C}_{\theta }$, given by
 $Cθ = exp - -ln⁡u1 θ + -ln⁡u2 θ + ⋯ + -ln⁡um θ , θ ∈ 1,∞ , uj ∈ 0,1 , j = 1 , 2 , … m ;$
with the special cases:
• ${C}_{1}={u}_{1}{u}_{2}\cdots {u}_{m}$, the product copula;
• ${C}_{\infty }=\mathrm{min}\phantom{\rule{0.125em}{0ex}}\left({u}_{1},{u}_{2},\dots ,{u}_{m}\right)$, the Fréchet–Hoeffding upper bound.
The generation method uses mixture of powers.
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_copula_gumbel (g05rkc).

## 4  References

Marshall A W and Olkin I (1988) Families of multivariate distributions Journal of the American Statistical Association 83 403
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.
3:     thetadoubleInput
On entry: $\theta$, the copula parameter.
Constraint: ${\mathbf{theta}}\ge 1.0$.
4:     nIntegerInput
On entry: $n$, the number of pseudorandom uniform variates to generate.
Constraint: ${\mathbf{n}}\ge 0$.
5:     mIntegerInput
On entry: $m$, the number of dimensions.
Constraint: ${\mathbf{m}}\ge 2$.
6:     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 pseudorandom uniform variates 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}$.
7:     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 {\mathbf{m}}$.
8:     sdxIntegerInput
On entry: the secondary dimension of X.
Constraints:
• if ${\mathbf{order}}=\mathrm{Nag_ColMajor}$, ${\mathbf{sdx}}\ge {\mathbf{m}}$;
• if ${\mathbf{order}}=\mathrm{Nag_RowMajor}$, ${\mathbf{sdx}}\ge {\mathbf{n}}$.
9:     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.
NE_BAD_PARAM
On entry, argument $〈\mathit{\text{value}}〉$ had an illegal value.
NE_INT
On entry, ${\mathbf{m}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{m}}>1$.
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$.

Not applicable.

## 8  Further Comments

In practice, the need for numerical stability restricts the range of $\theta$ such that:
• if $\left(\theta -1\right)<1.0×{10}^{-6}$, the function returns pseudorandom uniform variates with ${C}_{1}$ joint distribution;
• if $\theta >\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(80.0,-0.5\mathrm{ln}{\epsilon }_{s}\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).

## 9  Example

This example generates thirteen four-dimensional variates for copula ${C}_{2.4}$.

### 9.1  Program Text

Program Text (g05rkce.c)

None.

### 9.3  Program Results

Program Results (g05rkce.r)

nag_rand_copula_gumbel (g05rkc) (PDF version)
g05 Chapter Contents
g05 Chapter Introduction
NAG C Library Manual