Skip to contents

Inclusion Probabilities

Source: R/generics.R
inclusion_prob.Rd

Compute inclusion probabilities from a size measure, or extract them from a without-replacement design object.

Usage

inclusion_prob(x, ...)

# S3 method for class 'wor'
inclusion_prob(x, ...)

# S3 method for class 'wr'
inclusion_prob(x, ...)

# Default S3 method
inclusion_prob(x, n, ...)

Arguments

x

A numeric vector of positive size measures, or a without-replacement design object (class "wor").

...

Reserved for methods. The methods provided by sondage currently take no additional arguments.

n

The desired sample size, or the expected sample size of a random-size design, which may be fractional. Required when x is a numeric vector. It must not be supplied when x is a design object.

Value

A numeric vector of inclusion probabilities. When applied to a design object, returns the stored pik vector. For most methods this equals the true first-order inclusion probabilities. For order-sampling methods (sps, pareto), it is the target used to define the design; the true probabilities are approximately equal and converge as N grows. Names on a numeric x are preserved.

Details

When x is a numeric vector and n is provided, computes inclusion probabilities via iterative capping: units with \(\pi_k \ge 1\) are set to 1 (certainty selections) and the remaining probabilities are recomputed with reduced \(n\). The result sums to exactly \(n\). This differs from expected_hits(), which does simple proportional allocation without capping. Negative values in x are treated as zero (with a warning).

n may be any real number from 0 to the number of units with positive size. A fractional n is the expected size of a random-size design, such as Poisson sampling. Fixed-size samplers, unequal_prob_wor() among them, require probabilities that sum to a whole number and refuse others.

With-replacement designs

inclusion_prob() applies only to without-replacement (wor) designs. Calling it on a with-replacement design object (e.g. from equal_prob_wr() or unequal_prob_wr()) is an error; use expected_hits() to obtain the expected number of selections.

See also

expected_hits() for the with-replacement analogue, unequal_prob_wor() for sampling with these probabilities.

Examples

# From size measures
size <- c(10, 20, 30, 40)
pik <- inclusion_prob(size, n = 2)
sum(pik)  # 2
#> [1] 2

# From a design object
s <- unequal_prob_wor(pik, method = "cps")
inclusion_prob(s)
#> [1] 0.2 0.4 0.6 0.8

# With certainty selections (large units)
size <- c(1, 1, 1, 100)
pik <- inclusion_prob(size, n = 2)
pik  # Unit 4 gets probability 1
#> [1] 0.3333333 0.3333333 0.3333333 1.0000000

# The expected size of a random-size design need not be a whole number
pik <- inclusion_prob(rep(1, 10), n = 2.6)
sum(pik)  # 2.6
#> [1] 2.6
unequal_prob_wor(pik, method = "poisson")       # valid
#> Unequal prob WOR [poisson] (expected n=2.6, realized n=1, N=10): 10 
try(unequal_prob_wor(pik, method = "sampford")) # refused: fixed size
#> Error : sum(pik) = 2.6 is not close to an integer