Skip to contents

Run an ALSD Simulation

Source: R/simulation.R
run_alsd_simulation.Rd

This is the main function to run a single simulation of an adaptive survey. It compares a specified ALSD method against a Simple Random Sample (SRS) baseline.

Usage

run_alsd_simulation(
  population_df,
  strata_vars,
  outcome_var,
  method = "alsd_modelled",
  initial_sample_size = 500,
  wave_size = 250,
  total_budget = 1500,
  optimizer = c("adam", "bfgs"),
  objective = c("deff", "entropy"),
  enforce_target = FALSE,
  report_varw = FALSE,
  report_weighted = FALSE,
  verbose = TRUE
)

Arguments

population_df

The full population dataset.

strata_vars

Character vector of variable names for stratification.

outcome_var

The name of the binary outcome variable (string).

method

The ALSD method to use. Currently supports "alsd_modelled" and "alsd_simple".

initial_sample_size

The size of the first sample wave.

wave_size

The target size for subsequent sample waves.

total_budget

The total number of respondents to collect.

optimizer

Optimizer to use for the modelled method: one of "adam" (optimg::optimg with ADAM) or "bfgs" (stats::optim BFGS). Default is "adam". No silent fallback will occur.

objective

Objective to optimise when method = "alsd_modelled". One of "deff" (default; expected Kish design effect) or "entropy" (cross-entropy/KL between expected next-wave respondent shares and population shares). Both support the same budget penalty and analytic gradients.

enforce_target

Logical; if TRUE, after optimizing the logistic model for p_h, apply an intercept shift so that the expected number of respondents in the next wave exactly equals wave_size. Default FALSE (penalty-only).

report_varw

Logical; if TRUE, include var(w) alongside Kish D_eff in the per-wave summary (as varw = deff - 1 when weights are normalized to mean 1).

report_weighted

Logical; if TRUE, include a weighted estimate using post-stratification weights (y_estimate_weighted) and its error.

verbose

Logical; print per-wave progress and final termination reason. Default TRUE.

Value

A list containing:

  • summary: data frame of the simulation waves

  • final_sample: data frame with respondent IDs

  • termination_reason: character, why the loop ended

Examples

data(zimbabwe_minisample)

# Run a short simulation
results <- run_alsd_simulation(
  population_df = zimbabwe_minisample,
  strata_vars = c("gender", "region"),
  outcome_var = "fcs_insuff_flag",
  method = "alsd_simple",
  initial_sample_size = 100,
  wave_size = 50,
  total_budget = 200
)
#> 
#> --- Wave 1 ---
#> Respondents collected: 0/200
#> 
#> --- Wave 2 ---
#> Respondents collected: 87/200
#> 
#> --- Wave 3 ---
#> Respondents collected: 137/200
#> 
#> --- Wave 4 ---
#> Respondents collected: 187/200
#> Termination reason: Expended budget

print(results$summary)
#>   wave      method n_respondents y_estimate        error     deff varw
#> 1    1 alsd_simple            87  0.1379310 -0.077068966 1.208812   NA
#> 2    2 alsd_simple           137  0.1970803 -0.017919708 1.028400   NA
#> 3    3 alsd_simple           187  0.2032086 -0.011791444 1.016313   NA
#> 4    4 alsd_simple           220  0.2136364 -0.001363636 1.008779   NA
#>   y_estimate_weighted error_weighted
#> 1                  NA             NA
#> 2                  NA             NA
#> 3                  NA             NA
#> 4                  NA             NA