nag_rngs_2_way_table (g05qdc) (PDF version)
g05 Chapter Contents
g05 Chapter Introduction
NAG C Library Manual

NAG Library Function Document

nag_rngs_2_way_table (g05qdc)

+ Contents

    1  Purpose
    7  Accuracy

1  Purpose

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

2  Specification

#include <nag.h>
#include <nagg05.h>
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 Ri and n column totals Cj (with i=1m Ri=j=1n Cj=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 order=Nag_RowMajor. See Section 3.2.1.3 in the Essential Introduction for a more detailed explanation of the use of this argument.
Constraint: order=Nag_RowMajor or Nag_ColMajor.
2:     modeIntegerInput
On entry: a code for selecting the operation to be performed by the function.
mode=0
Set up reference vector only.
mode=1
Generate two-way table using reference vector set up in a prior call to nag_rngs_2_way_table (g05qdc).
mode=2
Set up reference vector and generate two-way table.
Constraint: mode=0, 1 or 2.
3:     nrowIntegerInput
On entry: m, the number of rows in the table.
Constraint: nrow2.
4:     ncolIntegerInput
On entry: n, the number of columns in the table.
Constraint: ncol2.
5:     totr[nrow]const IntegerInput
On entry: the m row totals, Ri, for i=1,2,,m.
Constraints:
  • totr[i-1]0, for i=1,2,,m;
  • i=1mtotr[i-1]=j=1ntotc[j-1].
6:     totc[ncol]const IntegerInput
On entry: the n column totals, Cj, for j=1,2,,n.
Constraints:
  • totc[j-1]0, for j=1,2,,n;
  • j=1ntotc[j-1]=i=1mtotr[i-1].
7:     x[dim]IntegerOutput
Note: the dimension, dim, of the array x must be at least
  • max1,pdx×ncol when order=Nag_ColMajor;
  • max1,nrow×pdx when order=Nag_RowMajor.
Where Xi,j appears in this document, it refers to the array element
  • x[j-1×pdx+i-1] when order=Nag_ColMajor;
  • x[i-1×pdx+j-1] when order=Nag_RowMajor.
On exit: if mode=1 or 2, a pseudorandom two-way m by n table, X, with element Xi,j containing the i,jth entry in the table such that i=1nrowXi,j=totc[j-1] and j=1ncolXi,j=totr[i-1]
8:     pdxIntegerInput
On entry: the stride separating row or column elements (depending on the value of order) in the array x.
Constraints:
  • if order=Nag_ColMajor, pdxnrow;
  • if order=Nag_RowMajor, pdxncol.
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 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: nri=1nrowtotr[i-1]+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.
NE_BAD_PARAM
On entry, argument value had an illegal value.
NE_INT
On entry, mode=value.
Constraint: mode=0, 1 or 2.
On entry, ncol=value.
Constraint: ncol2.
On entry, nr not large enough, nr=value. Minimum length required =value.
On entry, nrow=value.
Constraint: nrow2.
On entry, pdx=value.
Constraint: pdx>0.
NE_INT_2
On entry, nrow<2 or ncol<2: nrow=value and ncol=value.
On entry, pdx=value and ncol=value.
Constraint: pdxncol.
On entry, pdx=value and nrow=value.
Constraint: pdxnrow.
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 nrow=value, current value of nrow=value. Previous value of ncol=value, current value of ncol=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 value, totc array total is value.

7  Accuracy

None.

8  Further Comments

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)

9.2  Program Data

None.

9.3  Program Results

Program Results (g05qdce.r)


nag_rngs_2_way_table (g05qdc) (PDF version)
g05 Chapter Contents
g05 Chapter Introduction
NAG C Library Manual

© The Numerical Algorithms Group Ltd, Oxford, UK. 2012