Construct an immutable multisite simulation design

Build a frozen multisitedgp_design configuration object that captures every choice for a multisite-trial simulation: site count, latent-effect distribution, sample-size or precision margin, optional precision dependence, observation model, and seed. Pass the result to sim_multisite or sim_meta for a single simulation, or to design_grid for a scenario sweep.

Usage

multisitedgp_design(
  J = 50L,
  paradigm = c("site_size", "direct"),
  true_dist = c("Gaussian", "StudentT", "SkewN", "ALD", "Mixture", "PointMassSlab",
    "User", "DPM"),
  tau = 0,
  sigma_tau = 0.2,
  variance = 1,
  theta_G = list(),
  formula = NULL,
  beta = NULL,
  data = NULL,
  g_fn = NULL,
  g_returns = c("standardized", "raw"),
  nj_mean = 50,
  cv = 0.5,
  nj_min = 5L,
  p = 0.5,
  R2 = 0,
  var_outcome = 1,
  engine = c("A2_modern", "A1_legacy"),
  I = NULL,
  R = 1,
  shuffle = TRUE,
  se_fn = NULL,
  se_args = list(),
  dependence = c("none", "rank", "copula", "hybrid"),
  rank_corr = 0,
  pearson_corr = 0,
  dependence_fn = NULL,
  hybrid_init = c("copula", "rank"),
  hybrid_polish = c("hill_climb", "none"),
  max_iter = 20000L,
  tol = 0.02,
  target_marginal_rho = NULL,
  obs_fn = NULL,
  framing = c("superpopulation", "finite"),
  seed = NULL,
  record_permutation = NULL
)

# S3 method for class 'multisitedgp_design'
print(x, ...)

# S3 method for class 'multisitedgp_design'
format(x, ...)

Arguments

J: Integer (\(\ge 10\)). Number of sites. Default 50L.
paradigm: Character. Margin / SE paradigm — "site_size" (default) or "direct".
true_dist: Character. Latent-effect distribution — one of "Gaussian", "StudentT", "SkewN", "ALD", "Mixture", "PointMassSlab", "User", "DPM". Default "Gaussian".
tau: Numeric. Grand mean of the site-effect distribution. Default 0.
sigma_tau: Numeric (\(\ge 0\)). Between-site SD on the response scale. Default 0.20.
variance: Numeric. Legacy Gaussian variance argument. Default 1. Constrained to 1 by the unit-variance Layer 1 convention.
theta_G: Named list of distribution-specific parameters. See gen_effects for keys per shape.
formula, beta, data: Optional covariate specification. formula is a one-sided formula; beta is the matching coefficient vector; data is a data.frame with the predictors.
g_fn: Optional user-supplied effect-generator callback for true_dist = "User" or the bridged "DPM" route.
g_returns: Character. "standardized" (Convention A, default) or "raw" (Convention B). See gen_effects_user.
nj_mean, cv, nj_min, p, R2, var_outcome: Site-size margin parameters (Paradigm A only). See gen_site_sizes.
engine: Character. Site-size engine — "A2_modern" (default, recommended) or "A1_legacy" (JEBS bit-parity reproduction only).
I, R, shuffle, se_fn, se_args: Direct-precision parameters (Paradigm B only). See gen_se_direct.
dependence: Character. Layer 3 dependence injection method — "none" (default), "rank", "copula", or "hybrid".
rank_corr, pearson_corr: Numeric in [-1, 1]. Dependence targets. rank_corr is used for "rank" and "hybrid"; pearson_corr is used for "copula".
dependence_fn: Optional custom dependence callback. See align_rank_corr for the contract.
hybrid_init, hybrid_polish: Hybrid-aligner initialization and polishing controls. See align_hybrid_corr.
max_iter, tol: Iteration budget and convergence tolerance for the rank / hybrid hill-climb. Defaults 20000L and 0.02.
target_marginal_rho: Reserved for future marginal-correlation target; not implemented in the current release.
obs_fn: Optional Layer 4 observation callback. See gen_observations.
framing: Character. Sampling-frame interpretation — "superpopulation" (default) or "finite".
seed: Optional integer. Single seed for the full pipeline; if non-NULL, the wrapper wraps the call in with_seed for bit-identical replays.
record_permutation: Logical. Retain Layer 3 permutation metadata for inspection. Default depends on dependence.
x: A multisitedgp_design object — used by print and format methods.
...: Additional arguments for print / format methods.

Value

A list with class c("multisitedgp_design", "list") carrying every locked configuration choice. Pass to sim_multisite or sim_meta.

Details

When to construct a design vs. pass flat args. For a single simulation call, you can pass flat arguments directly to sim_multisite (or sim_meta) and skip multisitedgp_design(). Construct a design once when you want to reuse it across multiple simulation calls, sweep a design_grid, or audit a fixed configuration with validate_multisitedgp_design.

Site-size-driven (Paradigm A) vs direct-precision (Paradigm B). paradigm = "site_size" (default) uses the nj_mean, cv, nj_min, p, R2, var_outcome, engine arguments to derive sampling variance from site sizes (Layer 2 via gen_site_sizes). paradigm = "direct" uses I, R, shuffle, se_fn, se_args to specify the precision distribution directly (Layer 2 via gen_se_direct). Mixing arguments from the two paradigms triggers a coherence error.

For the formal specification of every slot and the design-class contract, see the The two-stage DGP — formal specification vignette and Appendix A.

Methods (by generic)

print(multisitedgp_design): Print a compact multi-line design summary.
format(multisitedgp_design): Format a compact multi-line design summary.

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 .

Examples

# Minimal site-size-driven design.
design <- multisitedgp_design(J = 20L, sigma_tau = 0.20, seed = 1L)
is_multisitedgp_design(design)
#> [1] TRUE

# Direct-precision design for meta-analysis.
meta_design <- multisitedgp_design(
  paradigm = "direct", J = 30L, I = 0.30, R = 2,
  sigma_tau = 0.20, seed = 1L
)