augment_study: Add declaratively specified variables to existing data

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

Add declaratively specified variables to existing data

Description

A parameter or formula may refer to a column data already has as readily as to a variable defined earlier in the same specification. A variable that already exists is refused rather than overwritten.

Usage

augment_study(data, specification, seed = NULL, envir = parent.frame())

Arguments

data	A base data.frame.
specification	A tidy definition table created with define_variables(), in either the distribution-call form or the formula/variance column form.
seed	Optional random seed.
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 columns of data or variables defined earlier in the same specification.

Value

A simulab_sim base data.frame with one row per row of data, containing the original and new variables. Use as.data.frame(x, what = "definitions") for the generating definitions.

Conditions

simulab_existing_variable when the specification names a column data already has.

Examples

# Distribution calls, generated into data that is already there.
head(augment_study(
  data.frame(id = 1:100, treated = rep(0:1, each = 50)),
  specification = define_variables(
    outcome = normal(mean = 3 + 2 * treated, sd = 1),
    visits  = poisson(lambda = 4)
  ),
  seed = 3
))

base <- simulate_study(
  n = 100,
  specification = define_variables(
    define_variable("baseline", formula = "0", variance = "1", distribution = "normal")
  ),
  seed = 1
)

result <- augment_study(
  base,
  specification = define_variables(
    define_variable("outcome", formula = "2 * baseline", variance = "1",
                    distribution = "normal")
  ),
  seed = 2
)
head(result)

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