Create a Cartesian grid of multisite design cells for scenario sweeps

Expand vectors of multisitedgp_design arguments into a tibble of distinct design cells — one row per Cartesian-product combination. Each row gets a locked multisitedgp_design object and, optionally, a deterministic seed for reproducible parallel simulation. Pass the result to scenario_audit for a top-of-funnel feasibility sweep, or to a custom worker pipeline for the full simulation.

Usage

design_grid(..., base_design = NULL, seed_root = NULL, seed_stream = TRUE)

Arguments

...

Named vectors or lists of flat multisitedgp_design arguments to expand as a Cartesian product. Each name must be a valid constructor argument; unknown names trigger an informative error.

base_design

Optional multisitedgp_design object used as the base for every row before applying row-specific overrides. Default NULL.

seed_root

Optional integer root seed. Required when seed_stream = TRUE. Pick a 9-digit integer; the package derives one seed per row from this root.

seed_stream

Logical. Allocate one deterministic seed per grid row. Default TRUE. Set to FALSE only when you intend to manage seeds externally.

Value

A tibble with class multisitedgp_design_grid, one row per distinct design cell. A design list-column carries the multisitedgp_design object for that row; a seed integer column appears when seed_stream = TRUE. Override columns appear as named columns for easy joining / filtering.

Details

Replication vs sweep. Replication is intentionally NOT represented in design_grid() — use scenario_audit(M = ...) for per-cell replication. The grid represents the unique design cells; replication is a separate axis.

base_design reuse pattern. Pass a multisitedgp_design object as base_design to use it as the starting point for every row; the ... overrides are applied via update_multisitedgp_design on top of the base. Useful when sweeping a single dimension (e.g., sigma_tau) while holding all other parameters constant.

Seed allocation. When seed_stream = TRUE (default), the package allocates one deterministic 9-digit integer seed per row from seed_root via the local-seed-stream policy. Re-running with the same seed_root produces bit-identical results across runs and across machines, and parallel workers get non-overlapping RNG streams.

For a worked scenario-grid example see the Case study — multisite trial vignette.

References

Lee, J., Che, J., Rabe-Hesketh, S., Feller, A., & Miratrix, L. (2025). Improving the estimation of site-specific effects and their distribution in multisite trials. Journal of Educational and Behavioral Statistics, 50(5), 731–764. doi:10.3102/10769986241254286 .

See also

multisitedgp_design for constructing per-row designs; update_multisitedgp_design for the override mechanism used when base_design is supplied; scenario_audit for the top-of-funnel grid feasibility sweep; the A6 Case study — multisite trial vignette.

Other family-design: as_tibble.multisitedgp_data(), is_multisitedgp_data(), is_multisitedgp_design(), multisitedgp_design(), print.multisitedgp_data(), summary.multisitedgp_data(), update_multisitedgp_design(), validate_multisitedgp_design()

Examples

# Two J values × two sigma_tau values = 4 design cells.
grid <- design_grid(J = c(10L, 12L), sigma_tau = c(0.10, 0.20),
                    seed_root = 1L)
nrow(grid)
#> [1] 4

# Sweep heterogeneity holding everything else at the modest preset.
base <- preset_education_modest()
het_sweep <- design_grid(sigma_tau = c(0.05, 0.20, 0.30),
                         base_design = base, seed_root = 12345L)