define_variables: Combine variable definitions into a specification

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

Combine variable definitions into a specification

Description

Combine variable definitions into a specification

Usage

define_variables(...)

Arguments

...

One of three forms. Distribution calls. age = normal(mean = 50, sd = 10) names the variable with the argument name and states its distribution as a call. Parameters may be given positionally or by name, in the order list_distributions() reports. A parameter may be any expression over variables defined earlier in the same call, so outcome = normal(mean = 10 + 0.2 * age, sd = 2) is a regression. Distribution names are never evaluated, so gamma(), beta() and t() do not reach the base functions of those names. Specification columns given as named vectors (variable, formula, variance, distribution, link). Objects created by define_variable() or repeat_variables(). The forms cannot be mixed in one call. In the column form, variable and formula are required. A column given as a single value is recycled across every variable. variance defaults to 0, distribution to "normal", and link to "identity".

Value

A simulab_spec base data.frame, shaped by the form it was given. Distribution calls give one row per distribution parameter, with columns variable, distribution, parameter and value. The column form and the constructor form give one row per variable, with columns variable, distribution, formula, variance and link. Both forms are accepted by simulate_study() and augment_study().

Examples

# Distribution calls. The variable name is the argument name.
define_variables(
  age     = normal(mean = 50, sd = 10),
  treated = binary(prob = 0.5),
  outcome = normal(mean = 10 + 0.2 * age + 2 * treated, sd = 2)
)

# Parameters may be positional, in the order list_distributions() reports.
define_variables(y = normal(5, 1), count = poisson(3))

# Specification columns. `formula` is the mean or linear predictor and may
# refer to variables defined earlier. `variance` is a variance, not a
# standard deviation.
define_variables(
  variable     = c("baseline", "treatment", "outcome"),
  formula      = c("0", "0.5", "0.4 * baseline + 0.8 * treatment"),
  variance     = c("1", "0", "1"),
  distribution = c("normal", "binary", "normal")
)

# A column given once is recycled, so a specification that shares one
# distribution stays short.
define_variables(
  variable = c("x1", "x2", "x3"),
  formula  = "0",
  variance = "1"
)

# Definitions built one at a time are still accepted.
define_variables(
  define_variable("age", formula = 40, variance = 100, distribution = "normal"),
  define_variable("treated", formula = 0.5, distribution = "binary")
)

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