View source: R/simulation_functions.R
simulate_trials | R Documentation |
Function for simulating generalised two-arm time-to-event trial data for NPH trials with arbitrary event, censoring and recruitment distributions.
Event and censoring distributions are specified via Curve objects, with recruitment specified through an RCurve object.
As it uses same architecture and similar syntax to nph_traj(), analysis results ought to be directly comparable.
It is designed to complement nph_traj(), either as a stochastic alternative, or as a means to validate its outputs.
It can also be used to build more complex simulations by combining the outputs of multiple runs; e.g. multi-arm trials.
Data sets created by this function are formatted so they may be automatically recognised and analysed by analyse_sim().
simulate_trials(
active_ecurve,
control_ecurve,
active_dcurve = Blank(),
control_dcurve = Blank(),
rcurve,
assess = NULL,
fix_events = NULL,
iterations,
seed,
detailed_output = FALSE,
output_type = c("matrix", "list"),
Time = "Time",
Event = "Censored",
censoringOne = TRUE,
Trt = "Trt",
Iter = "Iter"
)
active_ecurve |
Event distribution for the active arm, specified as a Curve object |
control_ecurve |
Event distribution for the control arm, specified as a Curve object |
active_dcurve |
Dropout/censoring distribution for the active arm, specified as a Curve object. By default, Blank(), i.e. no dropout. |
control_dcurve |
Dropout/censoring distribution for the control arm, specified as a Curve object. By default, Blank(), i.e. no dropout. |
rcurve |
Recruitment distribution, specified as an 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) |
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" |
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.
"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)
James Bell
example_sim <- simulate_trials(active_ecurve=Weibull(250,0.8),control_ecurve=Weibull(100,1),
rcurve=LinearR(12,100,100), assess=20, iterations=5,seed=12345)
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.