naginterfaces.library.rand.int_​hypergeom

naginterfaces.library.rand.int_hypergeom(mode, n, ns, np, m, statecomm, comm=None)

int_hypergeom generates a vector of pseudorandom integers from the discrete hypergeometric distribution of the number of specified items in a sample of size $l$, taken from a population of size $k$ with $m$ specified items in it.

For full information please refer to the NAG Library document for g05te

https://support.nag.com/numeric/nl/nagdoc_30.2/flhtml/g05/g05tef.html

Parameters

modeint

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

$mode=2$

Set up reference vector and generate variates.

$mode=3$

Generate variates without using the reference vector.

nint

$n$, the number of pseudorandom numbers to be generated.

nsint

$l$, the sample size of the hypergeometric distribution.

npint

$k$, the population size of the hypergeometric distribution.

mint

$m$, the number of specified items of the hypergeometric distribution.

statecommdict, RNG communication object, modified in place

RNG communication structure.

This argument must have been initialized by a prior call to init_repeat() or init_nonrepeat().

commNone or dict, communication object, optional, modified in place

Communication structure for the reference vector.

If $mode=1$, this argument must have been initialized by a prior call to int_hypergeom.

If $mode=3$, $comm$ is not referenced and may be None.

Returns

xNone or int, ndarray, shape $\left(n\right)$

The pseudorandom numbers from the specified hypergeometric distribution.

Raises

NagValueError

(errno $1$)

On entry, $mode=⟨value⟩$.

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

(errno $2$)

On entry, $n=⟨value⟩$.

Constraint: $n\ge 0$.

(errno $3$)

On entry, $ns=⟨value⟩$ and $np=⟨value⟩$.

Constraint: $0\le ns\le np$.

(errno $4$)

On entry, $np=⟨value⟩$.

Constraint: $np\ge 0$.

(errno $5$)

On entry, $m=⟨value⟩$ and $np=⟨value⟩$.

Constraint: $0\le m\le np$.

(errno $6$)

The value of $ns$, $np$ or $m$ is not the same as when $comm$[‘r’] was set up in a previous call with $mode=0$ or $2$.

(errno $6$)

On entry, some of the elements of the array $comm$[‘r’] have been corrupted or have not been initialized.

(errno $8$)

On entry, $statecomm$[‘state’] vector has been corrupted or not initialized.

Notes

int_hypergeom generates $n$ integers $x_i$ from a discrete hypergeometric distribution, where the probability of $x_i=I$ is

$$\begin{array}{c}\begin{array}{cc}P(i=I)=\frac{l!m!(k-l)!(k-m)!}{I!(l-I)!(m-I)!(k-m-l+I)!k!}& \text{if}I=max(0,m+l-k),\dots ,min(l,m)\text{,}\\ & \\ P(i=I)=0& \text{otherwise.}\end{array}\end{array}$$

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 int_hypergeom with the same parameter values can then use this reference vector to generate further variates. The reference array is generated by a recurrence relation if $lm(k-l)(k-m)<50k^3$, otherwise Stirling’s approximation is used.

One of the initialization functions init_repeat() (for a repeatable sequence if computed sequentially) or init_nonrepeat() (for a non-repeatable sequence) must be called prior to the first call to int_hypergeom.

References

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