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_int_multinomial (g05tg)


    1  Purpose
    2  Syntax
    7  Accuracy
    9  Example


nag_rand_int_multinomial (g05tg) generates a sequence of n variates, each consisting of k pseudorandom integers, from the discrete multinomial distribution with k outcomes and m trials, where the outcomes have probabilities p1,p2,,pk respectively.


[r, state, x, ifail] = g05tg(mode, n, m, p, r, state, 'k', k)
[r, state, x, ifail] = nag_rand_int_multinomial(mode, n, m, p, r, state, 'k', k)


nag_rand_int_multinomial (g05tg) generates a sequence of n groups of k integers xi,j, for j=1,2,,k and i=1,2,,n, from a multinomial distribution with m trials and k outcomes, where the probability of xi,j=Ij for each j=1,2,,k is
Pi1=I1,,ik=Ik= m! j=1k Ij! j=1k pjIj= m! I1!I2!Ik! p1I1p2I2pkIk,  
j= 1k pj= 1  and   j= 1k Ij=m.  
A single trial can have several outcomes (k) and the probability of achieving each outcome is known (pj). After m trials each outcome will have occurred a certain number of times. The k numbers representing the numbers of occurrences for each outcome after m trials is then a single sample from the multinomial distribution defined by the parameters k, m and pj, for j=1,2,,k. This function returns n such samples.
When k=2 this distribution is equivalent to the binomial distribution with parameters m and p=p1 (see nag_rand_int_binomial (g05ta)).
The variates can be generated with or without using a search table and index. If a search table is used then it is stored with the index in a reference vector and subsequent calls to nag_rand_int_multinomial (g05tg) with the same parameter values can then use this reference vector to generate further variates. The reference array is generated only for the outcome with greatest probability. The number of successes for the outcome with greatest probability is calculated first as for the binomial distribution (see nag_rand_int_binomial (g05ta)); the number of successes for other outcomes are calculated in turn for the remaining reduced multinomial distribution; the number of successes for the final outcome is simply calculated to ensure that the total number of successes is m.
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_int_multinomial (g05tg).


Knuth D E (1981) The Art of Computer Programming (Volume 2) (2nd Edition) Addison–Wesley


Compulsory Input Parameters

1:     mode int64int32nag_int scalar
A code for selecting the operation to be performed by the function.
Set up reference vector only.
Generate variates using reference vector set up in a prior call to nag_rand_int_multinomial (g05tg).
Set up reference vector and generate variates.
Generate variates without using the reference vector.
Constraint: mode=0, 1, 2 or 3.
2:     n int64int32nag_int scalar
n, the number of pseudorandom numbers to be generated.
Constraint: n0.
3:     m int64int32nag_int scalar
m, the number of trials of the multinomial distribution.
Constraint: m0.
4:     pk – double array
Contains the probabilities pj, for j=1,2,,k, of the k possible outcomes of the multinomial distribution.
Constraint: 0.0pj1.0 and j=1kpj=1.0.
5:     rlr – double array
lr, the dimension of the array, must satisfy the constraint
  • if mode=0 or 2,
    lr > minm,INT m×p_max+7.25 × m× p_max×1-p_max +8.5 - max0,INT m×p_max-7.25 × m×p_max× 1-p_max +9 ;
  • if mode=1, lr must remain unchanged from the previous call to nag_rand_int_multinomial (g05tg).
If mode=1, the reference vector from the previous call to nag_rand_int_multinomial (g05tg).
If mode=3, r is not referenced.
6:     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:     k int64int32nag_int scalar
Default: the dimension of the array p.
k, the number of possible outcomes of the multinomial distribution.
Constraint: k2.

Output Parameters

1:     rlr – double array
If mode3, the reference vector.
2:     state: int64int32nag_int array
Contains updated information on the state of the generator.
3:     xldxk int64int32nag_int array
The first n rows of xij each contain k pseudorandom numbers representing a k-dimensional variate from the specified multinomial distribution.
4:     ifail int64int32nag_int scalar
ifail=0 unless the function detects an error (see Error Indicators and Warnings).

Error Indicators and Warnings

Errors or warnings detected by the function:
Constraint: mode=0, 1, 2 or 3.
Constraint: n0.
Constraint: m0.
Constraint: k2.
On entry, at least one element of the vector p is less than 0.0 or greater than 1.0.
On entry, the sum of the elements of p do not equal one.
On entry, some of the elements of the array r have been corrupted or have not been initialized.
The value of m or k is not the same as when r was set up in a previous call.
On entry, lr is too small when mode=0 or 2.
On entry, state vector has been corrupted or not initialized.
Constraint: ldxn.
Constraint: ldxk.
An unexpected error has been triggered by this routine. Please contact NAG.
Your licence key may have expired or may not have been installed correctly.
Dynamic memory allocation failed.


Not applicable.

Further Comments

The reference vector for only one outcome can be set up because the conditional distributions cannot be known in advance of the generation of variates. The outcome with greatest probability of success is chosen for the reference vector because it will have the greatest spread of likely values.


This example prints 20 pseudorandom k-dimensional variates from a multinomial distribution with k=4, m=6000, p1=0.08, p2=0.1, p3=0.8 and p4=0.02, generated by a single call to nag_rand_int_multinomial (g05tg), after initialization by nag_rand_init_repeat (g05kf).
function g05tg_example

fprintf('g05tg example results\n\n');

% Initialize the base generator to a repeatable sequence
seed  = [int64(1762543)];
genid = int64(1);
subid = int64(1);
[state, ifail] = g05kf( ...
                        genid, subid, seed);

% Number of variates
n = int64(20);

% Parameters
m = int64(6000);
p = [0.08; 0.1; 0.8; 0.02];

% Generate variates from multinomial distribution
mode = int64(2);
r = zeros(6007, 1);
[r, state, x, ifail] = g05tg( ...
                              mode, n, m, p, r, state);


g05tg example results

         468         603        4811         118
         490         630        4761         119
         482         575        4821         122
         495         591        4826          88
         512         611        4761         116
         474         601        4800         125
         485         595        4791         129
         468         582        4825         125
         485         598        4800         117
         485         573        4814         128
         501         634        4749         116
         482         618        4780         120
         470         584        4810         136
         479         642        4750         129
         476         608        4807         109
         473         631        4782         114
         509         596        4778         117
         450         565        4877         108
         484         556        4840         120
         466         615        4802         117

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–2015