Simulate longitudinal outcome measurements — simulate_longitudinal

This function generates longitudinal (repeated measures) outcomes for patients at given visit times. It can incorporate treatment effects over time and between-patient variability, including a random site or country effect to simulate multi-level data.

Usage

simulate_longitudinal_outcomes(
  visits,
  patients,
  baseline_mean = 0,
  baseline_sd = 1,
  control_slope = 0,
  treatment_slope = 0,
  error_sd = 1,
  cluster_var = NULL,
  cluster_effect_sd = 0
)

Arguments

visits: A data frame of scheduled visits (e.g., output of simulate_visits) with at least ID and Time columns for each patient visit.
patients: The patient data frame (as from simulate_patients and subsequent steps) that includes patient-level information such as treatment group and possibly site or country.
baseline_mean: Numeric, the overall mean outcome at baseline for control patients (default = 0).
baseline_sd: Numeric, standard deviation for baseline outcome between patients (default = 1).
control_slope: Numeric, the rate of change in outcome over time for the control group (per unit time, default = 0 for no change).
treatment_slope: Numeric, additional rate of change in outcome over time for the treatment group relative to control (per unit time, default = 0). For example, a negative value indicates the treatment group’s outcome improves (decreases) over time relative to control.
error_sd: Numeric, standard deviation of measurement error or intra-patient variability at each visit (default = 1).
cluster_var: Character, name of a clustering variable in patients (e.g., "Site" or "Country") for multi-level outcomes. If provided, random intercepts are simulated for each cluster (default = NULL).
cluster_effect_sd: Numeric, standard deviation of the cluster-level random intercept (default = 0, meaning no cluster effect).

Value

A data frame with longitudinal measurements for each patient visit. Columns include:

ID: Patient ID.
Time: Visit time.
Arm: Treatment group for that patient (from patients$Arm).
Site (or Country): If those columns exist in patients, they are included here for reference.
Outcome: Simulated outcome value at that visit time.

Details

The outcome for patient i at time t is simulated as: $$Outcome_{i}(t) = B_{i0} + (\beta_c + \beta_t * I(\text{treatment}_i)) * t + \epsilon_{i}(t),$$ where $B_{i0}$ is the baseline outcome for patient i (including any cluster effect), $\beta_c$ is the control group slope, $\beta_t$ is the additional treatment effect on slope (so total slope for treatment = $\beta_c + \beta_t$), and $\epsilon_{i}(t)$ is random measurement error with SD = error_sd. If cluster_var is specified, each cluster gets a random intercept added to $B_{i0}$ (with SD = cluster_effect_sd), which introduces between-cluster variability (an original feature demonstrating multi-level data).

Baseline outcomes (t=0) are generated from N(baseline_mean + cluster\_offset, baseline_sd^2) for each patient. Set baseline_sd = 0 for identical baseline values within a cluster.

Examples

df <- simulate_patients(2, countries = 1, sites_per_country = 2)
df$Arm <- factor(c("Control","Treatment"), levels = c("Control","Treatment"))
# Generate visits for baseline and time=10 for both patients
visits <- simulate_visits(df, visit_times = c(0, 10))
# Simulate longitudinal outcome (no error for clarity, treatment improves outcome)
visit_data <- simulate_longitudinal_outcomes(visits, df, baseline_mean = 100, baseline_sd = 0,
                                  control_slope = 0, treatment_slope = -5, error_sd = 0,
                                  cluster_var = "Site", cluster_effect_sd = 0)
visit_data  # Patient 1 (Control) stays at 100; Patient 2 (Treatment) drops to 50 by time 10
#>   ID Time       Arm  Site  Country Outcome
#> 1  1    0   Control Site2 Country1     100
#> 2  1   10   Control Site2 Country1     100
#> 3  2    0 Treatment Site1 Country1     100
#> 4  2   10 Treatment Site1 Country1      50