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_poisson_varmean (g05tk)

## Purpose

nag_rand_int_poisson_varmean (g05tk) generates a vector of pseudorandom integers, each from a discrete Poisson distribution with differing parameter.

## Syntax

[state, x, ifail] = g05tk(vlamda, state, 'm', m)
[state, x, ifail] = nag_rand_int_poisson_varmean(vlamda, state, 'm', m)

## Description

nag_rand_int_poisson_varmean (g05tk) generates $m$ integers ${x}_{j}$, each from a discrete Poisson distribution with mean ${\lambda }_{j}$, where the probability of ${x}_{j}=I$ is
 $P xj=I = λjI × e -λj I! , I=0,1,… ,$
where
 $λj ≥ 0 , j=1,2,…,m .$
The methods used by this function have low set up times and are designed for efficient use when the value of the parameter $\lambda$ changes during the simulation. For large samples from a distribution with fixed $\lambda$ using nag_rand_int_poisson (g05tj) to set up and use a reference vector may be more efficient.
When $\lambda <7.5$ the product of uniforms method is used, see for example Dagpunar (1988). For larger values of $\lambda$ an envelope rejection method is used with a target distribution:
 $fx=13 if ​x≤1, fx=13x-3 otherwise.$
This distribution is generated using a ratio of uniforms method. A similar approach has also been suggested by Ahrens and Dieter (1989). The basic method is combined with quick acceptance and rejection tests given by Maclaren (1990). For values of $\lambda \ge 87$ Stirling's approximation is used in the computation of the Poisson distribution function, otherwise tables of factorials are used as suggested by Maclaren (1990).
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_poisson_varmean (g05tk).

## References

Ahrens J H and Dieter U (1989) A convenient sampling method with bounded computation times for Poisson distributions Amer. J. Math. Management Sci. 1–13
Dagpunar J (1988) Principles of Random Variate Generation Oxford University Press
Maclaren N M (1990) A Poisson random number generator Personal Communication

## Parameters

### Compulsory Input Parameters

1:     $\mathrm{vlamda}\left({\mathbf{m}}\right)$ – double array
The means, ${\lambda }_{\mathit{j}}$, for $\mathit{j}=1,2,\dots ,{\mathbf{m}}$, of the Poisson distributions.
Constraint: $0.0\le {\mathbf{vlamda}}\left(\mathit{j}\right)\le {\mathbf{x02bb}}/2.0$, for $\mathit{j}=1,2,\dots ,{\mathbf{m}}$.
2:     $\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{m}$int64int32nag_int scalar
Default: the dimension of the array vlamda.
$m$, the number of Poisson distributions for which pseudorandom variates are required.
Constraint: ${\mathbf{m}}\ge 1$.

### Output Parameters

1:     $\mathrm{state}\left(:\right)$int64int32nag_int array
Contains updated information on the state of the generator.
2:     $\mathrm{x}\left({\mathbf{m}}\right)$int64int32nag_int array
The $m$ pseudorandom numbers from the specified Poisson distributions.
3:     $\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{m}}\ge 1$.
${\mathbf{ifail}}=2$
On entry, at least one element of vlamda is less than zero.
On entry, at least one element of vlamda is too large.
${\mathbf{ifail}}=3$
On entry, state vector has been corrupted or not initialized.
${\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.

Not applicable.

None.

## Example

This example prints ten pseudorandom integers from five Poisson distributions with means ${\lambda }_{1}=0.5$, ${\lambda }_{2}=5$, ${\lambda }_{3}=10$, ${\lambda }_{4}=500$ and ${\lambda }_{5}=1000$. These are generated by ten calls to nag_rand_int_poisson_varmean (g05tk), after initialization by nag_rand_init_repeat (g05kf).
```function g05tk_example

fprintf('g05tk 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 sets of variates
n = 10;
% Parameters
vlamda = [0.5; 5; 10; 500; 1000];
m = numel(vlamda);

x = zeros(n, m, 'int64');

% Generate n sets of the m variates
for i = 1:n
[state, x(i, :), ifail] = g05tk( ...
vlamda, state);
end

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

```
```g05tk example results

Variates
1           6          12         507        1003
0           9          11         520        1028
1           3           7         483        1041
0           3          11         513        1012
1           5           9         496         940
0           6          17         548         990
1           9           8         512        1035
0           4          10         458        1029
1           6          13         523         971
0           9          16         519         999

```