g05pz generates a random two-way table.

Syntax

C#
public static void g05pz( int mode, int nrow, int ncol, int[] totr, int[] totc, double[] r, G05..::..G05State g05state, int[,] x, out int ifail )

Visual Basic
Public Shared Sub g05pz ( _ mode As Integer, _ nrow As Integer, _ ncol As Integer, _ totr As Integer(), _ totc As Integer(), _ r As Double(), _ g05state As G05..::..G05State, _ x As Integer(,), _ <OutAttribute> ByRef ifail As Integer _ )

Visual Basic

Public Shared Sub g05pz ( _
	mode As Integer, _
	nrow As Integer, _
	ncol As Integer, _
	totr As Integer(), _
	totc As Integer(), _
	r As Double(), _
	g05state As G05..::..G05State, _
	x As Integer(,), _
	<OutAttribute> ByRef ifail As Integer _
)

Visual C++
public: static void g05pz( int mode, int nrow, int ncol, array<int>^ totr, array<int>^ totc, array<double>^ r, G05..::..G05State^ g05state, array<int,2>^ x, [OutAttribute] int% ifail )

F#
static member g05pz : mode : int * nrow : int * ncol : int * totr : int[] * totc : int[] * r : float[] * g05state : G05..::..G05State * x : int[,] * ifail : int byref -> unit

Parameters

mode

Type: System..::..Int32

On entry: a code for selecting the operation to be performed by the method.

$mode = 0$: Set up reference vector only.
$mode = 1$: Generate two-way table using reference vector set up in a prior call to g05pz.
$mode = 2$: Set up reference vector and generate two-way table.

Constraint:

mode = 0

1

2

nrow: Type: System..::..Int32
On entry: $m$ , the number of rows in the table.

Constraint: $nrow \geq 2$ .

ncol: Type: System..::..Int32
On entry: $n$ , the number of columns in the table.

Constraint: $ncol \geq 2$ .

totr

Type: array<System..::..Int32>[]()[][]

An array of size [nrow]

On entry: the

m

row totals,

R_{i}

, for

i = 1, 2, \dots, m

Constraints:

$totr [i - 1] \geq 0$ , for $i = 1, 2, \dots, m$ ;
$\sum_{i = 1}^{m} totr [i - 1] = \sum_{j = 1}^{n} totc [j - 1]$ ;
$\sum_{i} totr [i - 1] > 0$ , for $i = 1, 2, \dots, m$ .

totc

Type: array<System..::..Int32>[]()[][]

An array of size [ncol]

On entry: the

n

column totals,

C_{j}

, for

j = 1, 2, \dots, n

Constraints:

$totc [j - 1] \geq 0$ , for $j = 1, 2, \dots, n$ ;
$\sum_{j = 1}^{n} totc [j - 1] = \sum_{i = 1}^{m} totr [i - 1]$ .

r: Type: array<System..::..Double>[]()[][]
An array of size [lr]
On entry: if $mode = 1$ , the reference vector from the previous call to g05pz.
On exit: the reference vector.

g05state: Type: NagLibrary..::..G05..::..G05State
An Object of type G05.G05State.

x: Type: array<System..::..Int32,2>[,](,)[,][,]
An array of size [dim1, ncol]
Note: dim1 must satisfy the constraint: $dim1 \geq nrow$
On exit: if $mode = 1$ or $2$ , a pseudorandom two-way $m$ by $n$ table, $X$ , with element $x [i - 1, j - 1]$ containing the $(i, j)$ th entry in the table such that $\sum_{i = 1}^{m} x [i - 1, j - 1] = totc [j - 1]$ and $\sum_{j = 1}^{n} x [i - 1, j - 1] = totr [i - 1]$

ifail: Type: System..::..Int32%
On exit: $ifail = 0$ unless the method detects an error or a warning has been flagged (see [Error Indicators and Warnings]).

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), g05pz 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 \times n

(i.e.,

T > 2 m n

). 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. g05pz 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 methods (G05KFF not in this release) (for a repeatable sequence if computed sequentially) or (G05KGF not in this release) (for a non-repeatable sequence) must be called prior to the first call to g05pz.

References

Patefield W M (1981) An efficient method of generating

R \times C

tables with given row and column totals Appl. Stats. 30 91–97

Error Indicators and Warnings

Errors or warnings detected by the method:

Some error messages may refer to parameters that are dropped from this interface (LDX) In these cases, an error in another parameter has usually caused an incorrect value to be inferred.

$ifail = 1$: On entry, $mode \neq 0$ , $1$ or $2$ .

$ifail = 2$

On entry,

nrow < 2

$ifail = 3$

On entry,

ncol < 2

$ifail = 4$: At least one element of totr is negative.

$ifail = 5$: At least one element of totc is negative.

$ifail = 6$: The value of nrow or ncol is not the same as when r was set up in a previous call to g05pz with $mode = 0$ or $2$ .

$ifail = 7$

On entry,

lr is too small when

mode = 0

2

(see [Parameters]).

$ifail = 8$

On entry,

state vector was not initialized or has been corrupted.

$ifail = 15$: The arrays totr and totc do not sum to the same total.

$ifail = -9000$: An error occured, see message report.
$ifail = -6000$: Invalid Parameters $〈value〉$
$ifail = -4000$: Invalid dimension for array $〈value〉$
$ifail = -8000$: Negative dimension for array $〈value〉$
$ifail = -6000$: Invalid Parameters $〈value〉$

Accuracy

None.

Parallelism and Performance

None.

Further Comments

None.

Example

Example program (C#): g05pze.cs

Example program data: g05pze.d

Example program results: g05pze.r

Syntax

Parameters

Description

References

Error Indicators and Warnings

Accuracy

Parallelism and Performance

Further Comments

Example

See Also