Summarize the population structure recorded with a sample

An executed sample can carry a frame digest: a compact record of the frames, selection pools, resolved selection chances, and allocation that each stage encountered at execution time. frame_summary() turns that record into documented tibbles, so the structure of the selection remains intelligible after the original frame has gone away.

Usage

frame_summary(
  x,
  stage = NULL,
  scope = c("eligible", "universe"),
  detail = c("stage", "pool", "unit")
)

Arguments

x

A tbl_sample produced by execute() that carries a frame digest, or a sampling_design restored by read_design() whose file was written from an executed sample: the execution receipt carries the digest, so a shipped design file supports next-wave planning without the frame or the sample.

stage

An integer vector of stage numbers to report, or NULL (default) for all recorded stages.

scope

Denominator basis for population sizes and take rates. With "eligible" (default), denominators cover the units that were eligible for the recorded execution. With "universe", denominators are reported only where the digest covers the full population hierarchy. Denominators that the recorded scope cannot support are NA, never invented.

detail

Resolution of the report: "stage" (one row per stage), "pool" (one row per selection pool), or "unit" (one row per population unit, only for stages that retained a unit-level representation).

Value

A tibble. The scope column always states how complete the underlying representation is ("eligible", "universe", "conditional", "partial", or "unknown").

For detail = "stage", one row per stage with stage, unit_level, scope, chance_kind, probabilities, storage, n_pools, N, n_target, n_expected, n_realized, and take_rate.

For detail = "pool", one row per selection pool with stage, pool_id, parent_unit, any stratum label columns, N, n_target, n_expected, n_realized, scope, chance_status, chance (the constant per-unit chance where one applies, NA otherwise), and take_rate. Stratum columns of stages that do not use them are NA.

For detail = "unit", one row per population unit of each stage that stored units, with stage, pool_id, unit_id, unit_order, chance, is_certainty, n_descendants, is_selected, and n_hits. Stages that stored only a constant or a chance distribution contribute no rows; requesting such a stage explicitly is an error rather than a silently empty result.

Details

take_rate is n_realized / N. It is a take rate, not an inclusion probability: for unequal-probability designs the two differ by design. chance_kind states what the recorded chances mean: first-order inclusion probabilities for without-replacement stages, expected hits for with-replacement stages. probabilities states how well the stage's method honors them: "exact" when the recorded chances equal the design's true first-order chances, "approximate" when the method treats them as a target achieved to a documented approximation ("pps_sps", "pps_pareto", and registered methods declared probabilities = "approximate"), and NA for digests recorded before the field existed.

Allocation is reported as three quantities that only coincide for fixed-size designs: n_target (requested), n_expected (sum of resolved chances), and n_realized (selected units or occurrences). For replicated executions, allocation quantities are per replicate: when the realized allocation is identical across replicates the common value is reported, and when it varies (random-size designs) n_realized and take_rate are NA rather than a guess. Unit detail spans the stacked replicates: is_selected marks units selected in at least one replicate and n_hits counts occurrences across all replicates, so a without-replacement unit can show n_hits > 1. The per-replicate trace is the replicate column of the digest's selected units. A replicated multi-stage execution records only the stage prefix shared by every replicate: later-stage pools hang off each replicate's own selected parents, so those stages are not part of the manifest and frame_summary() says so.

A digest whose sample was modified after execution (rows, weights, or design columns changed) is reported as invalidated and refused: a stale digest is worse than no digest.

See also

execute(), validate_frame()