Register a Custom Unequal Probability Sampling Method

Register a user-defined sampling method so it can be used through unequal_prob_wor() or unequal_prob_wr() and their associated generics.

Usage

register_method(
  name,
  type = c("wor", "wr"),
  sample_fn,
  joint_fn = NULL,
  fixed_size = TRUE,
  supports_prn = FALSE
)

Arguments

name: A unique method name (character string). Must not collide with a built-in method name.
type: "wor" (without replacement) or "wr" (with replacement).
sample_fn: A function that draws a sample. See Contracts below.
joint_fn: An optional function that computes joint inclusion probabilities (WOR) or joint expected hits (WR). If NULL, joint_inclusion_prob() / joint_expected_hits() will error for this method.
fixed_size: Does this method always produce exactly n units?
supports_prn: Does this method support permanent random numbers for sample coordination?

Value

Invisible NULL, called for its side effect.

Contracts

sample_fn(pik, n = NULL, prn = NULL, ...)

pik: Inclusion probabilities (WOR) or expected hits (WR), numeric vector of length N.
n: Target sample size (integer). For WOR this equals round(sum(pik)); for WR round(sum(hits)).
prn: Permanent random numbers (numeric vector length N, values in (0,1)), or NULL.
Returns: Integer vector of selected unit indices (1-based). For WOR: distinct indices of length n (fixed-size) or varying length (random-size). For WR: indices with possible repeats, of length n.

joint_fn(pik, sample_idx = NULL, ...) (optional)

pik: Same as above.
sample_idx: When non-NULL, an integer vector of sampled unit indices. Return only the submatrix for these units.
Returns: Symmetric matrix of joint inclusion probabilities (N x N when sample_idx is NULL, length(sample_idx) x length(sample_idx) otherwise).

Examples

# Register a toy random sampler
my_sampler <- function(pik, n = NULL, prn = NULL, ...) {
  sample.int(length(pik), size = n, prob = pik)
}
register_method("toy", type = "wor", sample_fn = my_sampler)
s <- unequal_prob_wor(c(0.3, 0.3, 0.4), method = "toy")
s$method
#> [1] "toy"

# Clean up
unregister_method("toy")