Define a New Stage in Multi-Stage Designs

stage() opens a new stage context in multi-stage sampling designs. It acts as a delimiter between stages, not a wrapper—each stage's specification follows stage() using the same verbs.

stage(.data, label = NULL)

Arguments

.data

A sampling_design object.

label

Optional character string labeling the stage (e.g., "Schools", "Classrooms", "Students"). Used for documentation and printing.

Value

A modified sampling_design object with a new stage context.

Details

Multi-Stage Design Structure

In multi-stage designs, sampling proceeds hierarchically:

1. Stage 1: Select primary sampling units (PSUs), e.g., schools

2. Stage 2: Within selected PSUs, select secondary units, e.g., classrooms

3. Stage 3+: Continue nesting as needed

Each stage can have its own:

• Stratification (stratify_by())

• Clustering (cluster_by())

• Selection method and sample size (draw())

Design Patterns

Pattern 1: Single-stage (no explicit stage()):

sampling_design() |>
  stratify_by(...) |>
  draw(...)

Pattern 2: Multi-stage (explicit stages):

sampling_design() |>
  stage(label = "Stage 1") |>
    cluster_by(...) |>
    draw(...) |>
  stage(label = "Stage 2") |>
    cluster_by(...) |>
    draw(...) |>
  stage(label = "Stage 3") |>
    draw(...)

Validation Rules

• Each stage must end with draw() before the next stage() or execute()

• Empty stages (stage followed immediately by stage) are not allowed

• The final stage doesn't need cluster_by() (samples individuals)

Execution

Multi-stage designs can be executed:

• All at once with a single frame (hierarchical data)

• All at once with multiple frames (one per stage)

• Stage by stage using stages = parameter in execute()

See execute() for details on execution patterns.

See also

sampling_design() for creating designs, draw() for completing stages, execute() for running multi-stage designs

Examples

if (FALSE) { # \dontrun{
# Two-stage design: schools then students
sampling_design() |>
  stage(label = "Schools") |>
    cluster_by(school_id) |>
    draw(n = 50, method = "pps_brewer", mos = enrollment) |>
  stage(label = "Students") |>
    draw(n = 20) |>
  execute(frame, seed = 42)

# Three-stage with stratification at stage 1
sampling_design() |>
  stage(label = "Districts") |>
    stratify_by(region) |>
    cluster_by(district_id) |>
    draw(n = 5, method = "pps_brewer", mos = population) |>
  stage(label = "Schools") |>
    cluster_by(school_id) |>
    draw(n = 4) |>
  stage(label = "Students") |>
    draw(n = 15) |>
  execute(frame, seed = 42)

# Gambia bednet survey pattern
sampling_design() |>
  stage(label = "Districts") |>
    stratify_by(region) |>
    cluster_by(district) |>
    draw(n = 5, method = "pps_brewer", mos = census_pop) |>
  stage(label = "Villages") |>
    stratify_by(phc_status) |>
    cluster_by(village) |>
    draw(n = 2, method = "pps_brewer", mos = census_pop) |>
  stage(label = "Compounds") |>
    draw(n = 6) |>
  execute(frame, seed = 42)
} # }