simulate_correlated: Simulate correlated Gaussian variables

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

Simulate correlated Gaussian variables

Description

Simulate correlated Gaussian variables

Usage

simulate_correlated(
  n,
  means,
  sds = 1,
  rho = 0,
  structure = c("independent", "exchangeable", "ar1", "custom"),
  correlation = NULL,
  variable_names = NULL,
  seed = NULL,
  batch = NULL
)

Arguments

n	Number of observations.
means	Variable means.
sds	Variable standard deviations.
rho	Correlation used when correlation is not supplied.
structure	Correlation structure: one of "independent", "exchangeable", "ar1", or "custom". If left unset it is chosen from the other arguments: "custom" when correlation is supplied, "exchangeable" when a non-zero rho is supplied, and "independent" otherwise. Passing "independent" together with a non-zero rho is a contradiction and raises a simulab_contradictory_structure error.
correlation	A custom correlation matrix or tidy table returned by correlation_structure().
variable_names	Optional variable names.
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 observation and columns id and one column per variable. Three tidy tables come from as.data.frame(): what = "parameters" has one row per variable with columns variable, mean and sd; what = "correlation" and what = "covariance" each have one row per matrix cell with columns row, column and correlation or covariance. The covariance is the correlation matrix scaled by sds on both sides, so sds are standard deviations rather than variances.

Examples

simulate_correlated(
  n = 100,
  means = c(0, 1, 2),
  sds = c(1, 2, 1),
  rho = 0.4,
  structure = "exchangeable",
  seed = 1
)

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