sim_clinical_data: Simulate Clinical Trial Multistate Data

In RFmstate: Random Forest-Based Multistate Survival Analysis

Simulate Clinical Trial Multistate Data

Description

Generates realistic clinical trial data with covariates and multistate event times for testing and demonstration. The structure must be an acyclic, non-recurrent graph with one common initial state.

Usage

sim_clinical_data(n = 500, structure = NULL, max_followup = 365, seed = NULL)

Arguments

n	Integer, number of patients to simulate.
structure	An mstate_structure object. Defaults to clinical_states().
max_followup	Numeric, maximum follow-up time (for generating censoring). Default 365.
seed	Optional integer for reproducibility.

Details

Cause-specific transition hazards follow Weibull distributions with covariate effects on the scale parameter. For the default clinical_states() structure, transition-specific parameters are calibrated to produce realistic clinical trial trajectories. For custom structures, sensible default parameters are used for all transitions.

Event waiting times remain at full numerical precision. External censoring is generated before each path and truncates it, so no event is retained after censoring or after entry into any absorbing state. Supplying the same seed, arguments, structure, and package version reproduces the returned data.

Value

A data frame in wide format with columns:

ID

Patient identifier (1 to n).

age

Continuous, simulated from Normal(60, 12).

sex

Binary 0/1.

BMI

Continuous, simulated from Normal(26, 5).

treatment

Binary 0/1 (balanced arms).

time_StateName

For each non-initial state in the structure, the time (days) of entry into that state, or NA if the state was not visited. Column names follow the pattern time_<StateName> (e.g., time_Death).

time_censored

Days until last follow-up (right censoring time), or NA if an absorbing state was reached.

Limitations

This helper supplies demonstration and test data, not the final manuscript simulation design. It uses four fixed baseline covariates and simple transition-specific Weibull cause-specific hazards. It does not generate left truncation, recurrent/cyclic histories, time-dependent covariates, interval-censored transitions, or ongoing-sojourn predictions.

Examples

dat <- sim_clinical_data(n = 100, seed = 123)
head(dat)
summary(dat)

RFmstate documentation built on Sept. 10, 2026, 1:09 a.m.