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, ...)

# S3 method for class 'summary_tbl_sample'
print(x, ...)

Arguments

object

A tbl_sample object produced by execute().

...

Must be empty.

x

A summary_tbl_sample object.

Value

A summary_tbl_sample object, which prints the summary below. Its fields hold the figures the print shows: n, stages, seed, weights (mean, minimum, maximum and coefficient of variation of .weight), design_effect and effective_n (as design_effect() and effective_n() give them), certainty, the units taken with certainty at each executed stage, and single_unit_pools, the pools of one unit each stage took whole. Such a unit is certain too, as .certainty_k records, but it is counted only in single_unit_pools, so a stage of unsegmented EAs does not read as large units taken for their size. periods is NULL unless the sample is split into periods(). It then holds k and a pools table with each pool's fewest and most units per period (min, max). Weight figures are NULL for an empty sample and for stacked replicates, which the print also leaves out. sample is the summarized sample itself.

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. Under frame_digest = "none" the header shows the sample size alone, since nothing records the size of the frame. When the later stages were drawn one wave at a time, the header shows the seeds of the draws the rows come from, such as seeds = 101 to 112 for the completed master. A wave shows the seed of the draw that took its units. The header shows no seed when one of those draws ran without one.

A sample split into periods() gets one more line, which says whether each stratum has the same number of units in every period and names the strata that do not, for example "Periods: 12, even in 10 of 13 strata." followed by "Uneven: Cascades (2 to 3 per period), Centre-Nord (3 to 4)." When every stratum is even, the line gives the range of units per period instead. This is the table fieldwork is planned from, and an uneven stratum shows an allocation that is not a multiple of the number of periods. While the later stages are drawn one period at a time, a line such as "Drawn: stage 2 in 3 of 12 periods (1, 2, 5)." says how far they are.

A materialized wave, period or window describes itself. A line such as "Period: 2 of 4. It holds 26 of the master's 104 units." names it and counts the units its panels were assigned to, each once however many of the waves activate it. Its stage sections count the wave's own units, with or without a frame digest, since the digest records the master's draw. A stage drawn for the wave alone is read from the wave's part of the digest. The master's own summary describes its draw.

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.

For a sample returned by share_weights(), the rows are target units, while the stage sections and the certainty and single_unit_pools fields describe the source sample the weights were shared from. The header line and the weight figures describe the target rows.

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: compare_designs(), 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
#>