simulate_trials_strata: Perform multi-strata simulations of time-to-event data using...

In gestate: Generalised Survival Trial Assessment Tool Environment

Perform multi-strata simulations of time-to-event data using arbitrary event, censoring and recruitment distributions.

Description

Function for simulating generalised two-arm multi-strata time-to-event trial data for NPH trials with arbitrary event, censoring and recruitment distributions.
Acts as a wrapper for simulate_trials.
Vector of strata proportions supplies number of strata. Event and censoring distributions specified via lists of Curve objects. If only one Curve supplied then assumed to be common to all strata. Recruitment specified via a single RCurve object.
As it uses same architecture and similar syntax to nph_traj(), results in simple cases may be directly comparable to e.g. use of MixExp() or MixWei() Curves.
Can be used to validate outputs from nph_traj().
Data sets from this are set up to be automatically analysed with the analyse_sim function (including stratified analysis if you provide it the name of stratum column).

Usage

simulate_trials_strata(
  stratum_probs,
  active_ecurve,
  control_ecurve,
  active_dcurve = Blank(),
  control_dcurve = Blank(),
  rcurve,
  assess = NULL,
  fix_events = NULL,
  stratum_name = "Stratum",
  iterations,
  seed,
  detailed_output = FALSE,
  output_type = c("matrix", "list"),
  Time = "Time",
  Event = "Censored",
  censoringOne = TRUE,
  Trt = "Trt",
  Iter = "Iter"
)

Arguments

stratum_probs	Vector of probabilities that patients belong to each stratum. Must sum to 1. Its length determines the number of strata.
active_ecurve	List of event distributions for the active arm, specified as a list of Curve objects. If single Curve is specified, will be used for all strata.
control_ecurve	List of event distributions for the control arm, specified as a list of Curve objects. If single Curve is specified, will be used for all strata.
active_dcurve	List of dropout/censoring distribution for the active arm, specified as a Curve object. If single Curve is specified, will be used for all strata. By default, Blank(), i.e. no dropout in any stratum.
control_dcurve	List of dropout/censoring distribution for the control arm, specified as a Curve object. If single Curve is specified, will be used for all strata. By default, Blank(), i.e. no dropout in any stratum.
rcurve	Recruitment distribution, specified as a single RCurve object.
assess	Positive number for the assessment time at which administrative censoring will be performed.
fix_events	Positive integer for the number of events to fix (if required), letting the assessment time vary. Alternatively, NULL for fixed time assessment with variable event numbers. Notes: Fixing event numbers overrides any specified assessment time and slows simulation considerably. Default = NULL (fixed analysis time)
stratum_name	Name of the column defining the stratum. Default="Stratum".
iterations	Number of simulations to perform. Depending on trial size, 10,000-20,000 is typically OK to analyse on 8GB RAM.
seed	Seed number to use. Numerical, although if "Rand" is specified, a system-time-derived number will be used.
detailed_output	Boolean to require full details of timings of competing processes. Full details required for any future adjustments to assessment time. Simplified option approximately halves RAM requirements. Default=FALSE (simplified).
output_type	"matrix" or "list" specifying the type of output required. "matrix" requests a single matrix with a column "iter" to denote the simulation, while "list" creates a list with one entry per simulation. Default="matrix".
Time	String specifying the name of the output time column. Default="Time"
Event	String specifying the name of the output censoring/event column. Default="Censored" (and by default it is a censoring column unless censoringOne=FALSE)
censoringOne	Boolean specifying whether censoring is denoted in the censoring/event column by a one (TRUE) or zero (FALSE). Default=TRUE (censorings denoted by 1, events by 0)
Trt	String specifying the name of the output treatment column. Default="Trt"
Iter	String specifying the name of the output iterations column. Default="Iter"

Value

Returns a table with one row per patient per simulation. Table contains the following columns:

• "Time" Simulated actually observed (patient) time of event or censoring: This is the main column of interest for analysis. Named by Time argument.

• "Event" Simulated event indicator denoting censorings/events as 1/0 if censoringOne=TRUE and 0/1 if censoringOne=FALSE. Named by Event argument.

• "Trt" Treatment group number - 1 is active, 2 is control. Named by Trt argument.

• "Iter" Simulation number. Named by Iter argument.

• "Stratum" Stratum number. Column name will be the value of the stratum_name argument.)

• "ETime" Simulated actual event (patient) time (may or may not be observed). Only produced when detailed_output=TRUE.

• "CTime" Simulated actual censoring/dropout (patient) time (may or may not be observed).Only produced when detailed_output=TRUE.

• "Rec_Time" Simulated (trial) time of recruitment. Only produced when detailed_output=TRUE.

• "Assess" Prespecified (trial) time of assessment. Only produced when detailed_output=TRUE.

• "Max_F" Prespecified maximum patient follow-up time. Only produced when detailed_output=TRUE.

• "RCTime" Simulated actual administrative censoring (patient) time (may or may not be observed. Only produced when detailed_output=TRUE.)

Author(s)

James Bell

Examples

example_strat_sim <- simulate_trials_strata(stratum_probs=c(0.5,0.5),
active_ecurve=c(Weibull(250,0.8),Weibull(100,1)), control_ecurve=Weibull(100,1),
rcurve=LinearR(12,100,100),assess=20,iterations=5,seed=12345)

gestate documentation built on April 26, 2023, 5:10 p.m.