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/duration, enrollment plan, dropout mechanism and seeding are specified in this function. Note that many of these parameters can be altered adaptively during a trial.

Note that it is users' responsibility to assure that the units of dropout time, trial duration, and readout of non-tte endpoints are consistent.

Usage

trial(
  name,
  n_patients,
  duration,
  description = name,
  seed = NULL,
  enroller = StaggeredRecruiter,
  dropout = NULL,
  stratification_factors = NULL,
  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.
duration: Numeric. Trial duration. 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.
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.

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, duration = 100,
  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  
#>  ⚕⚕   Planned Duration:  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  
#>  ⚕⚕   Planned Duration:  100  
#>  ⚕⚕            Regimen:  not set  
#>  ⚕⚕        Random Seed:  31415926