Resolve a design's full ex-ante digest from a frame, without drawing

Enumerates every pool of every stage over the universe frame and resolves the first-order chances the design would use, exactly as execution resolves them: parents split before strata, stratum allocation replayed, chances from the same formulas the selection engine applies. Nothing is drawn and no random numbers are consumed: every pool carries chance_status "design_resolved", scope "universe" and n_realized 0, with no selected trace.

Usage

exante_digest(design, frame, call = rlang::caller_env())

Arguments

design: A complete sampling_design (a draw() at every stage).
frame: The sampling frame the design targets: one data frame for a shared hierarchy, or an ordered list of stage registers, as execute() takes them. Frames are read and checked with the same grammar execute() applies, so a frame this accepts is one execution accepts.
call: Environment reported as the error call.

Value

An ex-ante frame digest list.

Details

Refuses, with class samplyr_error_exante_unsupported, designs whose pool structure depends on the realization: a stage under a with-replacement parent (the occurrence count of each parent is random) or under an element-level stage (no unit registry to nest pools in).

This is an extension API for packages that build on the digest (such as samplens, which draws the ex-ante sampling card from it). The list structure of the returned digest is internal and versioned: it may change between samplyr releases, so extension packages should pin a minimum samplyr version.

Examples

design <- sampling_design() |>
  stratify_by(region, alloc = "proportional") |>
  draw(n = 300)

# Resolved from the frame alone: nothing is drawn, no seed is consumed
digest <- exante_digest(design, bfa_eas)
digest$status
#> [1] "complete"
digest$stages[[1]]$scope
#> [1] "universe"