Convert a tbl_sample to a replicate-weight survey design

Creates a svyrep.design object from a tbl_sample by first converting to a survey::svydesign() object via as_svydesign(), then converting with survey::as.svrepdesign().

Usage

as_svrepdesign(x, ...)

# S3 method for class 'tbl_sample'
as_svrepdesign(
  x,
  ...,
  type = c("auto", "JK1", "JKn", "BRR", "bootstrap", "subbootstrap", "mrbbootstrap",
    "Fay"),
  systematic_variance = c("warn", "approximate", "error")
)

Arguments

x: A tbl_sample object produced by execute().
...: Additional arguments passed to survey::as.svrepdesign() and on to the replicate-weight generator it selects, such as replicates, fay.rho, fpctype, or mse. Every argument must be named, and its name must be one those functions accept: type follows the ... and so is matched exactly, and a near miss such as typ is reported rather than forwarded. design cannot be given here: it is the survey::svydesign() object this verb builds from the sample.
type: Replicate method passed to survey::as.svrepdesign(). One of "auto", "JK1", "JKn", "BRR", "bootstrap", "subbootstrap", "mrbbootstrap", or "Fay".
systematic_variance: What to do about the generic replicate weights built for equal-probability systematic stages. "warn" (default) builds them and warns once per call, naming every affected stage. "approximate" builds them silently, for a caller who has acknowledged the approximation, while "error" refuses. Naming a type is not an acknowledgement, since no type reproduces systematic selection. Census stages are exempt and pps_systematic is unaffected, as in as_svydesign(). The choice and the affected stages are recorded on the returned object in the "samplyr_systematic_variance" attribute.

Value

A svyrep.design object from the survey package.

Details

Replicate conversion supports single-phase designs. For unequal-probability designs (PPS or random-size Poisson), "subbootstrap" and "mrbbootstrap" are the supported replicate types. Other types emit a warning and may fail because inclusion probabilities vary within strata. For fixed-size PPS variance estimation, linearization via as_svydesign() is generally preferred. Two-phase designs should be exported with as_svydesign().

Bootstrap escape hatch for random-size Poisson at stage 1

Some designs cannot be expressed as a linearization-based survey::svydesign() object. Specifically, multi-stage designs with a random-size Poisson method (bernoulli or pps_poisson) at stage 1, and single-stage designs with cluster_by() and multiple rows per sampled cluster, are rejected by as_svydesign() for those methods.

For these cases as_svrepdesign(type = "subbootstrap") (or "mrbbootstrap") is the recommended path. The design is exported with a permissive specification (no finite-population correction at the Poisson stage, no pps argument), and the bootstrap resampler supplies the variance through replicate weights.

This is the package's bootstrap approximation for designs that exact Horvitz-Thompson linearization cannot express in survey::svydesign(). The subbootstrap and mrbbootstrap methods were developed for fixed-size PPS sampling (Antal and Tille 2011). Their behavior on random-size Poisson designs, especially at multiple stages, has weaker theoretical backing and should be treated as an approximation. In particular, the resampling is fixed-size, so it does not capture the variance contribution of the random sample size and can materially understate the total variance of a Poisson-type design. When the exact Poisson linearization is available (single-stage designs), prefer as_svydesign().

Bounded cube, LPM2, and SCPS designs likewise have no native, design-specific replicate variance estimator in samplyr. as_svrepdesign(type = "subbootstrap") and "mrbbootstrap" export a generic PPS bootstrap approximation for them. They do not reproduce the original cube constraints or spatial selection algorithm within each replicate. Treat the resulting variance estimates as approximations, not as exact variance estimators for those designs.

Equal-probability systematic sampling

Equal-probability systematic stages are in the same position, for every replicate type rather than for a subset of them. A jackknife or bootstrap replicate perturbs the realized sample. It does not redraw a random start against the frame in the order the frame was in, which is what generates a systematic sample's variance. Frame ordering or periodicity can therefore make the resulting standard errors too small or too large, in the same direction that ordering moves the true variance. See systematic_variance, and as_svydesign() for how large the analogous gap was measured to be under linearization.

Examples

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

rep_svy <- as_svrepdesign(sample, type = "auto")
survey::svymean(~households, rep_svy)
#>              mean     SE
#> households 71.668 3.6922