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", "random_groups"),
  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, since this verb builds it from the sample. For type = "rwyb", only replicates (default 500, integer at least 2), mse (default TRUE), compress (default TRUE) and lonely.psu are accepted. lonely.psu = "certainty" treats a final-stage stratum holding one noncertainty unit as taken with certainty, so it adds no variance of its own, whereas the default "fail" refuses such a stratum. For type = "random_groups", only mse (default FALSE) is accepted.

type

Replicate method passed to survey::as.svrepdesign(). One of "auto", "JK1", "JKn", "BRR", "bootstrap", "subbootstrap", "mrbbootstrap", "Fay", "rwyb", or "random_groups". "rwyb" uses svrep rather than survey::as.svrepdesign(), and "random_groups" builds the weights from the replicates of execute(reps = R) (see Details).

The jackknife, BRR and Fay types are deterministic: one sample gives one set of replicate weights. The bootstrap types draw from the session's random stream, so two calls on one sample give two different standard errors unless a seed is set beforehand.

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. Raise replicates through ... when the second decimal of a bootstrap standard error is going to be read.

systematic_variance

What to do about the generic replicate weights built for systematic and pps_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, and "error" refuses. Naming a type is not an acknowledgement, since no type reproduces systematic selection. Census stages are exempt, as in as_svydesign(). The choice and the affected stages are recorded in the "samplyr_systematic_variance" attribute of the result.

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. Two-phase replicate export is unsupported. "auto" keeps survey's method choice, whether or not svrep is installed.

The first stage under the generic types

"JK1", "JKn", "BRR", "Fay", "bootstrap" and "subbootstrap" resample first-stage units within first-stage strata and read nothing below, whereas "mrbbootstrap" and "rwyb" read every stage. A PPS first stage drawn without replacement is read as drawn with replacement, which errs toward too large a variance at large sampling fractions (samplyr_warning_replicate_wr_first_stage, see variance_estimation). Chromy's method is read as with replacement too. Unequal probabilities at later stages, and a first stage drawn with replacement, reach the variance through the weights and draw no warning. In a simulation with "JKn", a PPS second stage gave 0.98 of the true variance, as its SRS counterpart did, while a Brewer first stage with a sampling fraction of 0.4 gave 1.43. A certainty PSU is a stratum of its own whose stage-two units are resampled, and a certainty unit with no stage below keeps its full weight in every replicate. With certainty PSUs these types gave 1.1 to 1.2 times the true variance in a Monte Carlo, and linearization and "rwyb" about 1.0.

Rao-Wu-Yue-Beaumont bootstrap

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. Fixed-size PPS WOR (pps_brewer, pps_cps, pps_sampford, pps_systematic) uses approximate joint probabilities, with a warning. 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 keeps 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, and at the final stage under lonely.psu = "certainty".

Export refuses a selected parent with no descendant in the final sample, because silently dropping it changes the earlier-stage resampling distribution. When a later stage is Poisson, this check needs a complete frame digest ("summary" or "full"). Empty samples cannot be exported. These are export limits, and empty Poisson realizations remain valid sampling outcomes.

Replicate variances carry simulation error, so set a seed and increase replicates for stable estimates. svrep's estimate_boot_sim_cv() assesses that error for chosen estimates. With mse = TRUE the factors use scale 1 / replicates, and with mse = FALSE they use 1 / (replicates - 1). The backend and stage methods are recorded in the "samplyr_replication" attribute.

Random groups

type = "random_groups" takes a sample from execute(reps = R) as R independent samples of the same design (Wolter 2007, ch. 2). The estimate is the mean of the R replicate estimates, carried by the full-sample weight .weight / R, and its variance is their spread divided by R, with R - 1 degrees of freedom. A replicate that selected nothing counts as a zero estimate. Nothing is assumed about the selection method, so the route is right for systematic, balanced, spatial or custom stages, which no other type redraws. On a frame whose period matches a systematic interval it gave 0.997 of the true variance, where one sample's linearization gave 0.0001. The cost is R samples.

The replicates must vary at every stage and phase. A sample that continues one realized stage with reps, or replicates a later phase over one realized first phase, is refused (samplyr_error_random_groups_shared), because the shared selection's variance would be left out. Replicate that stage or phase too, and continue each replicate. The sample must hold every replicate of its execution (samplyr_error_random_groups_input).

Variance by selection method

The generic types are refused for Poisson sampling, which needs "rwyb". Bounded cube, LPM2 and SCPS have only the generic PPS bootstrap of "subbootstrap" and "mrbbootstrap", which does not recreate their constraints or spatial algorithm. Only "random_groups" redraws a systematic start. variance_estimation has each case and the measured error.

References

Rao, J.N.K., Wu, C.F.J. and Yue, K. (1992). Some recent work on resampling methods for complex surveys. Survey Methodology, 18(2), 209-217.

Wolter, K. M. (2007). Introduction to Variance Estimation, 2nd ed. Springer.

Beaumont, J.-F. and Émond, N. (2022). A bootstrap variance estimation method for multistage sampling and two-phase sampling when Poisson sampling is used at the second phase. Stats, 5(2), 339-357. doi:10.3390/stats5020019

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