Variance components from an executed sample

Estimate design-based variance components (B, W, icc, k) from a tbl_sample, for planning the next round with svyplan::n_cluster(). The method extracts everything the estimation needs from the sample's design columns, applying two conventions that are easy to get wrong by hand:

Usage

varcomp(x, ...)

# S3 method for class 'tbl_sample'
varcomp(x, ..., strata = NULL)

Arguments

x

A tbl_sample with at least one executed clustered stage.

...

The outcome as a one-sided formula, e.g. varcomp(x, ~y), mirroring the survey.design method. Nothing else belongs here: strata follows the ... and so is matched exactly, so a near miss such as strat or a second positional formula is reported rather than silently dropped.

strata

Optional one-sided formula naming a column to estimate per-stratum components by, when the first stage was not stratified. Stage-1 design strata are picked up automatically. Combining them with strata is an error, because per-stratum components crossed with design strata are ambiguous.

Value

A svyplan_varcomp object. Pass it as icc to svyplan::n_cluster(). Use as.data.frame() to export either the one-row unstratified components or the per-stratum component table.

Details

• Within-PSU weights. The components are weighted by the product of the per-stage weights below stage 1 (.weight_2, or .weight_2 * .weight_3), never the compound .weight, whose stage-1 factor would overstate every cluster size.

• Stage-1 selection shares. For an unequal-probability first stage, per-PSU shares are derived from the stage-1 weights and normalized to sum to 1 over the sampled PSUs (per stratum when the first stage is stratified). For an equal-probability first stage the SRS path applies. See the Details of svyplan::varcomp().

The decomposition covers the clustered stages plus the sample rows as elements: one clustered stage gives 2-stage components, two give 3-stage. Deeper designs are refused. Estimate the top stages and fold the rest into a design effect. With-replacement (WR/PMR) stages treat each draw as an independent unit, keyed by the .draw_k column as in as_svydesign(): a cluster hit twice enters the decomposition twice, with its share counted per draw. Two-phase samples are refused: the nested decomposition does not model phase sampling. Certainty PSUs are refused: self-representing PSUs contribute no between-PSU variance and belong in their own stratum, so estimate components on the probability part of the design.

Variance-component estimation should use this method on the tbl_sample directly, not as_svydesign(): the exported design carries the compound weight and encodes stage probabilities in fpc conventions that varcomp cannot see.

See also

svyplan::varcomp() for the estimator and its conventions, svyplan::n_cluster() for planning with the result

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

Examples

# Two-stage sample: 8 of 24 clusters by PPS, 3 persons per cluster
set.seed(7)
frame <- data.frame(
  cl = rep(sprintf("c%02d", 1:24), each = 5),
  size = rep(rep(c(80, 120, 160, 200), 6), each = 5),
  y = rnorm(120) + rep(rnorm(24, sd = 0.4), each = 5)
)
sam <- sampling_design() |>
  add_stage() |> cluster_by(cl) |>
  draw(n = 8, method = "pps_brewer", mos = size) |>
  add_stage() |> draw(n = 3) |>
  execute(frame, seed = 11)

vc <- varcomp(sam, ~y)
vc
#> Variance components (2-stage)
#> varb = 0.5959, varw = 23.6774
#> icc = 0.0245
#> var_ratio = 1.5572
#> Unit relvariance = 15.5876
as.data.frame(vc)
#>   stages      varb     varw        icc var_ratio unit_relvar
#> 1      2 0.5958577 23.67737 0.02454793  1.557215    15.58759

# Feed the components into next-round cluster planning
svyplan::n_cluster(stage_cost = c(500, 50), icc = vc,
                   budget = 100000)
#> Optimal 2-stage allocation
#> field design: n_psu = 74 | n_per_psu = 17 -> total n = 1258
#> cv = 0.1639, cost = 99900
#> continuous optimum: n_psu = 66.81355 | n_per_psu = 19.93405 (cv = 0.1634, cost = 100000)
#> design df = 73