naginterfaces.library.rand.sample

naginterfaces.library.rand.sample(m, statecomm, ipop=None, n=None)

sample selects a pseudorandom sample without replacement from an integer vector.

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

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

Parameters

mint

The sample size.

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

ipopNone or int, array-like, shape $\left(n\right)$, optional

The population to be sampled.

If $ipop$ is None, then the population is assumed to be the set of values $(1,2,\dots ,n)$ and the array $ipop$ is not referenced.

nNone or int, optional

Note: if this argument is None then a default value will be used, determined as follows: $ipop.shape\left[0\right]$.

The number of elements in the population to be sampled.

Returns

isamplint, ndarray, shape $\left(m\right)$

The selected sample.

Raises

NagValueError

(errno $2$)

On entry, $n=⟨value⟩$.

Constraint: $n\ge 1$.

(errno $4$)

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

Constraint: $1\le m\le n$.

(errno $5$)

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

Notes

sample selects $m$ elements from a population vector $ipop$ of length $n$ and places them in a sample vector $isampl$. Their order in $ipop$ will be preserved in $isampl$. Each of the (n;m) possible combinations of elements of $isampl$ may be regarded as being equally probable.

For moderate or large values of $n$ it is theoretically impossible that all combinations of size $m$ may occur, unless $m$ is near $1$ or near $n$. This is because (n;m) exceeds the cycle length of any of the base generators. For practical purposes this is irrelevant, as the time taken to generate all possible combinations is many millenia.

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

References

Kendall, M G and Stuart, A, 1969, The Advanced Theory of Statistics (Volume 1), (3rd Edition), Griffin

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