simulate_study: Simulate a declaratively specified study

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

Simulate a declaratively specified study

Description

Simulate a declaratively specified study

Usage

simulate_study(
  n,
  specification,
  id = "id",
  seed = NULL,
  envir = parent.frame(),
  batch = NULL
)

Arguments

n	Number of observational units.
specification	A tidy definition table created with define_variables(), in either the distribution-call form or the formula/variance column form.
id	Name of the identifier column.
seed	Optional random seed. The caller's random-number state is restored on exit.
envir	Environment used to resolve functions and external values named by a formula/variance specification. It is not consulted by the distribution-call form, whose parameters must be expressions over variables defined earlier in the same specification.
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 n rows: the identifier column followed by one column per variable. Use as.data.frame(x, what = "definitions") for the generating definitions.

Examples

# `formula` is the mean or linear predictor and may refer to variables
# defined earlier. `variance` is a variance, not a standard deviation, so
# age has sd 10 and outcome has residual sd 2.
simulate_study(
  n = 20,
  specification = define_variables(
    define_variable("age", formula = 40, variance = 100, distribution = "normal"),
    define_variable("treated", formula = 0.5, distribution = "binary"),
    define_variable("outcome", formula = "10 + 2 * treated", variance = 4,
                    distribution = "normal")
  ),
  seed = 1
)

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