simulate_multilevel: Simulate a two-level Gaussian model

In simulab: Simulates a Wide Variety of Data Shapes, Sizes and Distributions

Simulate a two-level Gaussian model

Description

Draws a random intercept (and optionally a random slope) per cluster, draws the predictors independently for every unit, and forms the outcome as the fixed part plus the cluster random effects plus normal residual noise.

Usage

simulate_multilevel(
  clusters,
  cluster_size,
  intercept = 0,
  slopes = numeric(0L),
  predictor_means = 0,
  predictor_sds = 1,
  random_intercept_sd = 1,
  random_slope_sd = 0,
  random_effect_correlation = 0,
  residual_sd = 1,
  seed = NULL,
  batch = NULL
)

Arguments

clusters	Number of clusters. A single whole number of at least 2.
cluster_size	Units per cluster: a single whole number recycled across clusters, or one whole number per cluster, so clusters may be unbalanced.
intercept	Fixed intercept. A single number, defaulting to 0.
slopes	Named fixed-effect slopes; the names become the predictor columns of the returned data. Defaults to numeric(0), an intercept-only model with no predictor columns.
predictor_means, predictor_sds	Mean and standard deviation of each predictor, a scalar recycled across predictors (the defaults, 0 and 1) or one value per entry of slopes. Predictors are drawn independently at the unit level, not at the cluster level, so they carry no between-cluster variance by construction.
random_intercept_sd	Random-intercept standard deviation. A single non-negative number, defaulting to 1.
random_slope_sd	Random-slope standard deviation for the first predictor only; the remaining predictors have fixed slopes. A single non-negative number, defaulting to 0 (no random slope).
random_effect_correlation	Correlation between random intercept and slope. A single number in ⁠[-1, 1]⁠, defaulting to 0.
residual_sd	Residual standard deviation. A single positive number, defaulting to 1.
seed	Optional random seed.
batch	Optional single positive whole number. When given, the simulator runs batch times and returns a plain list of batch results, each exactly what the same call without batch returns. With a seed, every dataset gets its own seed drawn from seed, so the whole batch is reproducible; without one the datasets are consecutive draws from the session's random-number stream. The default NULL returns a single result.

Value

A simulab_sim base data.frame with one row per unit (sum(cluster_size) rows) and columns id, cluster, one column per name of slopes, and outcome. Components: fixed_effects (one row per fixed term, columns term and coefficient), variance_components (one row for each of random_intercept, random_slope and residual, columns component and variance – the squared standard deviations supplied as arguments), and random_effects (one row per cluster, columns cluster, random_intercept and random_slope; the random_slope column is present but zero when random_slope_sd = 0).

Examples

# `slopes` must be named; the names become the predictor columns.
result <- simulate_multilevel(
  clusters = 30,
  cluster_size = 10,
  intercept = 1,
  slopes = c(x1 = 0.5),
  random_intercept_sd = 0.8,
  seed = 1
)
head(result)
as.data.frame(result, what = "fixed_effects")
as.data.frame(result, what = "variance_components")

simulab documentation built on Oct. 15, 2026, 5:08 p.m.