Selection probabilities a design would give a register, without drawing

Returns the probability that each unit of a register would be selected, computed from the design rather than observed from a sample. It draws no random numbers, and it needs no execution. By default, every stage must supply exact inclusion probabilities. Approximate targets require allow_approximate = TRUE and are labelled in the result.

The intended use is a survey covering one population through several registers, where the expected multiframe estimator needs a unit's chance in the frames it was not selected from. See exante_overlaps(), which resolves those chances for a whole stack_frames() collection.

Usage

exante_probabilities(design, frame, ..., key, allow_approximate = FALSE)

Arguments

design: A sampling_design with a complete draw() on every stage.
frame: The register, a data frame.
...: Must be empty. Arguments after it are matched by exact name.
key: A bare column of frame identifying the population unit. It must be unique and cannot be named probability or probability_quality.
allow_approximate: Logical, default FALSE. Explicitly accept approximate probability targets, with the limitations described above.

Value

A tibble with the key column, probability, and probability_quality ("exact" or "approximate"), one row per unit in the register's own order. Quality reflects the weakest stage's probability contract.

Details

The probability is compounded across stages: for a two-stage design it is the chance the unit's cluster is selected times the chance the unit is selected within it. The stage-by-stage quantities come from the same allocation and chance resolvers execution uses, so a sample's own weights reproduce these numbers exactly. Agreement with weights verifies that the same targets were used. It does not establish that approximate targets are the method's actual inclusion probabilities.

Approximate probabilities

pps_sps and pps_pareto, and custom methods declaring approximate probabilities, are refused by default. With allow_approximate = TRUE, their targets are returned and compounded across stages. The whole result is labelled "approximate" if any stage has this probability contract, including rows selected with certainty. Estimators using these targets need not be design-unbiased. Methods declaring "unknown" probabilities remain unsupported even with this opt-in.

What it refuses

A with-replacement or minimum-replacement stage, because the quantity there is an expected number of hits rather than an inclusion probability, and a method whose registered probabilities are "unknown". It also refuses a design given several registers, one per stage: the compounding runs along the rows of one register and there is no correspondence between the rows of two.

frame_summary() answers a different question. It reports the pools and chances a design resolves, at whatever resolution the digest retained, and returns no unit rows at all where that was a quantile summary.

References

Lohr, S. L. (2021). Multiple-frame surveys for a multiple-data-source world. Survey Methodology, 47(2), 229-263.

Examples

register <- data.frame(
  person_id = 1:40,
  size = rep(c(2, 5, 3, 8), times = 10)
)

design <- sampling_design() |>
  draw(n = 10, method = "pps_brewer", mos = size)

head(exante_probabilities(design, register, key = person_id))
#> # A tibble: 6 × 3
#>   person_id probability probability_quality
#>       <int>       <dbl> <chr>              
#> 1         1       0.111 exact              
#> 2         2       0.278 exact              
#> 3         3       0.167 exact              
#> 4         4       0.444 exact              
#> 5         5       0.111 exact              
#> 6         6       0.278 exact              

# The design's own sample carries the same numbers, as 1 / .weight.
sample <- execute(design, register, seed = 1)
resolved <- exante_probabilities(design, register, key = person_id)
all.equal(
  resolved$probability[match(sample$person_id, resolved$person_id)],
  1 / sample$.weight
)
#> [1] TRUE