Integer type:  int32  int64  nag_int  show int32  show int32  show int64  show int64  show nag_int  show nag_int

Chapter Contents
Chapter Introduction
NAG Toolbox

# NAG Toolbox: nag_rand_int_multinomial (g05tg)

## Purpose

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 ${p}_{1},{p}_{2},\dots ,{p}_{k}$ respectively.

## Syntax

[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)

## Description

nag_rand_int_multinomial (g05tg) generates a sequence of $n$ groups of $k$ integers ${x}_{\mathit{i},\mathit{j}}$, for $\mathit{j}=1,2,\dots ,k$ and $\mathit{i}=1,2,\dots ,n$, from a multinomial distribution with $m$ trials and $k$ outcomes, where the probability of ${x}_{\mathit{i},\mathit{j}}={I}_{j}$ for each $j=1,2,\dots ,k$ is
 $Pi1=I1,…,ik=Ik= m! ∏j=1k Ij! ∏j=1k pjIj= m! I1!I2!⋯Ik! p1I1p2I2⋯pkIk,$
where
 $∑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 (${p}_{j}$). 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 ${p}_{\mathit{j}}$, for $\mathit{j}=1,2,\dots ,k$. This function returns $n$ such samples.
When $k=2$ this distribution is equivalent to the binomial distribution with parameters $m$ and $p={p}_{1}$ (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).

## References

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

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{mode}$int64int32nag_int scalar
A code for selecting the operation to be performed by the function.
${\mathbf{mode}}=0$
Set up reference vector only.
${\mathbf{mode}}=1$
Generate variates using reference vector set up in a prior call to nag_rand_int_multinomial (g05tg).
${\mathbf{mode}}=2$
Set up reference vector and generate variates.
${\mathbf{mode}}=3$
Generate variates without using the reference vector.
Constraint: ${\mathbf{mode}}=0$, $1$, $2$ or $3$.
2:     $\mathrm{n}$int64int32nag_int scalar
$n$, the number of pseudorandom numbers to be generated.
Constraint: ${\mathbf{n}}\ge 0$.
3:     $\mathrm{m}$int64int32nag_int scalar
$m$, the number of trials of the multinomial distribution.
Constraint: ${\mathbf{m}}\ge 0$.
4:     $\mathrm{p}\left({\mathbf{k}}\right)$ – double array
Contains the probabilities ${p}_{\mathit{j}}$, for $\mathit{j}=1,2,\dots ,k$, of the $k$ possible outcomes of the multinomial distribution.
Constraint: $0.0\le {\mathbf{p}}\left(j\right)\le 1.0$ and $\sum _{j=1}^{k}{\mathbf{p}}\left(j\right)=1.0$.
5:     $\mathrm{r}\left(\mathit{lr}\right)$ – double array
lr, the dimension of the array, must satisfy the constraint
• if ${\mathbf{mode}}=0$ or $2$,
$\begin{array}{lll}\mathit{lr}& >& \mathrm{min}\phantom{\rule{0.125em}{0ex}}\left({\mathbf{m}},\mathrm{INT}\left[{\mathbf{m}}×\mathit{p_max}+7.25×\sqrt{{\mathbf{m}}×\mathit{p_max}×\left(1-\mathit{p_max}\right)}+8.5\right]\right)\\ & & -\mathrm{max}\phantom{\rule{0.125em}{0ex}}\left(0,\mathrm{INT}\left[{\mathbf{m}}×\mathit{p_max}-7.25×\sqrt{{\mathbf{m}}×\mathit{p_max}×\left(1-\mathit{p_max}\right)}\right]\right)+9\end{array}$;
• if ${\mathbf{mode}}=1$, lr must remain unchanged from the previous call to nag_rand_int_multinomial (g05tg).
If ${\mathbf{mode}}=1$, the reference vector from the previous call to nag_rand_int_multinomial (g05tg).
If ${\mathbf{mode}}=3$, r is not referenced.
6:     $\mathrm{state}\left(:\right)$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:     $\mathrm{k}$int64int32nag_int scalar
Default: the dimension of the array p.
$k$, the number of possible outcomes of the multinomial distribution.
Constraint: ${\mathbf{k}}\ge 2$.

### Output Parameters

1:     $\mathrm{r}\left(\mathit{lr}\right)$ – double array
If ${\mathbf{mode}}\ne 3$, the reference vector.
2:     $\mathrm{state}\left(:\right)$int64int32nag_int array
Contains updated information on the state of the generator.
3:     $\mathrm{x}\left(\mathit{ldx},{\mathbf{k}}\right)$int64int32nag_int array
The first $n$ rows of ${\mathbf{x}}\left(i,j\right)$ each contain $k$ pseudorandom numbers representing a $k$-dimensional variate from the specified multinomial distribution.
4:     $\mathrm{ifail}$int64int32nag_int scalar
${\mathbf{ifail}}={\mathbf{0}}$ unless the function detects an error (see Error Indicators and Warnings).

## Error Indicators and Warnings

Errors or warnings detected by the function:
${\mathbf{ifail}}=1$
Constraint: ${\mathbf{mode}}=0$, $1$, $2$ or $3$.
${\mathbf{ifail}}=2$
Constraint: ${\mathbf{n}}\ge 0$.
${\mathbf{ifail}}=3$
Constraint: ${\mathbf{m}}\ge 0$.
${\mathbf{ifail}}=4$
Constraint: ${\mathbf{k}}\ge 2$.
${\mathbf{ifail}}=5$
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.
${\mathbf{ifail}}=6$
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.
${\mathbf{ifail}}=7$
On entry, lr is too small when ${\mathbf{mode}}=0$ or $2$.
${\mathbf{ifail}}=8$
On entry, state vector has been corrupted or not initialized.
${\mathbf{ifail}}=10$
Constraint: $\mathit{ldx}\ge {\mathbf{n}}$.
${\mathbf{ifail}}=210$
Constraint: $\mathit{ldx}\ge {\mathbf{k}}$.
${\mathbf{ifail}}=-99$
${\mathbf{ifail}}=-399$
Your licence key may have expired or may not have been installed correctly.
${\mathbf{ifail}}=-999$
Dynamic memory allocation failed.

## Accuracy

Not applicable.

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.

## Example

This example prints $20$ pseudorandom $k$-dimensional variates from a multinomial distribution with $k=4$, $m=6000$, ${p}_{1}=0.08$, ${p}_{2}=0.1$, ${p}_{3}=0.8$ and ${p}_{4}=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);

disp('Variates');
disp(double(x));

```
```g05tg example results

Variates
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

```