Conditions raised during execution

execute() signals five conditions when a selection cannot be realized as written, because a pool held fewer units than the stage asked for. Each is a classed condition carrying a payload, so it can be caught and inspected rather than only read. They are reported once per stage per distinct finding, not once per capped pool and not once per replicate.

Details

A pool holding fewer units than the stage asks for is selected whole, which makes the design non-self-weighting. execute() reports this once per stage for each distinct finding, however many pools capped, however many parent pools the stage ran inside, and however many replicates ran. Which condition you get depends on what happened, not on which part of the package noticed:

samplyr_warning_size_capped: Some pools ran short. The stage left units behind in the pools it did not exhaust. A stage that sets on_capped = "error" in draw() refuses instead, before anything is drawn, with samplyr_error_size_capped and the same stage and payload fields, counted over the candidate pools.
samplyr_warning_census: The stage selected every unit available in the pools it executed, so it contributes no sampling variance. This is a claim about the stage: above the first stage those pools are the ones a sampled ancestor supplied, and the design as a whole is a census only if every stage is.
samplyr_warning_nominal_cap: A random-size method asked for more units than the pool holds. Clamping every chance at one caps the target the stage aims at. It does not select that many units, and the realized size usually lands below the cap.
samplyr_warning_poisson_shortfall: A pps_poisson pool resolved to an expectation more than 5% below what it could have reached, because dominant units saturated at probability 1. Measured against the reachable target, so a pool whose target the population already reduced is charged only for the further reduction saturation caused. See draw().
samplyr_message_allocation_capped: A feasible allocation was redistributed past a saturated stratum. A message, not a warning: nothing went wrong, and simulation loops can silence it with suppressMessages().

One more is reported the same way, once per stage with a payload, although nothing was capped. samplyr_message_singleton_pool names the strata of a fixed-size design without replacement that draw a single unit outside certainty. Such a stratum gives no variance estimate of its own: survey stops on it unless strata are collapsed, and the export warns again. It is a message because one unit per stratum is sometimes the design. Its payload carries pool_keys and n_singleton, the number of such strata, each counted once in every parent it appears in.

samplyr_message_absent_strata names the strata that an explicit n (a named vector or a data frame) gives a positive take but a selected parent does not hold, such as a province with no urban EA under n = data.frame(urban_rural = c("Urban", "Rural"), n = c(2, 2)). That parent's take falls short of the table's total. It is a message, because a parent can lack a category by design. Its payload carries pool_keys, each a parent and the stratum it lacks, and n_absent, the number of such pairs. A stratum missing from the whole stage is refused instead (samplyr_error_alloc_unknown_strata).

A selected unit that has no rows in the next stage's frame is reported the same way under that stage's on_empty = "warn": samplyr_warning_empty_parent, with pool_keys and n_empty. See on_empty in draw().

These are not every condition execute() raises. Panel assignment has one of its own, samplyr_warning_panel_small_pool, documented with small_pool: it is about a pool too small to rotate rather than too small to draw from, fires once for the assignment rather than per stage, and carries no payload.

Every condition carries stage, an operation naming the detected event, and a payload of aggregated detail. Payload fields mean the same thing wherever the event was detected:

pool_keys: The pools affected, qualified by their parent, so a stratum capping inside three clusters reports three pools rather than one.
n_capped, n_pools: Pools affected, out of pools executed.
n_requested: Units the stage asked for.
n_actual: Units selected.
n_available: Units the stage could have reached.
n_reachable: The target after any population bound, which is what a pps_poisson shortfall is measured against.
n_expected: The resolved expectation of a random-size stage.
n_clipped: Units whose computed chance exceeded one. Units taken by an explicit certainty_size/certainty_prop rule sit at one by instruction and are not counted here.
n_moved: Units redistributed by an allocation method.
n_absent: Parent and stratum pairs an explicit n names that the frame does not hold.
n_replicates, varied: How many replicates reported this finding, and whether they reported it identically. When varied is TRUE the pool list is the union across those replicates while the counts describe one of them, and the printed message says so.

Replicates are classified before they are merged, so a replicated execution whose replicates reach genuinely different outcomes reports each one. A design that exhausts its clusters in some replicates and merely runs short in others emits both samplyr_warning_census and samplyr_warning_size_capped, each naming only the pools that produced it. The count of conditions tracks distinct findings, not replicate count.

A field the event does not record is NA, never zero.

frame_digest defaults to "summary", so the ordinary way to read capping is the capped column of frame_summary(sample, detail = "pool"). It compares the executable target with the pool population, so a random-size method realizing below its target is never reported as capped. Reading a digest against a design that does not record the stage leaves capped as NA where a shortfall appears, because which of the two it is cannot be told without the design.

capped marks pools that could not supply the target they were given, so it agrees with samplyr_warning_size_capped pool for pool. It does not mark a stratum whose target an allocation method had already reduced to the stratum population: the digest records the post-cap target, and the two are equal by the time the pool is written. Read the conditions for allocation capping and for a stage census. The column reports what selection could not deliver.

Under frame_digest = "none" there is no digest to read and the condition is the only record. Capturing it needs a calling handler, because tryCatch() unwinds and loses the sample, suppressWarnings() loses the payload, and rlang::catch_cnd() loses the sample:

capped <- NULL
sample <- withCallingHandlers(
  design |> execute(frame, seed = 1, frame_digest = "none"),
  samplyr_warning_size_capped = function(w) {
    capped <<- w$payload$pool_keys
    invokeRestart("muffleWarning")
  }
)

Details

See also