Skip to contents

Validate a Frame Against a Design

Source: R/validation.R
validate_frame.Rd

Checks if a data frame contains all required variables for a sampling design and reports any issues.

Usage

validate_frame(
  design,
  frame,
  stage = NULL,
  fingerprint = c("inform", "warn", "ignore")
)

Arguments

design

A sampling_design object, or an executed tbl_sample: its stored design is validated and its frame digest (when present) is compared against frame.

frame

A data frame to validate

stage

Which stage(s) to validate against. Default validates all stages.

fingerprint

How to report differences between frame and what was recorded earlier: the frame fingerprint stored in a design file (designs restored with read_design() when saved with frame =) and the frame digest recorded at execution (when design is a tbl_sample, or a restored design whose receipt carries one). One of "inform" (default, emits a message), "warn", or "ignore". Both comparisons are informational and never fail validation, because a design remains executable on any frame that passes the variable checks.

Value

Invisibly returns TRUE if validation passes. Throws an informative error if validation fails.

Details

Validation checks include:

  • Presence of required stratification variables

  • Presence of required clustering variables

  • Presence of measure of size (MOS) variables for PPS sampling

  • Non-empty frame

  • Positive values for MOS variables

For designs restored with read_design(), if the design file carries a frame fingerprint, validate_frame() also compares it against frame and reports what changed (rows, columns, column types, or content).

When a frame digest is available (an executed tbl_sample, or a design file written from one), the structural comparison goes further: the role-scoped fingerprint (analysis columns added later do not trigger it), the frame size, and per-pool population sizes recomputed from frame at every stage the digest can anchor (stage 1 over the universe; later stages under the recorded parents). The report says where the frame drifted, not merely that it did.

When frame is itself a tbl_sample (that is, the design is being prepared as phase 2 of a two-phase sample), validate_frame() also pre-flights the two-phase export requirements: the design and the phase-1 sample must share unit identifiers declared with cluster_by(), and those identifiers must uniquely identify the phase-1 rows. Problems are reported as warnings rather than errors, because selection and weighting work without linkage; only as_svydesign() needs it.

Examples

# Create a design requiring region stratification and PPS by household count
design <- sampling_design() |>
  stratify_by(region) |>
  cluster_by(ea_id) |>
  draw(n = 10, method = "pps_brewer", mos = households)

# Validate against bfa_eas (should pass)
validate_frame(design, bfa_eas)

# Create a frame missing required variables (will fail)
bad_frame <- data.frame(id = 1:100, value = rnorm(100))
try(validate_frame(design, bad_frame))
#> Error : Frame validation failed:
#> ✖ Stage 1: missing stratification variable: "region"
#> ✖ Stage 1: missing cluster variable: "ea_id"
#> ✖ Stage 1: missing MOS variable: `households`

# Validate only specific stages of a multi-stage design
zwe_frame <- zwe_eas |>
  dplyr::mutate(district_hh = sum(households), .by = district)

multi_design <- sampling_design() |>
  add_stage(label = "Districts") |>
    cluster_by(district) |>
    draw(n = 20, method = "pps_brewer", mos = district_hh) |>
  add_stage(label = "EAs") |>
    draw(n = 10)

# Validate stage 1 only
validate_frame(multi_design, zwe_frame, stage = 1)

# Designs restored from a file also check the stored frame fingerprint
path <- tempfile(fileext = ".json")
write_design(design, path, frame = bfa_eas)
restored <- read_design(path)

# Same frame, no message
validate_frame(restored, bfa_eas)

# A modified frame passes validation with an informational message
validate_frame(restored, bfa_eas[-1, ])
#> Frame differs from the one recorded when the design was saved:
#> • 44569 rows instead of the 44570 recorded
#> ℹ This is informational. The design remains executable on any frame that passes
#>   the variable checks.
unlink(path)