Package 'simtte'

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

q	Numeric scalar. Survival quantile of interest (default 0.5, i.e. median survival).
pi	Numeric vector. Prognostic index values to evaluate.
mu	Numeric scalar. Intercept parameter.
shape	Numeric scalar or vector. Shape parameter(s) for the Weibull model.
type	Character string. Model type: "weibull" or "ms".
times	Numeric vector. Time points (M-spline models).
basehaz	Numeric matrix. Baseline hazard (M-spline models).
end_time	Numeric scalar. Administrative censoring time.
...	Additional arguments passed to mrgsim.

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

pi	Numeric matrix or vector. Prognostic index (linear predictor) for each individual. Given a covariate matrix X and coefficient vector b, pi = X %*% b.
log_pi	Logical; is the prognostic index already on the log scale? Default TRUE.
mu	Numeric scalar. Intercept parameter of the model. Default -3.
coefs	Numeric vector. For M-spline models, the coefficients of each spline basis function. For Weibull models, the shape parameter (scalar).
basis	Numeric matrix. Basis matrix for M-spline models. Ignored for Weibull models. Default NULL.
time	Numeric vector. For M-spline models, the time points corresponding to rows of the basis matrix. For Weibull models, used only to determine end_time if not supplied. Default 100.
end_time	Numeric scalar. Administrative censoring time. Defaults to max(time).
type	Character string. Model type: "weibull" or "ms" (M-splines). Default "weibull".
...	Additional arguments passed to mrgsim.

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", xdata = NULL)

Arguments

dat	Data frame. Output from mrgsim containing at minimum columns for time, subject ID, and survival probability.
surv_var	Character string. Name of the column containing the survival probability (probability of remaining event-free). Default "p11".
id_var	Character string. Name of the subject ID column. Default "ID".
xdata	Optional data frame of additional covariates to merge into the output. Must contain a column matching id_var.

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)

---