simulate_longitudinal: Simulate a multivariate longitudinal VAR process

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

Simulate a multivariate longitudinal VAR process

Description

Draws a person mean for each unit from between_covariance around grand_means, then runs a first-order vector autoregression on the deviations from that person mean: ⁠y_t = mu + intercept + transition %*% (y_{t-1} - mu) + e_t⁠, with e_t drawn from innovation_covariance. The first burn_in occasions are discarded so the retained occasions are near stationarity.

Usage

simulate_longitudinal(
  n,
  occasions,
  transition,
  intercept = 0,
  innovation_covariance = NULL,
  initial_covariance = NULL,
  between_covariance = NULL,
  grand_means = 0,
  beeps_per_day = NULL,
  burn_in = 50L,
  seed = NULL,
  batch = NULL
)

Arguments

n	Number of units. A single positive whole number.
occasions	Number of occasions retained per unit. A single whole number of at least 2.
transition	Lag-one coefficients as a square matrix, or as a tidy data frame with columns from, to and coefficient (from supplies the matrix row and to the column). Entry ⁠[i, j]⁠ multiplies variable j at the previous occasion when forming variable i at the current occasion, so rows index the receiving variable and columns the predicting variable. The spectral radius must be below one.
intercept	Variable intercepts, a scalar recycled across variables (the default, 0) or one value per variable. The intercept is added to the deviation from the person mean at every occasion, so a non-zero intercept shifts the stationary mean to person_mean + solve(diag(p) - transition) %*% intercept and the person_means component is then no longer the realized process mean.
innovation_covariance	Innovation covariance matrix, or a tidy data frame with columns row, column and covariance. Must be symmetric and positive semidefinite. NULL (the default) uses the identity.
initial_covariance	Initial-state covariance matrix, or a tidy data frame with columns row, column and covariance. NULL (the default) reuses innovation_covariance.
between_covariance	Between-unit covariance of person means, or a tidy data frame with columns row, column and covariance. NULL (the default) is a zero matrix, giving every unit the same person mean, grand_means.
grand_means	Population means, a scalar recycled across variables (the default, 0) or one value per variable.
beeps_per_day	Optional number of occasions per day; occasions must be divisible by it. Adds day and beep columns to the returned data. Temporal carryover resets at each day boundary.
burn_in	Warm-up occasions generated and then discarded before output. A single non-negative whole number, defaulting to 50.
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 long-form simulab_sim base data.frame with one row per unit-occasion (n * occasions rows) and columns id, occasion and one per variable, plus day and beep when beeps_per_day is supplied. Components: wide (one row per unit, one ⁠<variable>.<occasion>⁠ column per measurement), transition, innovation_covariance and between_covariance (tidy matrix tables with columns row, column and coefficient or covariance), and person_means (one row per unit with columns id and one per variable).

Examples

# `transition` is the lag-one coefficient matrix of the VAR process.
result <- simulate_longitudinal(
  n = 20,
  occasions = 30,
  transition = matrix(c(0.5, 0.1, 0.0, 0.4), nrow = 2, byrow = TRUE),
  seed = 1
)
head(result)
components(result)

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