g05 Chapter Contents
g05 Chapter Introduction
NAG C Library Manual

# NAG Library Function Documentnag_rngs_2_way_table (g05qdc)

## 1  Purpose

nag_rngs_2_way_table (g05qdc) generates a random two-way table.

## 2  Specification

 #include #include
 void nag_rngs_2_way_table (Nag_OrderType order, Integer mode, Integer nrow, Integer ncol, const Integer totr[], const Integer totc[], Integer x[], Integer pdx, Integer igen, Integer iseed[], double r[], Integer nr, NagError *fail)

## 3  Description

Given $m$ row totals ${R}_{i}$ and $n$ column totals ${C}_{j}$ (with $\sum _{i=1}^{m}{R}_{i}=\sum _{j=1}^{n}{C}_{j}=T$, say), nag_rngs_2_way_table (g05qdc) will generate a pseudorandom two-way table of integers such that the row and column totals are satisfied.
The method used is based on that described by Patefield (1981) which is most efficient when $T$ is large relative to the number of table entries $m×n$ (i.e., $T>2mn$). Entries are generated one row at a time and one entry at a time within a row. Each entry is generated using the conditional probability distribution for that entry given the entries in the previous rows and the previous entries in the same row.
A reference vector is used to store computed values that can be reused in the generation of new tables with the same row and column totals. nag_rngs_2_way_table (g05qdc) can be called to simply set up the reference vector, or to generate a two-way table using a reference vector set up in a previous call, or it can combine both functions in a single call.
One of the initialization functions nag_rngs_init_repeatable (g05kbc) (for a repeatable sequence if computed sequentially) or nag_rngs_init_nonrepeatable (g05kcc) (for a non-repeatable sequence) must be called prior to the first call to nag_rngs_2_way_table (g05qdc).

## 4  References

Patefield W M (1981) An efficient method of generating $R×C$ tables with given row and column totals Appl. Stats. 30 91–97

