simulate_dynamics: Simulate lineage frequency dynamics

In lineagefreq: Lineage Frequency Dynamics from Genomic Surveillance Counts

Simulate lineage frequency dynamics

Description

Generates synthetic lineage frequency data under a multinomial sampling model with configurable growth advantages. Useful for model validation, power analysis, and teaching.

Usage

simulate_dynamics(
  n_lineages = 4L,
  n_timepoints = 20L,
  total_per_tp = 500L,
  advantages = NULL,
  reference_name = "ref",
  start_date = Sys.Date(),
  interval = 7L,
  overdispersion = NULL,
  seed = NULL
)

Arguments

n_lineages	Number of lineages including reference. Default 4.
n_timepoints	Number of time points. Default 20.
total_per_tp	Sequences per time point. A single integer (constant across time) or a vector of length n_timepoints (variable sampling effort). Default 500.
advantages	Named numeric vector of per-week multiplicative growth advantages for non-reference lineages. Length must equal n_lineages - 1. Values > 1 mean growing faster than reference, < 1 means declining. If NULL, random values in (0.8, 1.5).
reference_name	Name of the reference lineage. Default "ref".
start_date	Start date for the time series. Default today.
interval	Days between consecutive time points. Default 7 (weekly data).
overdispersion	If NULL (default), standard multinomial sampling. If a positive number, Dirichlet-Multinomial sampling with concentration = 1 / overdispersion. Larger values = more overdispersion.
seed	Random seed for reproducibility.

Value

An lfq_data object with an additional true_freq column containing the true (pre-sampling) frequencies.

Examples

# JN.1 grows 1.3x per week, KP.3 declines at 0.9x
sim <- simulate_dynamics(
  n_lineages = 3,
  advantages = c("JN.1" = 1.3, "KP.3" = 0.9),
  n_timepoints = 15,
  seed = 42
)
sim

lineagefreq documentation built on April 3, 2026, 9:09 a.m.