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)

▸▿ Contents

1 Purpose

2 Syntax

3 Description

4 References

▸▿ 5 Parameters

5.1 Compulsory Input Parameters

5.2 Optional Input Parameters

5.3 Output Parameters

6 Error Indicators and Warnings

7 Accuracy

8 Further Comments

9 Example

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_{i, j}

, for

j = 1, 2, \dots, k

and

i = 1, 2, \dots, n

, from a multinomial distribution with

m

trials and

k

outcomes, where the probability of

x_{i, j} = I_{j}

for each

j = 1, 2, \dots, k

P (i_{1} = I_{1}, \dots, i_{k} = I_{k}) = \frac{m!}{\prod_{j = 1}^{k} I_{j}!} \prod_{j = 1}^{k} p_{j}^{I_{j}} = \frac{m!}{I_{1}! I_{2}! \dots I_{k}!} p_{1}^{I_{1}} p_{2}^{I_{2}} \dots p_{k}^{I_{k}},

where

\sum_{j = 1}^{k} p_{j} = 1 and \sum_{j = 1}^{k} I_{j} = 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_{j}

, for

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: $mode$ – int64int32nag_int scalar

A code for selecting the operation to be performed by the function.

$mode = 0$: Set up reference vector only.
$mode = 1$: Generate variates using reference vector set up in a prior call to nag_rand_int_multinomial (g05tg).
$mode = 2$: Set up reference vector and generate variates.
$mode = 3$: Generate variates without using the reference vector.

Constraint:

mode = 0

1

2

3

2: $n$ – int64int32nag_int scalar

n

, the number of pseudorandom numbers to be generated.

Constraint:

n \geq 0

3: $m$ – int64int32nag_int scalar

m

, the number of trials of the multinomial distribution.

Constraint:

m \geq 0

4: $p (k)$ – double array

Contains the probabilities

p_{j}

, for

j = 1, 2, \dots, k

, of the

k

possible outcomes of the multinomial distribution.

Constraint:

0.0 \leq p (j) \leq 1.0

and

\sum_{j = 1}^{k} p (j) = 1.0

5: $r (lr)$ – double array

lr, the dimension of the array, must satisfy the constraint

if $mode = 0$ or $2$ ,
$\begin{array}{l} lr & > & \min (m, INT [m \times p_max + 7.25 \times \sqrt{m \times p_max \times (1 - p_max)} + 8.5]) \\ - \max (0, INT [m \times p_max - 7.25 \times \sqrt{m \times p_max \times (1 - p_max)}]) + 9 \end{array}$ ;
if $mode = 1$ , lr must remain unchanged from the previous call to nag_rand_int_multinomial (g05tg).

mode = 1

, the reference vector from the previous call to nag_rand_int_multinomial (g05tg).

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: $k \geq 2$ .

Output Parameters

1: $r (lr)$ – double array: If $mode \neq 3$ , the reference vector.
2: $state (:)$ – int64int32nag_int array: Contains updated information on the state of the generator.
3: $x (ldx, k)$ – int64int32nag_int array: The first $n$ rows of $x (i, j)$ 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:

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

$ifail = 2$: Constraint: $n \geq 0$ .

$ifail = 3$: Constraint: $m \geq 0$ .

$ifail = 4$: Constraint: $k \geq 2$ .

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

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

$ifail = 7$: On entry, lr is too small when $mode = 0$ or $2$ .

$ifail = 8$: On entry, state vector has been corrupted or not initialized.

$ifail = 10$: Constraint: $ldx \geq n$ .

$ifail = 210$: Constraint: $ldx \geq k$ .

$ifail = - 99$: An unexpected error has been triggered by this routine. Please contact NAG.

$ifail = - 399$: Your licence key may have expired or may not have been installed correctly.

$ifail = - 999$: Dynamic memory allocation failed.

Accuracy

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.

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

Open in the MATLAB editor: g05tg_example

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

PDF version (NAG web site, 64-bit version, 64-bit version)

Chapter Contents

Chapter Introduction

NAG Toolbox