## 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:     modeIntegerInput
On entry: a code for selecting the operation to be performed by the function.
${\mathbf{mode}}=0$
Set up reference vector only.
${\mathbf{mode}}=1$
Generate two-way table using reference vector set up in a prior call to nag_rngs_2_way_table (g05qdc).
${\mathbf{mode}}=2$
Set up reference vector and generate two-way table.
Constraint: ${\mathbf{mode}}=0$, $1$ or $2$.
3:     nrowIntegerInput
On entry: $m$, the number of rows in the table.
Constraint: ${\mathbf{nrow}}\ge 2$.
4:     ncolIntegerInput
On entry: $n$, the number of columns in the table.
Constraint: ${\mathbf{ncol}}\ge 2$.
5:     totr[nrow]const IntegerInput
On entry: the $m$ row totals, ${R}_{\mathit{i}}$, for $\mathit{i}=1,2,\dots ,m$.
Constraints:
• ${\mathbf{totr}}\left[\mathit{i}-1\right]\ge 0$, for $\mathit{i}=1,2,\dots ,m$;
• $\sum _{i=1}^{m}{\mathbf{totr}}\left[i-1\right]=\sum _{j=1}^{n}{\mathbf{totc}}\left[j-1\right]$.
6:     totc[ncol]const IntegerInput
On entry: the $n$ column totals, ${C}_{\mathit{j}}$, for $\mathit{j}=1,2,\dots ,n$.
Constraints:
• ${\mathbf{totc}}\left[\mathit{j}-1\right]\ge 0$, for $\mathit{j}=1,2,\dots ,n$;
• $\sum _{j=1}^{n}{\mathbf{totc}}\left[j-1\right]=\sum _{i=1}^{m}{\mathbf{totr}}\left[i-1\right]$.
7:     x[$\mathit{dim}$]IntegerOutput
Note: the dimension, dim, of the array x must be at least
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{pdx}}×{\mathbf{ncol}}\right)$ when ${\mathbf{order}}=\mathrm{Nag_ColMajor}$;
• $\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(1,{\mathbf{nrow}}×{\mathbf{pdx}}\right)$ when ${\mathbf{order}}=\mathrm{Nag_RowMajor}$.
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: if ${\mathbf{mode}}=1$ or $2$, a pseudorandom two-way $m$ by $n$ table, $X$, with element ${\mathbf{X}}\left(i,j\right)$ containing the $\left(i,j\right)$th entry in the table such that $\sum _{i=1}^{{\mathbf{nrow}}}{\mathbf{X}}\left(i,j\right)={\mathbf{totc}}\left[j-1\right]$ and $\sum _{j=1}^{{\mathbf{ncol}}}{\mathbf{X}}\left(i,j\right)={\mathbf{totr}}\left[i-1\right]$
8:     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{nrow}}$;
• if ${\mathbf{order}}=\mathrm{Nag_RowMajor}$, ${\mathbf{pdx}}\ge {\mathbf{ncol}}$.
9:     igenIntegerInput
On entry: must contain the identification number for the generator to be used to return a pseudorandom number and should remain unchanged following initialization by a prior call to nag_rngs_init_repeatable (g05kbc) or nag_rngs_init_nonrepeatable (g05kcc).
10:   iseed[$4$]IntegerCommunication Array
On entry: contains values which define the current state of the selected generator.
On exit: contains updated values defining the new state of the selected generator.
11:   r[nr]doubleCommunication Array
On entry: if ${\mathbf{mode}}=1$, the reference vector from the previous call to nag_rngs_2_way_table (g05qdc).
On exit: the reference vector.
12:   nrIntegerInput
On entry: the dimension of the array r.
Constraint: ${\mathbf{nr}}\ge \sum _{i=1}^{{\mathbf{nrow}}}{\mathbf{totr}}\left[i-1\right]+4$.
13:   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{mode}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{mode}}=0$, $1$ or $2$.
On entry, ${\mathbf{ncol}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{ncol}}\ge 2$.
On entry, nr not large enough, ${\mathbf{nr}}=〈\mathit{\text{value}}〉$. Minimum length required $\text{}=〈\mathit{\text{value}}〉$.
On entry, ${\mathbf{nrow}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{nrow}}\ge 2$.
On entry, ${\mathbf{pdx}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pdx}}>0$.
NE_INT_2
On entry, ${\mathbf{nrow}}<2$ or ${\mathbf{ncol}}<2$: ${\mathbf{nrow}}=〈\mathit{\text{value}}〉$ and ${\mathbf{ncol}}=〈\mathit{\text{value}}〉$.
On entry, ${\mathbf{pdx}}=〈\mathit{\text{value}}〉$ and ${\mathbf{ncol}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pdx}}\ge {\mathbf{ncol}}$.
On entry, ${\mathbf{pdx}}=〈\mathit{\text{value}}〉$ and ${\mathbf{nrow}}=〈\mathit{\text{value}}〉$.
Constraint: ${\mathbf{pdx}}\ge {\mathbf{nrow}}$.
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_PREV_CALL
nrow or ncol is not the same as when r was set up in a previous call. Previous value of ${\mathbf{nrow}}=〈\mathit{\text{value}}〉$, current value of ${\mathbf{nrow}}=〈\mathit{\text{value}}〉$. Previous value of ${\mathbf{ncol}}=〈\mathit{\text{value}}〉$, current value of ${\mathbf{ncol}}=〈\mathit{\text{value}}〉$.
NE_REAL_ARRAY_ELEM_CONS
On entry, totc has at least one negative element.
On entry, totr has at least one negative element.
NE_REAL_ARRAYS_SUM
On entry, the arrays totr and totc do not sum to the same total: totr array total is $〈\mathit{\text{value}}〉$, totc array total is $〈\mathit{\text{value}}〉$.

None.

None.

## 9  Example

Following initialization of the pseudorandom number generator by a call to nag_rngs_init_repeatable (g05kbc), this example generates and prints a $4$ by $3$ two-way table, with row totals of $9$, $11$, $7$ and $23$ respectively, and column totals of $16$, $17$ and $17$ respectively.

### 9.1  Program Text

Program Text (g05qdce.c)

None.

### 9.3  Program Results

Program Results (g05qdce.r)