pf_weighted_subset Interface

public interface pf_weighted_subset

Fills idx with the first size(idx) items of a weighted sequential draw over weights.

Defined as size(idx) calls to pf_weighted_draw%next, not as a second algorithm, so a subset of size k is a prefix of one of size 2k, and stopping a %next loop after k draws gives exactly this. That identity is asserted by the suite rather than intended.

idx is a rank-1 integer(int32) or integer(int64) array, intent(out); weights is real(real64), one per item; seed is integer(int64); stream is optional and is integer(int32) or integer(int64). The population is size(weights) and the number drawn is size(idx) -- note this differs from pf_random_subset, whose second argument is the POPULATION, because here the population is carried by the weights themselves.

Preconditions, all of which abort when idx is non-empty: size(idx) <= size(weights); every weight >= 0; at least one weight > 0; and, for an integer(int32) idx, size(weights) <= huge(1_int32). A zero-sized idx asks for nothing and is a defined no-op.

O(n + k log n), so it is the cheaper form whenever k is small against n; past roughly k = n/2 a caller wanting most of the population is better served by asking for the whole weighted permutation.

Module Procedures