Package {simtte}

simtte: Simulate Bespoke Time-to-Event Models Using ODEs

Description

Simulates time-to-event (survival) datasets for clinical trial design and analysis using ordinary differential equation (ODE) models solved via the 'mrgsolve' backend. Built-in Weibull and flexible M-spline baseline hazard models are provided out of the box, and fully bespoke hazard models can be implemented as custom 'mrgsolve' ODE systems. Event times are generated by inverse transform sampling from the resulting cumulative hazard functions. See Bender et al. (2005) doi:10.1002/sim.2059 for the inverse transform sampling methodology and Royston and Parmar (2002) doi:10.1002/sim.1203 for flexible parametric survival models.

Author(s)

Maintainer: Carlos Traynor carlos.traynor.qcp@gmail.com

Authors:

• Carlos Traynor carlos.traynor.qcp@gmail.com

See Also

Useful links:

• https://github.com/csetraynor/simtte

• Report bugs at https://github.com/csetraynor/simtte/issues

Pipe operator

Description

See magrittr::%>% for details.

Value

The result of applying the right-hand side function to the left-hand side object. See %>% for details.

Explore Prognostic Index and Quantile Survival Times

Description

Calculates the difference in survival probability at a given quantile time across a range of prognostic index values. Useful for understanding how different log hazard ratios affect survival outcomes.

Usage

explore_pi_tq_surv(q = 0.5, pi, mu, shape, type, times, basehaz, end_time, ...)

Arguments

Value

A data frame including columns lp, p11, survdiff_tq, and model parameters.

Examples

# Small fast example
data_sim <- explore_pi_tq_surv(
  pi = seq(-1, 1, by = 0.5),
  mu = -1,
  shape = 1.1,
  end_time = 10,
  type = "weibull"
)
head(data_sim)

# Larger range example
data_sim2 <- explore_pi_tq_surv(
  pi = seq(-3, 3, by = 0.1),
  mu = -1,
  shape = 1.1,
  end_time = 200,
  type = "weibull"
)
plot(survdiff_tq ~ lp, data = data_sim2)

Simulated Data for M-Splines Model Demonstration

Description

A list containing parameters for an M-spline survival model, suitable for use with sim_tte.

Usage

ms_data

Format

A list with 4 elements:

mu

Numeric scalar. Intercept parameter.

basis

Numeric matrix. M-spline basis matrix with rows corresponding to time points and columns to basis functions.

coefs

Numeric vector. Coefficients for each basis function.

time

Numeric vector. Time points corresponding to the rows of the basis matrix.

Source

Simulated example data.

Simulate Time-to-Event Data

Description

Main function of simtte. Simulates a time-to-event dataset (survival dataset) using either a Weibull parametric model or an M-spline flexible baseline hazard model. Event times are generated via inverse transform sampling from the cumulative hazard function computed by mrgsolve.

Usage

sim_tte(
  pi,
  log_pi = TRUE,
  mu = -3,
  coefs = 0,
  basis = NULL,
  time = 100,
  end_time,
  type = "weibull",
  ...
)

Arguments

Value

A data frame with columns:

sim_time

Simulated event or censoring time.

sim_status

Event indicator (1 = event, 0 = censored).

ID

Subject identifier.

lp

Log prognostic index (linear predictor).

References

Bender R, Augustin T, Blettner M (2005). Generating survival times to simulate Cox proportional hazards models. Statistics in Medicine, 24(11), 1713–1723. doi:10.1002/sim.2059

Royston P, Parmar MKB (2002). Flexible parametric proportional-hazards and proportional-odds models for censored survival data, with application to prognostic modelling and estimation of treatment effects. Statistics in Medicine, 21(15), 2175–2197. doi:10.1002/sim.1203

Examples

# Fast Weibull example with a small dataset
set.seed(1)
lp <- matrix(rnorm(5, 0, 0.5), nrow = 5)
result <- sim_tte(
  pi = lp, mu = -1, coefs = 1.1,
  time = seq(0.1, 10, by = 0.5),
  type = "weibull", end_time = 10
)
head(result)

# Larger examples using bundled ms_data
data("ms_data")
mu <- ms_data$mu
basis <- ms_data$basis
coefs <- ms_data$coefs
time <- ms_data$time
lp <- matrix(runif(nrow(basis)), nrow = nrow(basis))
wei_sim <- sim_tte(pi = lp, mu = -1, coefs = 1.1,
  time = time, type = "weibull", end_time = 100)
ms_sim <- sim_tte(pi = lp, mu = mu, basis = basis,
  coefs = coefs, time = time, type = "ms")

Simulate Time-to-Event Data from a Custom mrgsolve Output

Description

Applies inverse transform sampling to a data frame produced by an mrgsolve simulation that contains a survival probability column. This function is useful when you have a custom time-to-event model implemented in mrgsolve and want to generate event times.

Usage

sim_tte_df(
  dat,
  surv_var = "p11",
  id_var = "ID",
  time_var = "time",
  xdata = NULL
)

Arguments

Value

A data frame with columns:

sim_time

Simulated event or censoring time.

sim_status

Event indicator (1 = event, 0 = censored).

ID

Subject identifier.

Plus any additional columns from xdata.

Examples

# Create a mock survival probability data frame (no mrgsolve required)
mock_dat <- data.frame(
  ID = rep(1:3, each = 50),
  time = rep(seq(0.1, 10, length.out = 50), 3),
  p11 = rep(exp(-0.3 * seq(0.1, 10, length.out = 50)), 3)
)
result <- sim_tte_df(mock_dat)
head(result)

# Custom column names
mock_dat2 <- data.frame(
  subj = rep(101:103, each = 50),
  tgrid = rep(seq(0.1, 10, length.out = 50), 3),
  surv = rep(exp(-0.3 * seq(0.1, 10, length.out = 50)), 3)
)
result2 <- sim_tte_df(mock_dat2, surv_var = "surv",
  id_var = "subj", time_var = "tgrid")
head(result2)