Convert a tbl_sample to a replicate-weight survey design

Creates a svyrep.design object from a tbl_sample. The "rwyb" method generates Rao-Wu-Yue-Beaumont factors with the optional svrep package directly from recorded stage mechanisms. Other methods first build a survey::svydesign() object, then call 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",
    "rwyb", "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. For type = "rwyb", only replicates (default 500, integer at least 2), mse (default TRUE) and compress (default TRUE) are accepted.

type

Replicate method passed to survey::as.svrepdesign(). One of "auto", "JK1", "JKn", "BRR", "bootstrap", "subbootstrap", "mrbbootstrap", "Fay", or "rwyb". The last uses svrep rather than survey::as.svrepdesign().

The jackknife, BRR and Fay types are deterministic: one sample gives one set of replicate weights. The bootstrap types resample, so they draw from the session's random stream and two calls on one sample give two different standard errors. Set a seed beforehand to make a result reproducible, as with any resampling in R.

The spread is not small at survey's default of 50 replicates. On a 90-of-600 stratified sample, twelve "bootstrap" calls on one sample ranged over 37% of their mean, falling to 12% at replicates = 200 and 4% at replicates = 4000. A reported bootstrap standard error carries that simulation noise on top of the sampling variance it is estimating, so raise replicates through ... when the second decimal is going to be read.

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, including multistage samples, shared weights and independent frame stacks. "auto" retains survey's method choice. It does not depend on whether svrep is installed. Two-phase replicate export remains unsupported.

Rao-Wu-Yue-Beaumont bootstrap

as_svrepdesign(x, type = "rwyb") supports SRS without replacement, independent draws with replacement (srswr, pps_multinomial), independent Poisson selection (bernoulli, pps_poisson), and combinations of these across stages. It also supports fixed-size PPS WOR (pps_brewer, pps_cps, pps_sampford, pps_systematic) using approximate joint probabilities and warns about this approximation. Equal-probability systematic stages use the SRS approximation governed by systematic_variance. Custom methods must declare a supported variance family. Balanced, spatial, Pareto, SPS and Chromy methods have no built-in RWYB mapping.

The adapter retains stage-specific sampling units, strata and probabilities. With-replacement stages resample draw occurrences, not distinct population units. Certainty units have conditional replicate factor one. Noncertainty singleton strata raise samplyr_error_rwyb_singleton whenever their variance contribution is needed, except under Poisson sampling, whose variance is estimable from one unit.

Every selected parent must have a descendant in the final sample. When a later stage is Poisson, a complete frame digest ("summary" or "full") is required to check this. Export refuses missing selected parents because silently dropping them changes the earlier-stage resampling distribution. Empty samples cannot be exported. These are export limits. Empty Poisson realizations remain valid sampling outcomes.

Replication adds simulation error, so finite replicate variances need not equal analytic variances exactly. Set a seed and increase replicates for stable estimates. With mse = TRUE, factors use scale 1 / replicates, while with mse = FALSE, they use 1 / (replicates - 1). svrep's estimate_boot_sim_cv() can assess simulation error for chosen estimates. The direct export records backend and stage methods in the "samplyr_replication" attribute.

Poisson variance

Generic survey bootstrap and jackknife methods are refused for Poisson sampling: they can lose the variance of its random sample size. Use type = "rwyb". For single-stage element Poisson sampling, as_svydesign() remains available with the analytic Horvitz-Thompson Poisson variance.

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