naginterfaces.library.rand.matrix_​2waytable

naginterfaces.library.rand.matrix_2waytable(mode, totr, totc, comm, statecomm)

matrix_2waytable generates a random two-way table.

For full information please refer to the NAG Library document for g05pz

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/g05/g05pzf.html

Parameters

modeint

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 matrix_2waytable.

$mode=2$

Set up reference vector and generate two-way table.

totrint, array-like, shape $\left(\text{nrow}\right)$

The $m$ row totals, $R_{\text{i}}$, for $\text{i}=1,2,\dots ,m$.

totcint, array-like, shape $\left(\text{ncol}\right)$

The $n$ column totals, $C_{\text{j}}$, for $\text{j}=1,2,\dots ,n$.

commdict, communication object, modified in place

Communication structure for the reference vector.

If $mode=1$, this argument must have been initialized by a prior call to matrix_2waytable.

statecommdict, RNG communication object, modified in place

RNG communication structure.

This argument must have been initialized by a prior call to init_repeat() or init_nonrepeat().

Returns

xNone or int, ndarray, shape $(\text{nrow},\text{ncol})$

If $mode=1$ or $2$, a pseudorandom two-way $m\times n$ table, $X$, with element $x[i-1,j-1]$ containing the $(i,j)$th entry in the table such that ${\sum }_1^{m}x[i-1,j-1]=totc[j-1]$ and ${\sum }_1^{n}x[i-1,j-1]=totr[i-1]$

Raises

NagValueError

(errno $1$)

On entry, $mode=⟨value⟩$.

Constraint: $mode=0$, $1$ or $2$.

(errno $2$)

On entry, $\text{nrow}=⟨value⟩$.

Constraint: $\text{nrow}\ge 2$.

(errno $3$)

On entry, $\text{ncol}=⟨value⟩$.

Constraint: $\text{ncol}\ge 2$.

(errno $4$)

On entry, at least one element of $totr$ is negative or $totr$ sums to zero.

(errno $5$)

On entry, $totc$ has at least one negative element.

(errno $6$)

$\text{nrow}$ or $\text{ncol}$ is not the same as when $comm$[‘r’] was set up in a previous call.

Previous value of $\text{nrow}=⟨value⟩$ and $\text{nrow}=⟨value⟩$.

Previous value of $\text{ncol}=⟨value⟩$ and $\text{ncol}=⟨value⟩$.

(errno $8$)

On entry, $statecomm$[‘state’] vector has been corrupted or not initialized.

(errno $15$)

On entry, the arrays $totr$ and $totc$ do not sum to the same total: $totr$ array total is $⟨value⟩$, $totc$ array total is $⟨value⟩$.

Notes

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), matrix_2waytable 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>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. matrix_2waytable 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 init_repeat() (for a repeatable sequence if computed sequentially) or init_nonrepeat() (for a non-repeatable sequence) must be called prior to the first call to matrix_2waytable.

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