NAG Library Function Document
nag_rand_sample_unequal (g05nec) selects a pseudorandom sample, without replacement and allowing for unequal probabilities.
||nag_rand_sample_unequal (Nag_SortOrder sortorder,
const double wt,
const Integer ipop,
nag_rand_sample_unequal (g05nec) selects elements from either the set of values or a supplied population vector of length . The probability of selecting the th element is proportional to a user-supplied weight, . Each element will appear at most once in the sample, i.e., the sampling is done without replacement.
One of the initialization functions nag_rand_init_repeatable (g05kfc)
(for a repeatable sequence if computed sequentially) or nag_rand_init_nonrepeatable (g05kgc)
(for a non-repeatable sequence) must be called prior to the first call to nag_rand_sample_unequal (g05nec).
sortorder – Nag_SortOrderInput
: a flag indicating the sorted status of the wt
- wt is sorted in ascending order,
- wt is sorted in descending order,
- wt is unsorted and nag_rand_sample_unequal (g05nec) will sort the weights prior to using them.
Irrespective of the value of sortorder
, no checks are made on the sorted status of wt
, e.g., it is possible to supply
, even when wt
is not sorted. In such cases the wt
array will not be sorted internally, but nag_rand_sample_unequal (g05nec) will still work correctly except, possibly, in cases of extreme weight values.
It is usually more efficient to specify a value of sortorder
that is consistent with the status of wt
, or .
wt[n] – const doubleInput
On entry: , the relative probability weights. These weights need not sum to .
- , for ;
- at least m values must be nonzero.
ipop – const IntegerInput
the dimension, dim
, of the array ipop
must be at least
is not NULL
: the population to be sampled. If
then the population is assumed to be the set of values
and the array ipop
is not referenced. Elements of ipop
with the same value are not combined, therefore if
then there is a nonzero probability that the sample will contain both
then that value can appear in isampl
more than once.
n – IntegerInput
On entry: , the size of the population.
isampl[m] – IntegerOutput
On exit: the selected sample.
m – IntegerInput
On entry: , the size of the sample required.
state – IntegerCommunication Array
, of this array is dictated by the requirements of associated functions that must have been previously called. This array MUST be the same array passed as argument state
in the previous call to nag_rand_init_repeatable (g05kfc)
or nag_rand_init_nonrepeatable (g05kgc)
On entry: contains information on the selected base generator and its current state.
On exit: contains updated information on the state of the generator.
fail – NagError *Input/Output
The NAG error argument (see Section 3.6
in the Essential Introduction).
6 Error Indicators and Warnings
Dynamic memory allocation failed.
On entry, argument had an illegal value.
On entry, .
On entry, and .
An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG
On entry, state
vector has been corrupted or not initialized.
On entry, at least one weight was less than zero.
, number of nonzero weights
Constraint: must be at least m
8 Parallelism and Performance
nag_rand_sample_unequal (g05nec) internally allocates
doubles and n
Although it is possible to use nag_rand_sample_unequal (g05nec) to sample using equal probabilities, by setting all elements of the input array wt
to the same positive value, it is more efficient to use nag_rand_sample (g05ndc)
. To sample with replacement, nag_rand_gen_discrete (g05tdc)
can be used when the probabilities are unequal and nag_rand_discrete_uniform (g05tlc)
when the probabilities are equal.
This example samples from a population of .
10.1 Program Text
Program Text (g05nece.c)
10.2 Program Data
Program Data (g05nece.d)
10.3 Program Results
Program Results (g05nece.r)