Skip to contents

Summarize a tbl_sample

Source: R/summary.R
summary.tbl_sample.Rd

Produces a compact summary of a sample: one section per executed stage with a design line and a realization line, followed by weight diagnostics.

Usage

# S3 method for class 'tbl_sample'
summary(object, ...)

Arguments

object

A tbl_sample object produced by execute().

...

Must be empty.

Value

Invisibly returns object. Called for its side effect of printing a summary.

Details

The header line shows the total sample size (with the universe size when the frame digest records a complete denominator and the executed path has no with-replacement stage), the stages executed, and the seed.

Each stage section has two lines:

  • the design: method (with with-replacement and approximate-probabilities qualifiers), measure of size, cluster and stratification variables, and balancing declarations.

  • the realization: population and sample sizes with the sampling fraction. Stages with several selection pools report ranges (N_h, n_h, f_h) and, for later stages, how many of the universe pools the realization reached. f_h is a realized sampling fraction, not a unit-level inclusion probability for unequal-probability designs.

Per-pool detail (one row per parent-by-stratum pool and realization) lives in frame_summary() with detail = "pool". The realization line uses compact sampling notation: N_h, n_h, and f_h correspond to that table's N, n_realized, and take_rate columns, respectively, and take_rate is n_realized / N. Here h indexes the displayed selection pools: strata at a first stratified stage and parent-by-stratum pools at later stages. For a replicated execution, the pool table has one row per pool_id and replicate.

Weights reports the mean and range, coefficient of variation, Kish design effect, and effective sample size on one line. The Kish DEFF token is the weighting loss alone, as computed by design_effect() on the .weight column. Clustering and stratification also move precision and are invisible in the weights, so a design effect that reflects them needs as_svydesign() and survey::svymean(deff = TRUE).

See also

tbl_sum.tbl_sample() for the compact print method, frame_summary() for per-pool allocation tables, as_svydesign() for exporting to the survey package

Other diagnostics: design_effect, frame_summary(), joint_expectation(), sample-columns, varcomp.tbl_sample()

Examples

sample <- sampling_design() |>
  stratify_by(region, alloc = "proportional") |>
  draw(n = 300) |>
  execute(bfa_eas, seed = 42)

summary(sample)
#> ── Sample Summary ──────────────────────────────────────────────────────────────
#> 
#> ℹ n = 300 of 44,570 | stages = 1/1 | seed = 42
#> 
#> ── Stage 1 ─────────────────────────────────────────────────────────────────────
#> • srswor, by region (proportional)
#> • 13 strata: N_h 1,612-5,505, n_h 11-37, f_h 0.0066-0.0068
#> 
#> ── Weights ─────────────────────────────────────────────────────────────────────
#> • Mean 148.57 [146.5, 151.22] | CV 0.01 | Kish DEFF 1 | n_eff 300
#>