Reports, before anything is drawn, how each variance estimator the export functions offer would treat a sample of this design: supported, supported only approximately, or refused, with the condition class the export would raise. Most of the answer is fixed by the design, some by the frame, and a few conditions can only be settled by the sample itself. The report keeps those apart, so a refusal can be designed around before fieldwork rather than discovered at export.
Arguments
- x
A
sampling_design, or atbl_samplestanding for its design.- frame
Optional. The frame the design will be executed on, as
execute()takes it: a data frame, or a list of stage registers. Atbl_sampleis the phase-1 sample of a second phase.
Value
A tibble with one row per estimator and the columns estimator,
call, status, decided_by, phase, stage, class, note and
sample_risk.
Details
Each row is one estimator and the call that requests it:
Taylor linearization,
as_svydesign().Linearization with joint inclusion probabilities,
as_svydesign()with a matrix fromjoint_expectation()passed aspps.The replicate types of
as_svrepdesign(): the jackknife ("JK1","JKn"), balanced repeated replication ("BRR","Fay"), the bootstrap ("bootstrap"), the rescaled bootstrap ("subbootstrap"), the multistage rescaled bootstrap ("mrbbootstrap"), the Rao-Wu-Yue-Beaumont bootstrap ("rwyb") and random groups ("random_groups").
status is "supported" when the export carries the design with no
approximation of its own, "approximate" when it knowingly approximates
part of it (Brewer's approximation for a PPS stage, a systematic stage,
a first stage treated as drawn with replacement), "refused" when the
export stops, and "not applicable" for the joint-probability route when
stage 1 has no unequal probabilities to supply. decided_by says what
settles it: "design" for the methods and the stage and phase structure,
"frame" for what the frame fixes before any draw, such as a stratum
that takes one unit or a stage that takes every unit. class and note
give the condition the export raises and why: for a refusal, the one the
export meets first, and for an approximation, every one that applies.
phase and stage locate the first of them.
sample_risk lists what only the realized sample decides and what it
would do to the estimator: a primary unit left with no rows, a stratum left
with one sampled unit at a random-size or later stage. What the frame shows
about the risk is part of the text, such as how many candidate units have
nothing below them.
Without frame, the frame checks are not run. A stratum that may take one
unit, the pairing BRR needs, several rows per cluster and candidate units
with nothing below them are then listed in sample_risk, and a stage that
takes every unit is not recognized. With a frame the design is resolved
against it as frame_summary() does, without drawing and without using
random numbers.
To assess a second phase, give the phase-1 sample as frame: the report
then covers the two-phase export. A tbl_sample passed as x stands for
its design, and when it is itself a later phase, its earlier phase is used.
Materialized panel waves are not assessed.
The report reads the same rules the exports apply, and a test compares it
with the conditions the exports actually raise on executed samples. It
does not certify an estimator's accuracy beyond that:
?variance_estimation gives the measured error of each approximation.
See also
?variance_estimation for how each selection method's variance
is estimated, frame_summary() and validate_frame() for the checks
before execution.
Other survey export:
as_survey_design.tbl_sample(),
as_survey_rep.tbl_sample(),
as_svrepdesign(),
as_svydesign(),
stack_waves(),
variance_estimation
Examples
design <- sampling_design() |>
add_stage(label = "EAs") |>
stratify_by(region) |>
cluster_by(ea_id) |>
draw(n = 4, method = "pps_brewer", mos = households) |>
add_stage(label = "Households") |>
draw(n = 12)
# From the design alone
variance_estimators(design)[c("estimator", "status", "class")]
#> # A tibble: 11 × 3
#> estimator status class
#> <chr> <chr> <chr>
#> 1 Taylor linearization approximate NA
#> 2 Linearization, joint probabilities refused samplyr_error_pps_rows_per_p…
#> 3 Jackknife (JK1) refused samplyr_error_svrep_conversi…
#> 4 Stratified jackknife (JKn) approximate samplyr_warning_replicate_wr…
#> 5 Balanced repeated replication approximate samplyr_warning_replicate_wr…
#> 6 Fay's balanced repeated replication approximate samplyr_warning_replicate_wr…
#> 7 Bootstrap approximate samplyr_warning_replicate_wr…
#> 8 Rescaled bootstrap supported NA
#> 9 Multistage rescaled bootstrap supported NA
#> 10 Rao-Wu-Yue-Beaumont bootstrap approximate samplyr_warning_rwyb_pps_app…
#> 11 Random groups supported NA
# Against the frame, which settles the checks the frame decides
estimators <- variance_estimators(design, bfa_eas)
estimators[estimators$status == "refused", c("estimator", "class")]
#> # A tibble: 2 × 2
#> estimator class
#> <chr> <chr>
#> 1 Linearization, joint probabilities samplyr_error_pps_rows_per_psu
#> 2 Jackknife (JK1) samplyr_error_svrep_conversion_failed
# A second phase, assessed against its phase-1 sample
phase1 <- sampling_design() |>
stratify_by(region) |>
cluster_by(ea_id) |>
draw(n = 300) |>
execute(bfa_eas, seed = 7)
phase2 <- sampling_design() |> draw(n = 60, method = "pps_sampford",
mos = households)
variance_estimators(phase2, phase1)[c("estimator", "status", "note")]
#> # A tibble: 11 × 3
#> estimator status note
#> <chr> <chr> <chr>
#> 1 Taylor linearization supported NA
#> 2 Linearization, joint probabilities refused A two-phase export takes no `p…
#> 3 Jackknife (JK1) refused No replicate export exists for…
#> 4 Stratified jackknife (JKn) refused No replicate export exists for…
#> 5 Balanced repeated replication refused No replicate export exists for…
#> 6 Fay's balanced repeated replication refused No replicate export exists for…
#> 7 Bootstrap refused No replicate export exists for…
#> 8 Rescaled bootstrap refused No replicate export exists for…
#> 9 Multistage rescaled bootstrap refused No replicate export exists for…
#> 10 Rao-Wu-Yue-Beaumont bootstrap refused No replicate export exists for…
#> 11 Random groups refused Replicates drawn from one real…