hide long namesshow long names
hide short namesshow short names
Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

NAG Toolbox: nag_rand_matrix_2waytable (g05pz)

Purpose

nag_rand_matrix_2waytable (g05pz) generates a random two-way table.

Syntax

[r, state, x, ifail] = g05pz(mode, totr, totc, r, state, 'nrow', nrow, 'ncol', ncol, 'lr', lr)
[r, state, x, ifail] = nag_rand_matrix_2waytable(mode, totr, totc, r, state, 'nrow', nrow, 'ncol', ncol, 'lr', lr)

Description

Given mm row totals RiRi and nn column totals CjCj (with i = 1m Ri = j = 1n Cj = Ti=1m Ri=j=1n Cj=T, say), nag_rand_matrix_2waytable (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 TT is large relative to the number of table entries m × nm×n (i.e., T > 2mnT>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_rand_matrix_2waytable (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 functions nag_rand_init_repeat (g05kf) (for a repeatable sequence if computed sequentially) or nag_rand_init_nonrepeat (g05kg) (for a non-repeatable sequence) must be called prior to the first call to nag_rand_matrix_2waytable (g05pz).

References

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

Parameters

Compulsory Input Parameters

1:     mode – int64int32nag_int scalar
A code for selecting the operation to be performed by the function.
mode = 0mode=0
Set up reference vector only.
mode = 1mode=1
Generate two-way table using reference vector set up in a prior call to nag_rand_matrix_2waytable (g05pz).
mode = 2mode=2
Set up reference vector and generate two-way table.
Constraint: mode = 0mode=0, 11 or 22.
2:     totr(nrow) – int64int32nag_int array
nrow, the dimension of the array, must satisfy the constraint nrow2nrow2.
The mm row totals, RiRi, for i = 1,2,,mi=1,2,,m.
Constraints:
  • totr(i)0totri0, for i = 1,2,,mi=1,2,,m;
  • i = 1mtotr(i) = j = 1ntotc(j)i=1mtotri=j=1ntotcj;
  • i totr(i) > 0i totri>0, for i = 1,2,,mi=1,2,,m.
3:     totc(ncol) – int64int32nag_int array
ncol, the dimension of the array, must satisfy the constraint ncol2ncol2.
The nn column totals, CjCj, for j = 1,2,,nj=1,2,,n.
Constraints:
  • totc(j)0totcj0, for j = 1,2,,nj=1,2,,n;
  • j = 1ntotc(j) = i = 1mtotr(i)j=1ntotcj=i=1mtotri.
4:     r(lr) – double array
lr, the dimension of the array, must satisfy the constraint lri = 1mtotr(i) + 5lri=1mtotri+5.
If mode = 1mode=1, the reference vector from the previous call to nag_rand_matrix_2waytable (g05pz).
5:     state( : :) – int64int32nag_int array
Note: the actual argument supplied must be the array state supplied to the initialization routines nag_rand_init_repeat (g05kf) or nag_rand_init_nonrepeat (g05kg).
Contains information on the selected base generator and its current state.

Optional Input Parameters

1:     nrow – int64int32nag_int scalar
Default: The dimension of the array totr.
mm, the number of rows in the table.
Constraint: nrow2nrow2.
2:     ncol – int64int32nag_int scalar
Default: The dimension of the array totc.
nn, the number of columns in the table.
Constraint: ncol2ncol2.
3:     lr – int64int32nag_int scalar
Default: The dimension of the array r.
The dimension of the array r as declared in the (sub)program from which nag_rand_matrix_2waytable (g05pz) is called.
Constraint: lri = 1mtotr(i) + 5lri=1mtotri+5.

Input Parameters Omitted from the MATLAB Interface

ldx

Output Parameters

1:     r(lr) – double array
The reference vector.
2:     state( : :) – int64int32nag_int array
Note: the actual argument supplied must be the array state supplied to the initialization routines nag_rand_init_repeat (g05kf) or nag_rand_init_nonrepeat (g05kg).
Contains updated information on the state of the generator.
3:     x(ldx,ncol) – int64int32nag_int array
ldxnrowldxnrow.
If mode = 1mode=1 or 22, a pseudorandom two-way mm by nn table, XX, with element x(i,j)xij containing the (i,j)(i,j)th entry in the table such that i = 1m x(i,j) = totc(j) i=1 m xij=totcj and j = 1n x(i,j) = totr(i) j=1 n xij=totri
4:     ifail – int64int32nag_int scalar
ifail = 0ifail=0 unless the function detects an error (see [Error Indicators and Warnings]).

Error Indicators and Warnings

Errors or warnings detected by the function:
  ifail = 1ifail=1
On entry, mode0mode0, 11 or 22.
  ifail = 2ifail=2
On entry,nrow < 2nrow<2.
  ifail = 3ifail=3
On entry,ncol < 2ncol<2.
  ifail = 4ifail=4
At least one element of totr is negative.
  ifail = 5ifail=5
At least one element of totc is negative.
  ifail = 6ifail=6
The value of nrow or ncol is not the same as when r was set up in a previous call to nag_rand_matrix_2waytable (g05pz) with mode = 0mode=0 or 22.
  ifail = 7ifail=7
On entry,lr is too small when mode = 0mode=0 or 22 (see Section [Parameters]).
  ifail = 8ifail=8
On entry,state vector was not initialized or has been corrupted.
  ifail = 10ifail=10
On entry,ldx < nrowldx<nrow.
  ifail = 15ifail=15
The arrays totr and totc do not sum to the same total.

Accuracy

None.

Further Comments

None.

Example

function nag_rand_matrix_2waytable_example
% Initialize the seed
seed = [int64(1762543)];
% genid and subid identify the base generator
genid = int64(1);
subid =  int64(1);

mode = int64(2);
totr = [int64(9);11;7;23];
totc = [int64(16);17;17];
r = zeros(60, 1);
% Initialize the generator to a repeatable sequence
[state, ifail] = nag_rand_init_repeat(genid, subid, seed);
[r, state, x, ifail] = nag_rand_matrix_2waytable(mode, totr, totc, r, state)
 

r =

   50.5000
    4.5000
    3.5000
   39.6402
         0
         0
    0.6931
    1.7918
    3.1781
    4.7875
    6.5793
    8.5252
   10.6046
   12.8018
   15.1044
   17.5023
   19.9872
   22.5522
   25.1912
   27.8993
   30.6719
   33.5051
   36.3954
   39.3399
   42.3356
   45.3801
   48.4712
   51.6067
   54.7847
   58.0036
   61.2617
   64.5575
   67.8897
   71.2570
   74.6582
   78.0922
   81.5580
   85.0545
   88.5808
   92.1362
   95.7197
   99.3306
  102.9682
  106.6318
  110.3206
  114.0342
  117.7719
  121.5331
  125.3173
  129.1239
  132.9526
  136.8027
  140.6739
  144.5657
  148.4778
         0
         0
         0
         0
         0


state =

                   17
                 1234
                    1
                    0
                 9174
                28197
                12280
                16631
                17917
                13895
                19930
                    8
                    0
                 1234
                    1
                    1
                 1234


x =

                    2                    4                    3
                    6                    1                    4
                    2                    4                    1
                    6                    8                    9


ifail =

                    0


function g05pz_example
% Initialize the seed
seed = [int64(1762543)];
% genid and subid identify the base generator
genid = int64(1);
subid =  int64(1);

mode = int64(2);
totr = [int64(9);11;7;23];
totc = [int64(16);17;17];
r = zeros(60, 1);
% Initialize the generator to a repeatable sequence
[state, ifail] = g05kf(genid, subid, seed);
[r, state, x, ifail] = g05pz(mode, totr, totc, r, state)
 

r =

   50.5000
    4.5000
    3.5000
   39.6402
         0
         0
    0.6931
    1.7918
    3.1781
    4.7875
    6.5793
    8.5252
   10.6046
   12.8018
   15.1044
   17.5023
   19.9872
   22.5522
   25.1912
   27.8993
   30.6719
   33.5051
   36.3954
   39.3399
   42.3356
   45.3801
   48.4712
   51.6067
   54.7847
   58.0036
   61.2617
   64.5575
   67.8897
   71.2570
   74.6582
   78.0922
   81.5580
   85.0545
   88.5808
   92.1362
   95.7197
   99.3306
  102.9682
  106.6318
  110.3206
  114.0342
  117.7719
  121.5331
  125.3173
  129.1239
  132.9526
  136.8027
  140.6739
  144.5657
  148.4778
         0
         0
         0
         0
         0


state =

                   17
                 1234
                    1
                    0
                 9174
                28197
                12280
                16631
                17917
                13895
                19930
                    8
                    0
                 1234
                    1
                    1
                 1234


x =

                    2                    4                    3
                    6                    1                    4
                    2                    4                    1
                    6                    8                    9


ifail =

                    0



PDF version (NAG web site, 64-bit version, 64-bit version)
Chapter Contents
Chapter Introduction
NAG Toolbox

© The Numerical Algorithms Group Ltd, Oxford, UK. 2009–2013