Variance Components from an Executed Sample

Estimate design-based variance components (B, W, delta, 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.

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 delta 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

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
#> delta = 0.0245
#> k = 1.5572
#> Unit relvariance = 15.5876
as.data.frame(vc)
#>   stages      varb     varw      delta        k  rel_var
#> 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), delta = vc,
                   budget = 100000)
#> Optimal 2-stage allocation
#> field design: n_psu = 74 | psu_size = 17 -> total n = 1258
#> cv = 0.1639, cost = 99900
#> continuous optimum: n_psu = 66.81355 | psu_size = 19.93405 (cv = 0.1634, cost = 100000)