bootstrap_variance.survey.design: Bootstrap for survey designs via replicate weights

Description

Bootstrap for survey designs via replicate weights

Usage

bootstrap_variance.survey.design(
  data,
  estimator_func,
  point_estimate,
  bootstrap_reps = 500,
  survey_na_policy = c("strict", "omit"),
  ...
)

Value

A list with components se, variance, and replicates.

Arguments

data

A survey.design.

estimator_func

Function returning an object with a numeric scalar component y_hat and an optional logical component converged.

point_estimate

Numeric scalar; used for survey bootstrap variance (passed to survey::svrVar() as coef).

bootstrap_reps

integer; number of bootstrap replicates.

survey_na_policy

Character string specifying how to handle replicates that fail to produce estimates. Options:

"strict": (default) Any failed replicate causes an error. This is a conservative default that makes instability explicit.

"omit"

Failed replicates are omitted. The corresponding rscales are also omitted to maintain correct variance scaling. Use with caution: if failures are non-random, variance may be biased.

...

Additional arguments. Some are consumed by bootstrap_variance() itself (for example resample_guard for IID bootstrap or bootstrap_settings/bootstrap_options/bootstrap_type/bootstrap_mse for survey bootstrap); remaining arguments are forwarded to estimator_func.

Limitations

Calibrated/post-stratified designs: Post-hoc adjustments applied via survey::calibrate(), survey::postStratify(), or survey::rake() are not supported here and will cause the function to error. These adjustments are not recomputed when replicate weights are injected, so the replicate designs would not reflect the intended calibrated/post-stratified analysis.

Details

This path constructs a replicate-weight design using svrep::as_bootstrap_design() and evaluates the estimator on each set of bootstrap replicate analysis weights.

Replicate evaluation starts from a shallow template copy of the input survey design (including its ids/strata/fpc structure) and injects each replicate's analysis weights by updating the design's probability slots (prob/allprob) so that weights(design) returns the desired replicate weights (with zero weights represented as prob = Inf). This avoids replaying or reconstructing a svydesign() call and therefore supports designs created via subset() and update().

NA policy: By default, survey bootstrap uses a strict NA policy: if any replicate fails to produce a finite estimate, the entire bootstrap fails with an error. Setting survey_na_policy = "omit" drops failed replicates (and their corresponding rscales) and proceeds with the remaining replicates.