Define a Trial — trial • TrialSimulator

Define a trial. This is a user-friendly wrapper for the class constructor Trial$new(). Users who are not familiar with the concept of classes may consider using this wrapper directly.

Trial's name, planned size, enrollment plan, dropout mechanism and seeding are specified in this function. Note that many of these parameters can be altered adaptively during a trial.

A trial has no pre-specified duration. It ends when its last milestone (usually the final analysis) is triggered, and the timing of a milestone is determined by its triggering condition, e.g., a calendar time, a number of events, or a number of enrolled patients. In particular, the duration of a trial with event-driven milestones is random and varies across simulated replicates. It can be read from the milestone time columns of $get_output().

Note that it is users' responsibility to assure that the units of dropout time, calendar time in milestones' triggering conditions, and readout of non-tte endpoints are consistent.

Usage

trial(
  name,
  n_patients,
  description = name,
  seed = NULL,
  enroller = StaggeredRecruiter,
  dropout = NULL,
  stratification_factors = NULL,
  global_data = list(),
  silent = FALSE,
  ...
)

Arguments

name: character. Name of trial. Usually, hmm..., useless.
n_patients: integer. Maximum (and initial) number of patients could be enrolled when planning the trial. It can be altered adaptively during a trial.
description: character. Optional for description of the trial. By default it is set to be trial's name. Usually useless.
seed: random seed. If NULL, seed is set for each simulated trial automatically and saved in output. It can be retrieved in the seed column in $get_output(). Setting it to be NULL is recommended. For debugging, set it to a specific integer.
enroller: enrollment-time generator. Must be StaggeredRecruiter (the default); any other value is rejected. Supply its accrual_rate via .... See ?TrialSimulator::StaggeredRecruiter. The argument is kept (rather than dropped) for backward compatibility: existing code that passes enroller = StaggeredRecruiter explicitly keeps working unchanged, and a named argument gives a clearer error than an "unused argument" failure if some other enroller is supplied.
dropout: a function returning a vector of dropout time for patients. It can be any random number generator with first argument n, the number of enrolled patients. Usually rexp if dropout rate is set at a single time point, or rweibull if dropout rates are set at two time points. See ?TrialSimulator::weibullDropout.
stratification_factors: character. Names of baseline characteristics to define stratums in stratified permuted block randomization. Stratification factors must be defined in endpoint() with readout = 0. As a natural assumption for randomized trial, TrialSimulator assumes that the baseline characteristics share the same distribution across arms, but endpoints can have same or different distributions given baseline characteristics. NULL by default, i.e., unstratified permuted block randomization is executed.
global_data: a list with named components, e.g., design parameters or a template object of a testing procedure, to be shared by all replicates of a simulation. It is read-only and can be accessed in action functions by calling trial$get_global_data(name). For temporary results passed between action functions within a single replicate, use trial$save_custom_data() instead. See vignette('actionFunctions', package = 'TrialSimulator').
silent: logical. TRUE to mute messages. However, warning message is still displayed. Usually set it to TRUE in formal simulation. Default: FALSE.
...: (optional) arguments of enroller and dropout.

Value

an object of R6 class Trials, representing a trial.

Examples

risk1 <- data.frame(
  end_time = c(1, 10, 26.0, 52.0),
  piecewise_risk = c(1, 1.01, 0.381, 0.150) * exp(-3.01)
)

pfs1 <- endpoint(name = 'pfs', type='tte',
          generator = PiecewiseConstantExponentialRNG,
          risk = risk1, endpoint_name = 'pfs')

orr1 <- endpoint(
  name = 'orr', type = 'non-tte',
  readout = c(orr=1), generator = rbinom,
  size = 1, prob = .4)

placebo <- arm(name = 'pbo')

placebo$add_endpoints(pfs1, orr1)

risk2 <- risk1
risk2$hazard_ratio <- .8

pfs2 <- endpoint(name = 'pfs', type='tte',
          generator = PiecewiseConstantExponentialRNG,
          risk = risk2, endpoint_name = 'pfs')

orr2 <- endpoint(
  name = 'orr', type = 'non-tte',
  generator = rbinom, readout = c(orr=3),
  size = 1, prob = .6)

active <- arm(name = 'ac')

active$add_endpoints(pfs2, orr2)

## Plan a trial, Trial-3415, of up to 100 patients.
## Enrollment accrues at a constant 10 patients per time unit.
trial <- trial(
  name = 'Trial-3415', n_patients = 100,
  seed = 31415926,
  enroller = StaggeredRecruiter,
  accrual_rate = data.frame(end_time = Inf, piecewise_rate = 10))

trial
#>  ⚕⚕         Trial Name:  Trial-3415  
#>  ⚕⚕        Description:  Trial-3415  
#>  ⚕⚕     Number of Arms:  0  
#>  ⚕⚕    Registered Arms:    
#>  ⚕⚕       Sample Ratio:    
#>  ⚕⚕ Number of Patients:  100  
#>  ⚕⚕            Regimen:  not set  
#>  ⚕⚕        Random Seed:  31415926  

trial$add_arms(sample_ratio = c(1, 2), placebo, active)
#> Arm(s) <pbo, ac> are added to the trial. 
#> Randomization is done for <1> potential patients. 
#> Data of <100> potential patients are generated for the trial with <2> arm(s) <pbo, ac>. 

## updated information after arms are registered
trial
#>  ⚕⚕         Trial Name:  Trial-3415  
#>  ⚕⚕        Description:  Trial-3415  
#>  ⚕⚕     Number of Arms:  2  
#>  ⚕⚕    Registered Arms:  pbo, ac  
#>  ⚕⚕       Sample Ratio:  1, 2  
#>  ⚕⚕ Number of Patients:  100  
#>  ⚕⚕            Regimen:  not set  
#>  ⚕⚕        Random Seed:  31415926