naginterfaces.library.rand.sample_​wgt

naginterfaces.library.rand.sample_wgt(order, wt, m, statecomm, ipop=None)

sample_wgt selects a pseudorandom sample, without replacement and allowing for unequal probabilities.

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

https://support.nag.com/numeric/nl/nagdoc_30.3/flhtml/g05/g05nef.html

Parameters

orderstr, length 1

A flag indicating the sorted status of the $wt$ vector.

$order=\text{‘A'}$

$wt$ is sorted in ascending order,

$order=\text{‘D'}$

$wt$ is sorted in descending order,

$order=\text{‘U'}$

$wt$ is unsorted and sample_wgt will sort the weights prior to using them.

Irrespective of the value of $order$, no checks are made on the sorted status of $wt$, e.g., it is possible to supply $order=\text{‘A'}$, even when $wt$ is not sorted.

In such cases the $wt$ array will not be sorted internally, but sample_wgt will still work correctly except, possibly, in cases of extreme weight values.

It is usually more efficient to specify a value of $order$ that is consistent with the status of $wt$.

wtfloat, array-like, shape $\left(n\right)$

$w_i$, the relative probability weights. These weights need not sum to $1.0$.

mint

$m$, the size of the sample required.

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 $(:)$, optional

Note: the required length for this argument is determined as follows: if $ipop\text{is not}None$: $n$; otherwise: $0$.

The population to be sampled. If $ipop\text{is}None$ then the population is assumed to be the set of values $(1,2,\dots ,n)$ and the array $ipop$ is not referenced. Elements of $ipop$ with the same value are not combined, therefore, if $wt[i-1]\ne 0,wt[j-1]\ne 0$ and $i\ne j$ then there is a nonzero probability that the sample will contain both $ipop[i-1]$ and $ipop[j-1]$. If $ipop[i-1]=ipop[j-1]$ then that value can appear in $isampl$ more than once.

Returns

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

The selected sample.

Raises

NagValueError

(errno $1$)

On entry, $order$ had an illegal value.

(errno $2$)

On entry, at least one weight was less than zero.

(errno $5$)

On entry, $n=⟨value⟩$.

Constraint: $n\ge 1$.

(errno $7$)

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

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

(errno $8$)

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

(errno $21$)

On entry, $m=⟨value⟩$, number of nonzero weights $=⟨value⟩$.

Constraint: must be at least $m$ nonzero weights.

Notes

sample_wgt selects $m$ elements from either the set of values $(1,2,\dots ,n)$ or a supplied population vector of length $n$. The probability of selecting the $i$th element is proportional to a user-supplied weight, $w_i$. Each element will appear at most once in the sample, i.e., the sampling is done without replacement.

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