Package 'TrialSimulator'

Description

add one or more arms to a trial. This function can be used in two scenarios: (1) adding arms right after a trial is created (i.e., trial(...)). sample_ratio and arms added through ... must be of same length; (2) adding arms to an existing trial in action functions of milestones.

This is a user-friendly wrapper of the member function of trial, i.e., Trials$add_arms(), which is used in vignettes. Users who are not familiar with the concept of classes may consider using this wrapper directly.

The trial captures an independent deep copy of every arm it registers. Subsequent changes to the original arm object do not affect the trial, and adaptations within the trial (e.g., update_generator()) do not modify the original arm. Complete the configuration of an arm before registering it. The copy covers the arm and endpoint objects themselves; a mutable environment or R6 object captured by a generator function is shared by design of R closures and is not isolated.

Usage

add_arms(trial, sample_ratio, ...)

Arguments

Value

no return value, called for its side effect of updating trial.

Description

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

Usage

arm(name, ...)

Arguments

Value

an object of R6 class Arms, representing an arm of a trial.

Examples

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

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

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

placebo <- arm(name = 'pbo')

placebo$add_endpoints(pfs, orr)

## try to generate some data from the arm
## it is NOT a recommended way to use the package in simulation
head(placebo$get_endpoints()[[1]]$get_generator()(n = 1e3))

## get name of endpoints in the arm
## for illustration only, NOT recommended
placebo$get_endpoints()[[2]]$get_name()

## run it in console to get summary report
## It is the recommended way to view an arm
placebo

Description

Create a class of arm.

Public methods in this R6 class are used in developing this package. Thus, we have to export the whole R6 class which exposures all public methods. However, only the public methods in the list below are useful to end users.

• $add_endpoints() add one or multiple endpoints to the arm.

• $print() print a summary report of the arm based on example data of its endpoints.

In addition, $generate_data() and $get_endpoints() are for exploratory purpose only. They appear in examples and vignettes to help users understand how this class works, but they are not needed at all in formal simulation once users know how to use this package.

Internal machinery. The remaining public methods ($get_name(), $get_endpoints_name(), $has_endpoint() and $update_endpoint_generator()) are public only because they are invoked on an arm object by other components of the package (trials), which R6 cannot grant through private members. Users should not call them directly.

Value

an R6Class generator object; use arm() to create an arm.

Methods

Public methods

• Arms$new()

• Arms$add_endpoints()

• Arms$get_name()

• Arms$has_endpoint()

• Arms$get_endpoints()

• Arms$get_endpoints_name()

• Arms$update_endpoint_generator()

• Arms$generate_data()

• Arms$print()

• Arms$clone()

Method new()

initialize an arm

Usage

Arms$new(name, ...)

Arguments

Method add_endpoints()

add one or multiple endpoints to the arm.

Usage

Arms$add_endpoints(...)

Arguments

Examples

a <- arm(name = 'trt')
x <- endpoint(name = 'x', type = 'tte',
              generator = rexp) # median = log(2)/1 = 0.7
y <- endpoint(name = 'y', type = 'non-tte', readout = c(y = 0),
              generator = rnorm, sd = 1.4, mean = 0.7)

a$add_endpoints(y, x)

## run it in console to see the summary report
a

print(a) # use the print method

Method get_name()

INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.

return name of arm.

Usage

Arms$get_name()

Method has_endpoint()

INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.

check if the arm has any endpoint. Return TRUE or FALSE.

Usage

Arms$has_endpoint()

Method get_endpoints()

return a list of endpoints in the arm.

Usage

Arms$get_endpoints()

Method get_endpoints_name()

INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.

return name of endpoints registered to the arm.

Usage

Arms$get_endpoints_name()

Method update_endpoint_generator()

INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.

update generator of an endpoint object

Usage

Arms$update_endpoint_generator(endpoint_name, generator, ...)

Arguments

Method generate_data()

generate arm data.

Usage

Arms$generate_data(n_patients_in_arm)

Arguments

Method print()

print an arm.

Usage

Arms$print(categorical_vars = NULL)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

Arms$clone(deep = FALSE)

Arguments

Examples

# Instead of using Arms$new(), please use arm(), a user-friendly
# wrapper. See examples in ?arm


## ------------------------------------------------
## Method `Arms$add_endpoints`
## ------------------------------------------------


a <- arm(name = 'trt')
x <- endpoint(name = 'x', type = 'tte',
              generator = rexp) # median = log(2)/1 = 0.7
y <- endpoint(name = 'y', type = 'non-tte', readout = c(y = 0),
              generator = rnorm, sd = 1.4, mean = 0.7)

a$add_endpoints(y, x)

## run it in console to see the summary report
a

print(a) # use the print method

Description

Define a condition to trigger trial milestone by calendar time. The milestone will be triggered when a trial has been running for at least the specified duration since the first patient is enrolled. It can be used combined with conditions specified by enrollment and eventNumber.

Refer to the vignette to learn how to define milestones when performing simulation using TrialSimulator.

Usage

calendarTime(time)

Arguments

Value

an object of class 'Condition'

Examples

milestone(name = 'end of trial', when = calendarTime(time = 12))

Description

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

TrialSimulator uses a controller to coordinate a trial object and a listener object to run simulations, in which the trial object defines endpoints, arms, and other settings of a trial, while the listener object monitors trials to triggered pre-defined milestones and execute action functions. See vignettes of this package for more examples.

Usage

controller(trial, listener)

Arguments

Value

an object of R6 class Controllers, executing simulation of a trial.

Examples

# a minimum, meaningful, and executable example,
# where a randomized trial with two arms is simulated and analyzed.

control <- arm(name = 'control arm')
active <- arm(name = 'active arm')

pfs_in_control <- endpoint(name = 'PFS', type = 'tte',
                           generator = rexp, rate = log(2) / 5)
control$add_endpoints(pfs_in_control)

pfs_in_active <- endpoint(name = 'PFS', type = 'tte',
                          generator = rexp, rate = log(2) / 6)
active$add_endpoints(pfs_in_active)

accrual_rate <- data.frame(end_time = c(10, Inf),
                           piecewise_rate = c(30, 50))
trial <- trial(name = 'trial',
               n_patients = 1000,
               enroller = StaggeredRecruiter,
               accrual_rate = accrual_rate,
               dropout = rweibull, shape = 2, scale = 38)

trial$add_arms(sample_ratio = c(1, 1), control, active)

action_at_final <- function(trial){
  locked_data <- trial$get_locked_data('final analysis')
  fitLogrank(Surv(PFS, PFS_event) ~ arm, placebo = 'control arm',
             data = locked_data, alternative = 'less')
  invisible(NULL)
}

final <- milestone(name = 'final analysis',
                   action = action_at_final,
                   when = calendarTime(time = 40))

listener <- listener()
listener$add_milestones(final)

controller <- controller(trial, listener)
controller$run(n = 1)

Description

Create a class of controller to run a trial.

Public methods in this R6 class are used in developing this package. Thus, we have to export the whole R6 class which exposures all public methods. However, only the public methods in the list below are useful to end users.

• $run() run trial simulation, sequentially or in parallel. It cannot be called twice on a controller unless $reset() is called in between.

• $get_output() return a data frame of all outputs saved during simulation.

• $reset() reset the trial and listener registered to the controller before starting a new simulation with $run().

Value

an R6Class generator object; use controller() to create a controller.

Methods

Public methods

• Controllers$new()

• Controllers$reset()

• Controllers$get_output()

• Controllers$run()

• Controllers$clone()

Method new()

initialize a controller of the trial

Usage

Controllers$new(trial, listener)

Arguments

Method reset()

reset the trial and listener registered to the controller so that a new simulation can be started with controller$run(). The trial and the milestones are restored to their as-designed version.

Usage

Controllers$reset()

Method get_output()

return a data frame of all current outputs saved by calling save().

Usage

Controllers$get_output(cols = NULL, simplify = TRUE, tidy = FALSE)

Arguments

Method run()

run trial simulation. It cannot be called again on the same controller unless reset() is called first.

Usage

Controllers$run(
  n = 1,
  n_workers = 1,
  plot_event = TRUE,
  silent = FALSE,
  tidy = FALSE
)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

Controllers$clone(deep = FALSE)

Arguments

Examples

##

Description

Generate correlated PFS and OS endpoints using the Gumbel copula. Marginally, both PFS and OS follow exponential distributions. This function can be used as custom generator in the function endpoint().

Note that the Gumbel copula is applied to the survival functions of OS and time-to-progression (TTP). PFS is defined as min(TTP, OS), which also follows an exponential distribution.

For more information, refer to this vignette.

Usage

CorrelatedPfsAndOs2(
  n,
  median_pfs,
  median_os,
  kendall,
  pfs_name = "pfs",
  os_name = "os"
)

Arguments

Value

A data frame of n rows and four columns, including PFS, OS and their event indicators. The event indicators are all 1s. The column names are <pfs_name>, <pfs_name>_event, <os_name>, and <os_name>_event.

Examples

pfs_and_os <- endpoint(name = c('PFS', 'Os'),
                       type = c('tte', 'tte'),
                       generator = CorrelatedPfsAndOs2,
                       median_pfs = 5,
                       median_os = 11,
                       kendall = .6,
                       pfs_name = 'PFS',
                       os_name = 'Os')

pfs_and_os # run it in console to see summary report

## for validation purpose only
## not the recommended way to use TrialSimulator
dat <- pfs_and_os$test_generator(n = 1e4)
cor(dat[, 1:2], method = 'kendall') ## close to 0.6

Description

Generate correlated PFS and OS endpoints using the three-states model. This function can be used as custom generator in the function endpoint().

Usage

CorrelatedPfsAndOs3(n, h01, h02, h12, pfs_name = "pfs", os_name = "os")

Arguments

Value

A data frame of n rows and four columns, including PFS, OS and their event indicators. The event indicators are all 1s. The column names are <pfs_name>, <pfs_name>_event, <os_name>, and <os_name>_event.

Examples

## use as function (if you don't use TrialSimulator for simulation)
pfs_and_os_trt <- CorrelatedPfsAndOs3(1e4, 0.06, 0.30, 0.30, 'PFS', 'OS')
pfs_and_os_pbo <- CorrelatedPfsAndOs3(1e4, 0.10, 0.40, 0.30, 'PFS', 'OS')

## use as generator (if you use TrialSimulator for simulation)

pfs_and_os <- endpoint(name = c('PFS', 'os'),
                       type = c('tte', 'tte'),
                       generator = CorrelatedPfsAndOs3,
                       h01 = .06, h02 = .30, h12 = .30,
                       pfs_name = 'PFS', os_name = 'os')

pfs_and_os # run it in console to see summary report

Description

Generate correlated PFS, OS and objective response using the four-states model. It can be used as custom generator of endpoint().

Usage

CorrelatedPfsAndOs4(
  n,
  transition_probability,
  duration,
  death_name = "death",
  progression_name = "progression",
  response_name = "response"
)

Arguments

Value

A data frame of n rows and 6 columns (response, progression, death, and their event indicators with 1 means event and 0 means censored at duration). The column names are <death_name>, <death_name>_event, <progression_name>, <progression_name>_event, <response_name> and <response_name>_event.

Note that it returns time-to-response for each patients with status of censoring at pre-set duration. If a binary indicator of response at a time point is needed as an endpoint, we may write a wrapper function to convert the column <response_name> to binary and remove the column <response_name>_event from return value.

Examples

m <- matrix(c(0.99, 0.0035, 0.0055, 0.0010,
                 0, 0.9900, 0.0052, 0.0048,
                 0,      0, 0.9960, 0.0040,
                 0,      0,      0,      1),
             nrow = 4, byrow = TRUE)

## use as function (if you don't use TrialSimulator for simulation)

dat <- CorrelatedPfsAndOs4(1e4, m, 365 * 3)

## use as generator (if you use TrialSimulator for simulation)

ep <- endpoint(name = c('pfs', 'os', 'or'),
               type = c('tte', 'tte', 'tte'), ## OR is TTE, not binary
               generator = CorrelatedPfsAndOs4,
               transition_probability = m,
               duration = 365 * 3,
               death_name = 'os', ## rename output from generator to match with "name"
               progression_name = 'pfs',
               response_name = 'or')

ep # run it in console to see summary report

Description

Apply a milestone-triggered crossover to patients who are still in the trial.

Unlike a regimen registered via add_regimen() (which is applied once, at enrollment), crossover() is meant to be called inside a milestone's action function. At the earliest crossover (calendar) time T = trial$get_current_time() + delay, eligible patients may switch to a new treatment, and only their post-switch endpoint values are altered; already-observed data is left intact. The crossover triplet is stacked onto the trial's regimen, so it is also re-applied to patients enrolled later.

Eligibility (the pool passed to what()) consists of patients with at least one endpoint still "open" (unobserved, dropout-/duration-aware) at T; fully-observed patients are excluded. when() must return a switch time with enroll_time + switch_time >= T (a crossover cannot predate its opening) or an error is raised. how() may only change post-switch outcomes; returning a changed value for a pre-switch/locked cell raises an error.

Two helper columns are injected into patient_data for the triplet functions: earliest_crossover_calendar_time (= T) and earliest_crossover_time_from_enrollment (= max(T - enroll_time, 0)), so when() can write e.g. switch_time = pmax(pfs, earliest_crossover_time_from_enrollment).

Note that this function should only be called within action functions of milestones. It is users' responsibility to ensure that and TrialSimulator has no way to track it.

This is a user-friendly wrapper of the member function of trial, i.e., Trials$crossover(). Users who are not familiar with the concept of classes may consider using this wrapper directly.

Usage

crossover(trial, what, how, when = NULL, delay = 0, ...)

Arguments

Value

no return value, called for its side effect of updating trial.

Description

This is an action function that does nothing when the corresponding milestone is triggered. When the listener is monitoring a trial and determining the time to trigger a milestone, data is automatically locked with other necessary data manipulations (censoring, truncation, etc.) are executed. If the users have no intent to modify the trial adaptively at the milestone, e.g., adding (add_arms()) or removing (remove_arms()) arm(s), changing sampling ratio(s) (update_sample_ratio()), stopping follow-up of a cohort (stop_followup()), carrying out statistical testing, or saving intermediate results (save(), etc.), then this function can be used to set the argument action when creating a new milestone. Note that the triggering time and number of observations/events of endpoints at a milestone with action = doNothing is still recorded in output automatically.

Usage

doNothing(trial, ...)

Arguments

Value

This function returns NULL. Actually, nothing is done in this function.

Description

This function may be useful to advanced users of TrialSimulator. It creates a wrapper function of a random number generator, while fixing a subset or all of arguments. This function is design to prevent inadvertent changing to arguments of random number generator. See examples below.

Usage

DynamicRNGFunction(fn, ...)

Arguments

Value

a function to generate random number based on fn and arguments in .... Specified arguments will be fixed and cannot be changed when invoking DynamicRNGFunction(fn, ...)(). For example, if foo <- DynamicRNGFunction(rnorm, sd = 2), then foo(n = 100) will always generate data from normal distribution of variance 4. foo(n = 100, sd = 1) will trigger an error. However, if an argument is not specified in DynamicRNGFunction, then it can be specified later. For example, foo(n = 100, mean = -1) will generate data from N(-1, 4).

Examples

# example code
dfunc <- DynamicRNGFunction(rnorm, sd = 3.2)
x <- dfunc(1e3) # mean 0 and sd 3.2
hist(x)

y <- dfunc(1e3, mean = 3.5) # mean can be changed
mean(y)

try(z <- dfunc(1e3, sd = 1)) # error because sd is fixed in dfunc

Description

Define one or multiple endpoints. This is a user-friendly wrapper for the class constructor Endpoints$new. Users who are not familiar with the concept of classes may consider using this wrapper directly.

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

Usage

endpoint(name, type, readout = NULL, generator, ...)

Arguments

Value

an object of R6 class Endpoints, representing one or more endpoints.

Examples

set.seed(12345)
## Example 1. Generate a time-to-event endpoint.
## Two columns are returned, one for time, one for event (1/0, 0 for
## A built-in RNG function is used to handle piecewise constant exponential
## distribution
risk <- data.frame(
  end_time = c(1, 10, 26.0, 52.0),
  piecewise_risk = c(1, 1.01, 0.381, 0.150) * exp(-3.01)
)

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

# run it in R console to display a summary report
# event indicator takes values 0/1
pfs

## Example 2. Generate continuous and binary endpoints using R's built-in
## RNG functions, e.g. rnorm, rexp, rbinom, etc.
ep1 <- endpoint(
         name = 'cd4', type = 'non-tte', generator = rnorm, readout = c(cd4=1),
         mean = 1.2)
ep2 <- endpoint(
         name = 'resp_time', type = 'non-tte', generator = rexp, readout = c(resp_time=0),
         rate = 4.5)
ep3 <- endpoint(
         name = 'orr', type = 'non-tte', readout = c(orr=3), generator = rbinom,
         size = 1, prob = .4)

ep1 # run it in R console. Mean and sd should be comparable to (1.2, 1.0)

ep2 # run it in R console. Median should be comparable to log(2)/4.5 = 0.154

ep3 # run it in R console. Mean and sd should be comparable to 0.4 and 0.49


## Example3: delayed effect
## Use piecewise constant exponential random number generator
## Baseline hazards are piecewise constant
## Hazard ratios are piecewise constant, resulting a delayed effect.
## Note that this example is for explaining the concept of "endpoint".
## Generating endpoint data manually is not the recommended way to use this package.

run <- TRUE

if (!requireNamespace("survminer", quietly = TRUE)) {
  run <- FALSE
  message("Please install 'survminer' to run this example.")
}

if (!requireNamespace("survival", quietly = TRUE)) {
  run <- FALSE
  message("Please install 'survival' to run this example.")
}

if(run){
risk1 <- risk
ep1 <- endpoint(
  name = 'pfs', type='tte',
  generator = PiecewiseConstantExponentialRNG,
  risk=risk1, endpoint_name = 'pfs')

risk2 <- risk1
risk2$hazard_ratio <- c(1, 1, .6, .4)
ep2 <- endpoint(
  name = 'pfs', type='tte',
  generator = PiecewiseConstantExponentialRNG,
  risk=risk2, endpoint_name = 'pfs')

n <- 1000
tte <- rbind(ep1$get_generator()(n), ep2$get_generator()(n))
arm <- rep(0:1, each = n)
dat <- data.frame(tte, arm)
sfit <- survival::survfit(
  survival::Surv(time = pfs, event = pfs_event) ~ arm, dat)

survminer::ggsurvplot(sfit,
           data = dat,
           pval = TRUE,  # Show p-value
           conf.int = TRUE,  # Show confidence intervals
           risk.table = TRUE,  # Add risk table
           palette = c("blue", "red"))


## print summary reports for endpoint objects in console
ep1
ep2

}

## Example 4: generate correlated pfs and os
## See vignette('simulatePfsAndOsIdm') and vignette('simulatePfsAndOsGumbel')

Description

Create a class of endpoint to specify its name, type, readout time (optional) and assign a random number generator.

Public methods in this R6 class are used in developing this package. Thus, I have to export the whole R6 class which exposures all public methods. However, none of the public methods is useful to end users except for the one below.

• $print() print a summary report of endpoint(s) based on example data from the generator.

In addition, $test_generator(), $get_generator() and $get_name() are for exploratory purpose only. They appear in examples and vignettes to help users understand how this class works, but they are not needed at all in formal simulation once users know how to use this package.

Internal machinery. The remaining public methods ($get_uid() and $update_generator()) are public only because they are invoked on an endpoint object by other components of the package (arms), which R6 cannot grant through private members. Users should not call them directly.

Value

an R6Class generator object; use endpoint() to create endpoints.

Methods

Public methods

• Endpoints$new()

• Endpoints$test_generator()

• Endpoints$get_generator()

• Endpoints$update_generator()

• Endpoints$get_uid()

• Endpoints$get_name()

• Endpoints$print()

• Endpoints$clone()

Method new()

initialize an endpoint.

Usage

Endpoints$new(name, type, readout = NULL, generator, ...)

Arguments

Method test_generator()

test random number generator of the endpoints. It returns an example dataset of an endpoint object. Note that users of TrialSimulator does not need to call this function to generate trial data; instead, the package will call this function at milestone automatically. Users may see example in vignette where this function is called. However, it is for illustration purpose only. In practice, this function may be used for debugging if users suspect some issues in custom generator, otherwise, this function should never been called in formal simulation.

Usage

Endpoints$test_generator(n = 1000)

Arguments

Method get_generator()

return random number generator of an endpoint

Usage

Endpoints$get_generator()

Method update_generator()

INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.

update endpoint generator

Usage

Endpoints$update_generator(generator, ...)

Arguments

Method get_uid()

INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.

return uid

Usage

Endpoints$get_uid()

Method get_name()

return endpoints' name

Usage

Endpoints$get_name()

Method print()

print an endpoint object

Usage

Endpoints$print(categorical_vars = NULL)

Arguments

Examples

rng <- function(n){
  data.frame(x = sample(1:3, n, replace = TRUE),
             y = sample(1:3, n, replace = TRUE)
            )
}
ep <- endpoint(name = c('x', 'y'),
               type = c('non-tte', 'non-tte'),
               readout = c(x = 0, y = 0),
               generator = rng)

## x and y as continuous endpoints, thus mean and sd are reported
ep

## force y to be categorical to create barplot of it
print(ep, categorical_vars = 'y')

Method clone()

The objects of this class are cloneable with this method.

Usage

Endpoints$clone(deep = FALSE)

Arguments

Examples

# Instead of using Endpoints$new(), please use endpoint(), a user-friendly
# wrapper to define endpoints. See examples in ?endpoint.


## ------------------------------------------------
## Method `Endpoints$print`
## ------------------------------------------------


rng <- function(n){
  data.frame(x = sample(1:3, n, replace = TRUE),
             y = sample(1:3, n, replace = TRUE)
            )
}
ep <- endpoint(name = c('x', 'y'),
               type = c('non-tte', 'non-tte'),
               readout = c(x = 0, y = 0),
               generator = rng)

## x and y as continuous endpoints, thus mean and sd are reported
ep

## force y to be categorical to create barplot of it
print(ep, categorical_vars = 'y')

Description

Define a condition to trigger trial milestone by the number of randomized patients. The milestone will be triggered when a trial has enrolled at least the specified number of patients. It can be used combined with conditions specified by calendarTime and eventNumber.

Refer to the vignette to learn how to define milestones when performing simulation using TrialSimulator.

Usage

enrollment(n, ..., arms = NULL, min_treatment_duration = 0)

Arguments

Value

an object of class 'Condition'

Examples

## ensure sufficient sample size of whole trial
enrollment(n = 100)

## ensure sufficient sample size in sub-group of interest
enrollment(n = 100, biomarker1 == 'positive' & biomarker2 == 'high')

## ensure sufficient sample size in high dose + placebo
enrollment(n = 1000, arms = c('high dose', 'placebo'))

## ensure sufficient treatment duration
enrollment(n = 500, min_treatment_duration = 2)

Description

Define a condition to trigger trial milestone by the number of events of a time-to-event endpoint or the number of non-missing observations of a non-time-to-event endpoint. The milestone will be triggered when a trial has observed at least the specified number of endpoint events (or non-missing observations). It can be used combined with conditions specified by calendarTime and enrollment.

Number of events for a time-to-event endpoint can vary at different milestones as more patients are randomized into a trial, or more events onset over time.

Number of non-missing observations for a non-time-to-event endpoint can vary at different milestones as more patients are randomized into a trial, or more patients have been treated until their readout time (thus, NA turns to a value).

Both numbers are affected by dropout.

Refer to the vignette to learn how to define milestones when performing simulation using TrialSimulator.

Usage

eventNumber(endpoint, n, ..., arms = NULL)

Arguments

Value

an object of class 'Condition'

Description

Expands the compact regimen_trajectory column in locked data (returned by trial$get_locked_data()) into a long-format data frame with one row per regimen segment per patient.

The regimen_trajectory column stores each patient's treatment history as a semicolon-separated string of "name\@time" entries, e.g. "placebo\@0;low dose\@8.5". expandRegimen parses this into two additional columns:

• regimen — name of the treatment regimen

• switch_time_from_enrollment — time from enrollment at which the patient switched to this regimen

The regimen_trajectory column is dropped from the result.

Usage

expandRegimen(data)

Arguments

Value

a long-format data frame: one row per regimen segment per patient, with regimen and switch_time_from_enrollment appended and regimen_trajectory removed.

Examples

## Not run: 
locked <- trial$get_locked_data('final')
long   <- expandRegimen(locked)

## End(Not run)

Description

Fit Cox proportional hazards model on an time-to-event endpoint.

Refer to this vignette for more information and examples.

Usage

fitCoxph(formula, placebo, data, alternative, scale, ..., tidy = TRUE)

Arguments

Value

a data frame with columns:

arm

name of the treatment arm.

placebo

name of the placebo arm.

estimate

estimate of main effect of arm, depending on scale.

p

one-sided p-value for log hazard ratio (treated vs placebo).

info

the number of events of the endpoint in the subset.

z

the z statistics of log hazard ratios.

Description

Test rate difference by comparing it to a pre-specified value using the Farrington-Manning test.

Refer to this vignette for more information and examples.

Usage

fitFarringtonManning(endpoint, placebo, data, alternative, ..., delta = 0)

Arguments

Value

a data frame with columns:

arm

name of the treatment arm.

placebo

name of the placebo arm.

estimate

estimate of rate difference.

p

one-sided p-value for log odds ratio (treated vs placebo).

info

sample size in the subset with NA being removed.

z

the z statistics of log odds ratio (treated vs placebo).

References

Farrington, Conor P., and Godfrey Manning. "Test statistics and sample size formulae for comparative binomial trials with null hypothesis of non-zero risk difference or non-unity relative risk." Statistics in medicine 9.12 (1990): 1447-1454.

Description

Fit linear regression model on a continuous endpoint.

Refer to this vignette for more information and examples.

Usage

fitLinear(formula, placebo, data, alternative, ...)

Arguments

Value

a data frame with columns:

arm

name of the treatment arm.

placebo

name of the placebo arm.

estimate

estimate of average treatment effect of arm.

p

one-sided p-value for between-arm difference (treated vs placebo).

info

sample size used in model with NA being removed.

z

z statistics of between-arm difference (treated vs placebo).

Description

Fit logistic regression model on an binary endpoint.

Refer to this vignette for more information and examples.

Usage

fitLogistic(formula, placebo, data, alternative, scale, ...)

Arguments

Value

a data frame with columns:

arm

name of the treatment arm.

placebo

name of the placebo arm.

estimate

estimate depending on scale.

p

one-sided p-value for log odds ratio (treated vs placebo).

info

sample size used in model with NA being removed.

z

z statistics of log odds ratio (treated vs placebo).

Description

Compute log rank test statistic on an endpoint.

Refer to this vignette for more information and examples.

Usage

fitLogrank(formula, placebo, data, alternative, ..., tidy = TRUE)

Arguments

Value

a data frame with columns:

arm

name of the treatment arm.

placebo

name of the placebo arm.

p

one-sided p-value for log-rank test (treated vs placebo).

info

the number of events of the endpoint in the subset.

z

the z statistic of the log rank test, with the sign of the log hazard ratio of treatment vs placebo.

If the statistic is undefined because its variance is zero (e.g., no informative event comparison in the subset), a simulation placeholder z = 0 with the corresponding p = 0.5 is returned with a warning rather than an error, so that a few such replicates in a large simulation do not require error handling in action functions. The placeholder carries no evidence either way and is not a standardized normal statistic.

Description

Internal function that retrieves precomputed simulation results. Not meant for use by package users.

Usage

getAdaptiveDesignOutput()

Value

A data frame containing simulation results of 1000 replicates.

Description

Internal function that retrieves precomputed simulation results. Not meant for use by package users.

Usage

getConditionalPowerOutput()

Value

A data frame containing simulation results of 1000 replicates.

Description

Internal function that retrieves precomputed simulation results. Not meant for use by package users.

Usage

getDoseRangingOutput()

Value

A data frame containing simulation results of 10 replicates.

Description

Internal function that retrieves precomputed simulation results. Not meant for use by package users.

Usage

getEnrichmentDesignOutput()

Value

A data frame containing simulation results of 10000 replicates under the alternative and 10000 replicates under the global null, distinguished by the column scenario.

Description

Internal function that retrieves precomputed simulation results. Not meant for use by package users.

Usage

getFixedDesignOutput()

Value

A data frame containing simulation results of 1000 replicates.

Description

Perform graphical testing under group sequential design for one or multiple endpoints. See Maurer & Bretz (2013).

Methods

Public methods

• GraphicalTesting$new()

• GraphicalTesting$reset()

• GraphicalTesting$is_valid_hid()

• GraphicalTesting$get_hypothesis_name()

• GraphicalTesting$get_weight()

• GraphicalTesting$set_weight()

• GraphicalTesting$get_alpha()

• GraphicalTesting$set_alpha()

• GraphicalTesting$get_hypotheses_ids()

• GraphicalTesting$get_number_hypotheses()

• GraphicalTesting$get_hids_not_in_graph()

• GraphicalTesting$get_testable_hypotheses()

• GraphicalTesting$has_testable_hypotheses()

• GraphicalTesting$is_in_graph()

• GraphicalTesting$is_testable()

• GraphicalTesting$get_hid()

• GraphicalTesting$reject_a_hypothesis()

• GraphicalTesting$set_trajectory()

• GraphicalTesting$get_trajectory()

• GraphicalTesting$test_hypotheses()

• GraphicalTesting$test()

• GraphicalTesting$get_current_testing_results()

• GraphicalTesting$get_current_decision()

• GraphicalTesting$print()

• GraphicalTesting$clone()

Method new()

Initialize an object for graphical testing procedure. Group sequential design is also supported.

Usage

GraphicalTesting$new(
  alpha,
  transition,
  alpha_spending,
  planned_max_info,
  hypotheses = NULL,
  silent = FALSE
)

Arguments

Method reset()

reset an object of class GraphicalTesting to original status so that it can be reused.

Usage

GraphicalTesting$reset()

Method is_valid_hid()

determine if index of a hypothesis is valid

Usage

GraphicalTesting$is_valid_hid(hid)

Arguments

Method get_hypothesis_name()

get name of a hypothesis given its index.

Usage

GraphicalTesting$get_hypothesis_name(hid)

Arguments

Method get_weight()

return weight between two nodes

Usage

GraphicalTesting$get_weight(hid1, hid2)

Arguments

Method set_weight()

update weight between two nodes

Usage

GraphicalTesting$set_weight(hid1, hid2, value)

Arguments

Method get_alpha()

return alpha allocated to a hypothesis when calling this function. Note that a function can be called several time with the graph is updated dynamically. Thus, returned alpha can be different even for the same hid.

Usage

GraphicalTesting$get_alpha(hid)

Arguments

Method set_alpha()

update alpha of a hypothesis

Usage

GraphicalTesting$set_alpha(hid, value)

Arguments

Method get_hypotheses_ids()

return all valid hid

Usage

GraphicalTesting$get_hypotheses_ids()

Method get_number_hypotheses()

return number of hypotheses, including those been rejected.

Usage

GraphicalTesting$get_number_hypotheses()

Method get_hids_not_in_graph()

return index of hypotheses that are rejected.

Usage

GraphicalTesting$get_hids_not_in_graph()

Method get_testable_hypotheses()

return index of hypotheses with non-zero alphas, thus can be tested at the current stage.

Usage

GraphicalTesting$get_testable_hypotheses()

Method has_testable_hypotheses()

determine whether at least one hypothesis is testable. If return FALSE, the testing procedure is completed.

Usage

GraphicalTesting$has_testable_hypotheses()

Method is_in_graph()

determine whether a hypothesis is not yet rejected (in graph).

Usage

GraphicalTesting$is_in_graph(hid)

Arguments

Method is_testable()

determine whether a hypothesis has a non-zero alpha allocated.

Usage

GraphicalTesting$is_testable(hid)

Arguments

Method get_hid()

convert hypothesis's name into (unique) index.

Usage

GraphicalTesting$get_hid(hypothesis)

Arguments

Method reject_a_hypothesis()

remove a node from graph when a hypothesis is rejected

Usage

GraphicalTesting$reject_a_hypothesis(hypothesis)

Arguments

Method set_trajectory()

save new testing results at current stage

Usage

GraphicalTesting$set_trajectory(result)

Arguments

Method get_trajectory()

return testing results by the time this function is called. Note that graphical test is carried out in a sequential manner. Users may want to review the results anytime. Value returned by this function can possibly vary over time.

Usage

GraphicalTesting$get_trajectory()

Method test_hypotheses()

test hypotheses using p-values (and other information in stats) base on the current graph. All rows should have the same order number.

Usage

GraphicalTesting$test_hypotheses(stats)

Arguments

Method test()

test hypotheses using p-values (and other information in stats) base on the current graph. Users can call this function multiple times. P-values of the same order should be passed through stats together. P-values of multiple orders can be passed together as well. For example, if users only have p-values at current stage, they can call this function and update the graph accordingly. In this case, column order in stats is a constant. They can call this function again when p-values of next stage is available, where order is another integer. In simulation, if p-values of all stages are on hand, users can call this function to test them all in a single pass. In this case, column order in stats can have different values.

Usage

GraphicalTesting$test(stats)

Arguments

Returns

a data frame returned by get_current_testing_results. It contains details of each of the testing steps.

Method get_current_testing_results()

return testing results with details by the time this function is called. This function can be called by users by multiple times, thus the returned value varies over time. This function is called by GraphicalTesting::test, and returns a data frame consisting of columns

hypothesis

name of hypotheses.

obs_p_value

observed p-values.

max_allocated_alpha

maximum allocated alpha for the hypothesis.

decision

'reject' or 'accept' the hypotheses.

stages

stage of a hypothesis.

order

order number that this hypothesis is tested for the last time. It is different from stages.

typeOfDesign

name of alpha spending functions.

Usage

GraphicalTesting$get_current_testing_results()

Method get_current_decision()

get current decisions for all hypotheses. Returned value could changes over time because it depends on the stages being tested already.

Usage

GraphicalTesting$get_current_decision()

Returns

a named vector of values "accept" or "reject". Note that if a hypothesis is not yet tested when calling this function, the decision for that hypothesis would be "accept".

Method print()

generic function for print

Usage

GraphicalTesting$print(graph = TRUE, trajectory = TRUE, ...)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

GraphicalTesting$clone(deep = FALSE)

Arguments

Examples

## Example 1
## dry-run to study the behavior of a graph
## without group sequential design
if(interactive()){
eps <- .01
alpha <- c(.01, .04, 0, 0, 0)
transition <- matrix(c(
  0, 0, 0, 0, 1,
  0, 0, .75, 0, .25,
  0, 1/2-eps/2, 0, eps, 1/2-eps/2,
  0, 0, 0, 0, 0,
  0, 1/2, 1/2, 0, 0
), nrow = 5, byrow = TRUE)

## dummy can be anything, we don't actually use it
asf <- rep('asOF', 5)
## dummy can be anything, we don't actually use it
max_info <- c(300, 1100, 1100, 1100, 500)

hs <- c('H1: UPCR IgA', 'H2: eGFR GN', 'H3: eGFR GN 10wk', 'H5: 2nd Endpoints', 'H4: eGFR IgA')

## initialize an object
gt <- GraphicalTesting$new(alpha, transition, asf, max_info, hs)
print(gt)

## reject hypotheses based on customized order
## to understand the behavior of a testing strategy
## Any other rejection order is possible
gt$reject_a_hypothesis('H1: UPCR IgA')
print(gt)

gt$reject_a_hypothesis('H2: eGFR GN')
print(gt)

gt$reject_a_hypothesis('H4: eGFR IgA')
print(gt)

gt$reject_a_hypothesis('H3: eGFR GN 10wk')
print(gt)

gt$reset()
}

## Example 2
## Example modified from vignettes in gMCPLite:
## Graphical testing for group sequential design
if(interactive()){
## initial alpha split to each of the hypotheses
alpha <- c(.01, .01, .004, .0, .0005, .0005)

## transition matrix of the initial graph
transition <- matrix(c(
  0, 1, 0, 0, 0, 0,
  0, 0, .5, .5, 0, 0,
  0, 0, 0, 1, 0, 0,
  0, 0, 0, 0, .5, .5,
  0, 0, 0, 0, 0, 1,
  .5, .5, 0, 0, 0, 0
), nrow = 6, byrow = TRUE)

## alpha spending functions per hypothesis
asf <- c('asUser', 'asOF', 'asUser', 'asOF', 'asOF', 'asOF')

## planned maximum number of events per hypothesis
max_info <- c(295, 800, 310, 750, 500, 1100)

## name of hypotheses
hs <- c('H1: OS sub',
        'H2: OS all',
        'H3: PFS sub',
        'H4: PFS all',
        'H5: ORR sub',
        'H6: ORR all')

gt <- GraphicalTesting$new(alpha, transition, asf, max_info, hs)

## print initial graph
gt

## nominal p-values at each stage
## Note: p-values with same order are calculated with the same locked data
## Note: alpha_spent is only specified for hypotheses using custom alpha
##       spending function "asUser"
stats <-
  data.frame(
    order = c(1:3, 1:3, 1:2, 1:2, 1, 1),
    hypotheses = c(rep('H1: OS sub', 3), rep('H2: OS all', 3),
                   rep('H3: PFS sub', 2), rep('H4: PFS all', 2),
                   'H5: ORR sub', 'H6: ORR all'),
    p = c(.03, .0001, .000001, .2, .15, .1, .2, .001, .3, .2, .00001, .1),
    info = c(185, 245, 295, 529, 700, 800, 265, 310, 675, 750, 490, 990),
    is_final = c(F, F, T, F, F, T, F, T, F, T, T, T),
    max_info = c(rep(295, 3), rep(800, 3), rep(310, 2), rep(750, 2), 490, 990),
    alpha_spent = c(c(.1, .4, 1), rep(NA, 3), c(.3, 1), rep(NA, 2), NA, NA)
  )

## test the p-values from the first analysis, plot the updated graph
gt$test(stats %>% dplyr::filter(order==1))

## test the p-values from the second analysis, plot the updated graph
gt$test(stats %>% dplyr::filter(order==2))

## test the p-values from the third analysis, plot the updated graph
## because no futher test would be done, displayed results are final
gt$test(stats %>% dplyr::filter(order==3))


## plot the final status of the graph
print(gt, trajectory = FALSE)

## you can get final testing results as follow
gt$get_current_testing_results()

## if you want to see step-by-step details
print(gt$get_trajectory())

## equivalently, you can call gt$test(stats) for only once to get same results.
gt$reset()
gt$test(stats)

## if you only want to get the final testing results
gt$get_current_decision()
}

Description

Perform group sequential test for a single endpoint based on sequential one-sided p-values at each stages. Selected alpha spending functions, including user-defined functions, are supported. Boundaries are calculated with 'rpact'. At the final analysis, adjustment can be applied for over-running or under-running trial where observed final information is greater or lower than the planned maximum information. See Wassmer & Brannath, 2016, p78f. The test is based on p-values not z statistics because it is easier to not handling direction of alternative hypothesis in current implementation. In addition, only one-sided test is supported which should be sufficient for common use in clinical design.

Value

an R6Class generator object; create a test with GroupSequentialTest$new().

Methods

Public methods

• GroupSequentialTest$new()

• GroupSequentialTest$get_name()

• GroupSequentialTest$get_alpha()

• GroupSequentialTest$set_alpha_spending()

• GroupSequentialTest$get_alpha_spending()

• GroupSequentialTest$get_max_info()

• GroupSequentialTest$set_max_info()

• GroupSequentialTest$get_stage()

• GroupSequentialTest$reset()

• GroupSequentialTest$set_trajectory()

• GroupSequentialTest$get_trajectory()

• GroupSequentialTest$get_stage_level()

• GroupSequentialTest$test_one()

• GroupSequentialTest$test()

• GroupSequentialTest$print()

• GroupSequentialTest$clone()

Method new()

initialize a group sequential test. Now only support one-sided test based on p-values.

Usage

GroupSequentialTest$new(
  alpha = 0.025,
  alpha_spending = c("asP", "asOF", "asUser"),
  planned_max_info,
  name = "H0",
  silent = TRUE
)

Arguments

Method get_name()

get name of hypothesis

Usage

GroupSequentialTest$get_name()

Method get_alpha()

get overall alpha

Usage

GroupSequentialTest$get_alpha()

Method set_alpha_spending()

set alpha spending function. This is useful when set 'asUser' at the final stage to adjust for an under- or over-running trial.

Usage

GroupSequentialTest$set_alpha_spending(asf)

Arguments

Method get_alpha_spending()

return character of alpha spending function

Usage

GroupSequentialTest$get_alpha_spending()

Method get_max_info()

return planned maximum information

Usage

GroupSequentialTest$get_max_info()

Method set_max_info()

set planned maximum information. This is used at the final stage to adjust for an under- or over-running trial.

Usage

GroupSequentialTest$set_max_info(obs_max_info)

Arguments

Method get_stage()

get current stage.

Usage

GroupSequentialTest$get_stage()

Method reset()

an object of class GroupSequentialTest is designed to be used sequentially by calling GroupSequentialTest$test. When all planned tests are performed, no further analysis could be done. In that case keep calling GroupSequentialTest$test will trigger an error. To reuse the object for a new set of staged p-values, call this function to reset the status to stage 1. See examples. This implementation can prevent the error that more than the planned number of stages are tested.

Usage

GroupSequentialTest$reset()

Method set_trajectory()

save testing result at current stage

Usage

GroupSequentialTest$set_trajectory(result, is_final = FALSE)

Arguments

Method get_trajectory()

return testing trajectory until current stage. This function can be called at any stage. See examples.

Usage

GroupSequentialTest$get_trajectory()

Method get_stage_level()

compute boundaries given current (potentially updated) settings. It returns different values if settings are changed over time.

Usage

GroupSequentialTest$get_stage_level()

Method test_one()

test a hypothesis with the given p-value at current stage

Usage

GroupSequentialTest$test_one(
  p_value,
  is_final,
  observed_info,
  alpha_spent = NA_real_
)

Arguments

Method test()

Carry out test based on group sequential design. If p_values is NULL, dummy values will be use and boundaries are calculated for users to review.

Usage

GroupSequentialTest$test(
  observed_info,
  is_final,
  p_values = NULL,
  alpha_spent = NULL
)

Arguments

Method print()

generic function for print

Usage

GroupSequentialTest$print()

Method clone()

The objects of this class are cloneable with this method.

Usage

GroupSequentialTest$clone(deep = FALSE)

Arguments

Examples

## Note: examples showed here replicate the results from
## https://www.rpact.org/vignettes/planning/rpact_boundary_update_example/

## Example 1. Generate boundaries for a pre-fix group sequential design
gst <- GroupSequentialTest$new(
  alpha = .025, alpha_spending = 'asOF',
  planned_max_info = 387)

## without giving p-values, boundaries are returned without actual testing
gst$test(observed_info = c(205, 285, 393), is_final = c(FALSE, FALSE, TRUE))
gst

## Example 2. Calculate boundaries with observed information at stages
## No p-values are provided

## get an error without resetting an used object
try( gst$test(observed_info = 500, is_final = FALSE) )

## reset the object for re-use
gst$reset()
gst$test(observed_info = c(205, 285, 393), is_final = c(FALSE, FALSE, TRUE))
gst

## Example 3. Test stagewise p-values sequentially
gst$reset()

gst$test(observed_info = 205, is_final = FALSE, p_values = .09)
gst$test(285, FALSE, .006)

## print testing trajectory by now
gst

gst$test(393, TRUE, .002)

## print all testing trajectory
gst

## you can also test all stages at once
## the result is the same as calling test() for each of the stages
gst$reset()
gst$test(c(205, 285, 393), c(FALSE, FALSE, TRUE), c(.09, .006, .002))
gst

## Example 4. use user-define alpha spending
gst <- GroupSequentialTest$new(
  alpha = .025, alpha_spending = 'asUser',
  planned_max_info = 387)

gst$test(
  observed_info = c(205, 285, 393),
  is_final = c(FALSE, FALSE, TRUE),
  alpha_spent = c(.005, .0125, .025))
gst

Description

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

Listener is an important concept of TrialSimulator. Used with a trial object in a controller, a listener can monitor a running trial to execute user-defined actions when it determine condition of triggering a milestone is met. This mechanism allows the package users to focus on the development of action functions in a simulation.

Usage

listener(silent = FALSE)

Arguments

Value

an object of R6 class Listeners, monitoring and triggering milestones of a trial.

Examples

listener <- listener()

Description

Create a class of listener. A listener monitors the trial while checking condition of pre-defined milestones. Actions are triggered and executed automatically.

Public methods in this R6 class are used in developing this package. Thus, we have to export the whole R6 class which exposures all public methods. However, only the public methods in the list below are useful to end users.

• $add_milestones() register milestone(s) with the listener.

• $get_milestone_names() return names of registered milestones.

Internal machinery. The remaining public methods ($monitor(), $mute() and $reset()) are public only because they are invoked on a listener object by other components of the package (controllers), which R6 cannot grant through private members. Users should not call them directly.

Value

an R6Class generator object; use listener() to create a listener.

Methods

Public methods

• Listeners$new()

• Listeners$add_milestones()

• Listeners$get_milestone_names()

• Listeners$monitor()

• Listeners$mute()

• Listeners$reset()

• Listeners$clone()

Method new()

initialize a listener

Usage

Listeners$new(silent = FALSE)

Arguments

Method add_milestones()

register milestones with listener. Order in ... matter as they are scanned and triggered in that order. It is users' responsibility to use reasonable order when calling this function, otherwise, the result of Listeners$monitor() can be problematic.

Usage

Listeners$add_milestones(...)

Arguments

Examples

listener <- listener()
interim <- milestone(name = 'interim',
                     when = eventNumber('endpoint', n = 100)
                    )
final <- milestone(name = 'final',
                   when = calendarTime(time = 24)
                  )
listener$add_milestones(interim, final)

Method get_milestone_names()

return names of registered milestones

Usage

Listeners$get_milestone_names()

Method monitor()

INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.

scan, check, and trigger registered milestones. Milestones are triggered in the order when calling Listener$add_milestones.

Usage

Listeners$monitor(trial)

Arguments

Method mute()

INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.

mute all messages (not including warnings)

Usage

Listeners$mute(silent)

Arguments

Method reset()

INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.

reset all milestones registered to the listener. Usually, this is called before a controller can run additional replicates of simulation.

Usage

Listeners$reset()

Method clone()

The objects of this class are cloneable with this method.

Usage

Listeners$clone(deep = FALSE)

Arguments

Examples

##

## ------------------------------------------------
## Method `Listeners$add_milestones`
## ------------------------------------------------

listener <- listener()
interim <- milestone(name = 'interim',
                     when = eventNumber('endpoint', n = 100)
                    )
final <- milestone(name = 'final',
                   when = calendarTime(time = 24)
                  )
listener$add_milestones(interim, final)

Description

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

A milestone means the time point to take an action, e.g., carrying out (futility, interim, final) analysis for adding/removing arms, or stopping a trial early. It can also be any more general time point where trial data is used in decision making or adaptation. For example, one can define a milestone for changing randomization scheme, sample size re-assessment, trial duration extension etc.

Refer to the vignette to learn how to define milestones when performing simulation using TrialSimulator.

Usage

milestone(name, when, action = doNothing, ...)

Arguments

Value

an object of R6 class Milestones, representing a milestone of a trial.

Examples

## See vignette('conditionSystem')

Description

Create a class of milestone. A milestone means the time point to take an action, e.g., carrying out (futility, interim, final) analysis for adding/removing arms, or stopping a trial early. It can also be any more general time point where trial data is used in decision making or adaptation. For example, one can define a milestone for changing randomization scheme, sample size re-assessment, trial duration extension etc.

Public methods in this R6 class are used in developing this package. Thus, we have to export the whole R6 class which exposures all public methods. However, none of the public methods on this page is useful to end users. Instead, refer to the vignette to learn how to define milestones when performing simulation using TrialSimulator.

Value

an R6Class generator object; use milestone() to create a milestone.

Methods

Public methods

• Milestones$new()

• Milestones$get_name()

• Milestones$set_trigger_condition()

• Milestones$set_action_function()

• Milestones$get_trigger_status()

• Milestones$reset()

• Milestones$trigger_milestone()

• Milestones$mute()

• Milestones$clone()

Method new()

initialize milestone

Usage

Milestones$new(name, type = name, trigger_condition, action = doNothing, ...)

Arguments

Method get_name()

INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.

return name of milestone

Usage

Milestones$get_name()

Method set_trigger_condition()

INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.

replace the trigger condition of a not-yet-triggered milestone. This is invoked by the listener when it applies an update requested through Trials$update_milestone() within an action function. The as-designed condition, frozen at construction, is restored by reset() between simulation replicates.

Usage

Milestones$set_trigger_condition(trigger_condition)

Arguments

Method set_action_function()

INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.

replace the action function (and its fixed arguments) of a not-yet-triggered milestone. This is invoked by the listener when it applies an update requested through Trials$update_milestone() within an action function. The action in effect at construction is restored by reset() between simulation replicates.

Usage

Milestones$set_action_function(action, action_args = list())

Arguments

Method get_trigger_status()

INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.

return trigger status

Usage

Milestones$get_trigger_status()

Method reset()

INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.

reset an milestone so that it can be triggered again. Usually, this is called before the controller of a trial can run additional replicates of simulation. If the trigger condition or the action was replaced in-run through Trials$update_milestone(), the as-designed version is restored so that every replicate starts from the original design.

Usage

Milestones$reset()

Method trigger_milestone()

INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.

trigger an milestone (always TRUE) and execute action accordingly. It calls Trial$get_data_lock_time() to lock data based on conditions implemented in Milestones$trigger_condition. If time that meets the condition cannot be found, Trial$get_data_lock_time() will throw an error and stop the program. This means that user needs to adjust their trigger_condition (e.g., target number of events (target_n_events) is impossible to reach).

Usage

Milestones$trigger_milestone(trial)

Arguments

Method mute()

INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.

mute all messages (not including warnings)

Usage

Milestones$mute(silent)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

Milestones$clone(deep = FALSE)

Arguments

Description

This function can be used as generator to define endpoint. Implementation is based on this algorithm. This distribution can be used to simulate delayed treatment effect.

Usage

PiecewiseConstantExponentialRNG(n, risk, endpoint_name)

Arguments

Value

a data frame of n rows and two columns

<endpoint_name>

name of endpoint specified by users in endpoint_name.

<endpoint_name>_event

event indicator with 0/1 as censoring and event, respectively. Note that due to the nature of the algorithm to generate data from this distribution, it is possible to have the endpoint being censoring at the last end_time unless it is set to Inf.

Examples

# example code
# In this example, absolute risk in [0, 1) and [26, 52] are 0.0181 and
# 0.0027, respectively.
risk <- data.frame(
  end_time = c(1, 4.33, 26.0, 52.0),
  piecewise_risk = c(1, 1.01, 0.381, 0.150) * exp(-4.01)
)
PiecewiseConstantExponentialRNG(10, risk, 'PFS')

Description

Plot Triggering Time of Milestones in Simulated Trials

Usage

## S3 method for class 'milestone_time_summary'
plot(x, ...)

Arguments

Value

no return value, called to display a boxplot of milestone triggering times.

Description

Plot result of three-state illness-death model

Usage

## S3 method for class 'three_state_model'
plot(x, ...)

Arguments

Value

no return value, called to print the calibration table and display the corresponding plot.

Description

To generate endpoint that follows a piecewise exponential distribution and is correlated with other endpoints, the copula method is commonly used. The quantile function needs to be specified (e.g., in the simdata package). If a piecewise exponential distributed endpoint is independent to other endpoints, one can simply use TrialSimulator::PiecewiseConstantExponentialRNG() to specify the generator argument in endpoint().

There are many R packages implementing the quantile function of the piecewise exponential distributed random variable. Why do I implement it again? The reason is that this function is extremely important for simulating time-to-event endpoint in clinical trial simulation, thus the speed matters. qPiecewiseExponential() is implemented purely in R for code transparency, and is much faster than other packages.

Usage

qPiecewiseExponential(p, times, piecewise_risk)

Arguments

Value

A vector of quantiles.

Examples

## This code snippet can take > 10s to execute
if(interactive()){
library(TrialSimulator)

run <- TRUE
if(!requireNamespace("rpact", quietly = TRUE)){
  run <- FALSE
  message("Please install 'rpact' to run this example.")
}

if(!requireNamespace("PWEXP", quietly = TRUE)){
  run <- FALSE
  message("Please install 'PWEXP' to run this example.")
}

if(!requireNamespace("PWEALL", quietly = TRUE)){
  run <- FALSE
  message("Please install 'PWEALL' to run this example.")
}

if(run){

x <- solvePiecewiseConstantExponentialDistribution(
  surv_prob = c(.9, .75, .64, .42, .28),
  times = c(.4, 1.2, 4, 5.5, 9)
)

p <- stats::runif(1e5)

## fast, and only five lines of R codes
message('TrialSimulator::qPiecewiseExponential(): ')
system.time(
  a <- qPiecewiseExponential(
    p, times = x$end_time, piecewise_risk = c(x$piecewise_risk, .1)
  )
) |> print()

## > 10s
message('rpact::getPiecewiseExponentialQuantile(): ')
system.time(
  b <- rpact::getPiecewiseExponentialQuantile(
    p, piecewiseSurvivalTime = c(0, x$end_time),
    piecewiseLambda=c(x$piecewise_risk, .1)
  )
) |> print()

## equally fast, but implemented in Fortran
message('PWEALL::qpwe(): ')
system.time(
  c <- PWEALL::qpwe(p, rate = c(x$piecewise_risk, .1), tchange = c(0, x$end_time))$q
) |> print()

## equally fast, long codes in R (maybe more versatile?)
message('PWEXP::qpwexp(): ')
system.time(
  d <- PWEXP::qpwexp(p, rate = c(x$piecewise_risk, .1), breakpoint = x$end_time)
) |> print()

message('a == b: ')
all.equal(a, b) |> print()
message('a == c: ')
all.equal(a, c) |> print()
message('a == d: ')
all.equal(a, d) |> print()

}
}

Description

A random number generator returning only a constant. This can be used to set dropout time. Currently it is the default value of dropout time, with value = Inf.

This function can also be used as a generator of endpoint() if a constant endpoint is needed.

Usage

rconst(n, value)

Arguments

Value

a numeric vector of length n with all entries equal to value.

Description

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

A regimen defines the rules to select patients who switch treatments, to determine the time of switching, and to update patients' endpoint data.

Usage

regimen(what, when, how, ...)

Arguments

Value

an object of R6 class Regimens, representing a treatment regimen.

Description

Create a class of regimen. A regimen defines the rules to select treatments for patients switch, to determine the time of switching, and to update patients' endpoint data.

Public methods in this R6 class are used in developing this package. Thus, we have to export the whole R6 class which exposures all public methods. However, none of the public methods on this page is useful to end users. Instead, use regimen() to create a regimen and register it with a trial through trial$add_regimen() or trial$crossover().

Value

an R6Class generator object; use regimen() to create a regimen.

Methods

Public methods

• Regimens$new()

• Regimens$get_number_treatment_allocator()

• Regimens$get_treatment_allocator()

• Regimens$get_time_selector()

• Regimens$get_data_modifier()

• Regimens$get_treatment_allocator_args()

• Regimens$get_time_selector_args()

• Regimens$get_data_modifier_args()

• Regimens$get_earliest_crossover_calendar_time()

• Regimens$append_triplet()

• Regimens$clone()

Method new()

initialize regimen

Usage

Regimens$new(what, when, how, ..., earliest_crossover_calendar_time = 0)

Arguments

Method get_number_treatment_allocator()

INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.

return number of treatment allocators for regimen

Usage

Regimens$get_number_treatment_allocator()

Method get_treatment_allocator()

INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.

return user-defined new treatment for a patient

Usage

Regimens$get_treatment_allocator(index = NULL)

Arguments

Method get_time_selector()

INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.

return user-defined time selector

Usage

Regimens$get_time_selector(index = NULL)

Arguments

Method get_data_modifier()

INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.

return user-defined endpoint data modifier

Usage

Regimens$get_data_modifier(index = NULL)

Arguments

Method get_treatment_allocator_args()

INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.

return pre-bound arguments for the i-th treatment allocator

Usage

Regimens$get_treatment_allocator_args(index)

Arguments

Method get_time_selector_args()

INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.

return pre-bound arguments for the i-th time selector

Usage

Regimens$get_time_selector_args(index)

Arguments

Method get_data_modifier_args()

INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.

return pre-bound arguments for the i-th data modifier

Usage

Regimens$get_data_modifier_args(index)

Arguments

Method get_earliest_crossover_calendar_time()

INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.

return the earliest crossover calendar time of triplet(s)

Usage

Regimens$get_earliest_crossover_calendar_time(index = NULL)

Arguments

Method append_triplet()

INTERNAL MACHINERY: DO NOT CALL THIS METHOD DIRECTLY.

append one more triplet to the regimen. Used by milestone-triggered crossover to stack a new what/when/how (with its own earliest_crossover_calendar_time) onto an existing regimen without overwriting earlier triplets. Triplets are executed in append order.

Usage

Regimens$append_triplet(
  what,
  when,
  how,
  ...,
  earliest_crossover_calendar_time = 0
)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

Regimens$clone(deep = FALSE)

Arguments

Description

remove arms from a trial. The application of this function includes, but is not limited to, dose selection, enrichment analysis (select sub-population).

Note that this function should only be called within action functions of milestones. It is users' responsibility to ensure that and TrialSimulator has no way to track it.

Removing an arm has three effects. No patient is randomized to it afterwards; unenrolled patients are randomized again among the remaining arms. It leaves the set of arms in the trial, e.g., arms = NULL in eventNumber() and enrollment() no longer counts it, and dunnettTest() stops testing it at later milestones. Its data are censored at the time of removal, or additional_followup later, but stay in the trial data, so they are present in the locked data of later milestones.

additional_followup has no default, so that the decision is visible in the action function. With 0, follow-up of the patients in a removed arm stops at the milestone where the arm is removed, e.g., a dose dropped for futility. A positive value keeps following them for a fixed time beyond the milestone, and Inf for the rest of the trial, e.g., to collect overall survival or safety data of a dose that stops enrolling. The same value applies to all arms removed in one call; to grant different times to different arms, call this function once per arm. Events of a removed arm within its follow-up are counted by a later milestone only if the arm is listed in arms of its triggering condition; see the next section.

Usage

remove_arms(trial, arms_name, additional_followup)

Arguments

Value

no return value, called for its side effect of updating trial.

Counting on removed arms at later milestones

Which arms are removed, and how many, are usually decided from the data and thus unknown when milestones are defined. Three patterns cover the triggering conditions of later milestones:

• Count on the arms still in the trial: leave arms = NULL in eventNumber() or enrollment(). It is resolved when the milestone is evaluated, so any arm removed by then is excluded.

• Count on all arms of the design, including removed ones: list every arm of the design in arms of eventNumber() or enrollment(). All names are known when the design is written; a removed arm passes the check because it was once in the trial, and a warning is raised unless the trial is silent. This is how the total sample size of a trial is counted after a dose is dropped.

• Count on a subset that depends on which arm was removed, e.g., the control arm and the removed arm only: the subset is unknown when the later milestone is defined. Call update_milestone() in the same action function as remove_arms() to replace the triggering condition of the later milestone, with arms built from the arm just removed.

See the examples.

This is a user-friendly wrapper of the member function of trial, i.e., Trials$remove_arms(), which is used in vignettes. Users who are not familiar with the concept of classes may consider using this wrapper directly.

Examples

## Not run: 
## Within an action function: drop a dose and stop following its patients
## at this milestone. additional_followup has no default.
remove_arms(trial, 'low dose', additional_followup = 0)

## Drop a dose but follow its patients for another 12 months, e.g., for
## overall survival.
remove_arms(trial, 'low dose', additional_followup = 12)

## Drop a dose and follow its patients until the end of the trial.
remove_arms(trial, 'low dose', additional_followup = Inf)

## Different follow-up for different arms: one call per arm.
remove_arms(trial, 'low dose', additional_followup = 12)
remove_arms(trial, 'mid dose', additional_followup = Inf)

## A design with placebo and two doses. At dose selection, one dose may be
## dropped; which one, if any, is decided from the data.

## Pattern 1: the final analysis counts events in the arms still in the
## trial. arms = NULL is resolved when `final` is evaluated, so the dropped
## dose is excluded automatically.
final <- milestone(name = 'final',
                   when = eventNumber(endpoint = 'os', n = 300),
                   action = action_at_final)
# final is then registered with the listener

## Pattern 2: the final analysis counts events in all arms of the design,
## including a dropped dose (events up to its removal). List every arm;
## a dropped arm is accepted, with a warning unless the trial is silent.
## In this example, final analysis is triggered when in total 1000 patients
## are enrolled, including those from the removed arm.
final <- milestone(name = 'final',
                   when = enrollment(n = 1000,
                                     arms = c('placebo', 'low dose', 'high dose')),
                   action = action_at_final)
# final is then registered with the listener

## Pattern 3: the final analysis counts events in placebo and the dropped
## dose only. The pair is unknown when `final` is defined, so `final` is
## registered with a placeholder condition, and the action of dose
## selection replaces it after the removal. The placeholder is never
## evaluated: milestones are triggered in registration order, and the
## update takes effect before `final` is checked.
final <- milestone(name = 'final',
                   when = eventNumber(endpoint = 'os', n = 90), # placeholder
                   action = action_at_final)

action_at_dose_selection <- function(trial){
  locked_data <- trial$get_locked_data('dose selection')
  dropped <- ...  # the dose to drop, selected from locked_data, or NULL
  if(!is.null(dropped)){
    trial$remove_arms(dropped, additional_followup = 0)
    trial$update_milestone(name = 'final',
                           when = eventNumber(endpoint = 'os', n = 300,
                           arms = c('placebo', dropped)))
  }
}

dose_selection <- milestone(name = 'dose selection',
                            when = eventNumber(endpoint = 'pfs', n = 150),
                            action = action_at_dose_selection)
# dose_selection and final are then registered with the listener, in this
# order, so that the update in dose_selection is in effect before final
# is checked
listener <- listener()
listener$add_milestones(dose_selection, final)

## End(Not run)

Description

resize a trial with a greater sample size. This function is used to update the maximum sample size adaptively after sample size reassessment. Note that this function should be called within action functions. It is users' responsibility to ensure it and TrialSimulator has no way to track this.

This is a user-friendly wrapper of the member function of trial, i.e., Trials$resize(), which is used in vignettes. Users who are not familiar with the concept of classes may consider using this wrapper directly.

Usage

resize(trial, n_patients)

Arguments

Value

no return value, called for its side effect of updating trial.

Description

This is a helper function to explore parameters for endpoint generator, likely in an enrichment design.

Assume that the overall population in an arm is a mixture of two exponential distributions with medians median1 ($m_1$) and median2 ($m_2$). Given the proportion of the first component ($p_1$) and the overall median $m$, we have

$p_1 (1 - e^{-\log(2)m/m_1}) + (1 - p_1) (1 - e^{-\log(2)m/m_2}) = 1/2$

This function computes $m_2$ or $m$ given $p_1$ and $m_1$. These parameters can be used in custom random number generator to define exponential distributed endpoints.

Note that the math formula above may not be displayed correctly on a html page. You can read it with better format by running ?solveMixtureExponentialDistribution.

Usage

solveMixtureExponentialDistribution(
  weight1,
  median1,
  median2 = NULL,
  overall_median = NULL
)

Arguments

Value

a named vector of median2 or overall_median.

Examples

library(dplyr)

median2 <-
  solveMixtureExponentialDistribution(
    weight1 = .3,
    median1 = 10,
    overall_median = 8)

median2

n <- 1e6
ifelse(
  runif(n) < .3,
  rexp(n, rate=log(2)/10),
  rexp(n, rate=log(2)/median2)) %>%
  median() ## should be close to 8

overall_median <-
  solveMixtureExponentialDistribution(
    weight1 = .4,
    median1 = 12,
    median2 = 4)

overall_median

ifelse(
  runif(n) < .4,
  rexp(n, rate=log(2)/12),
  rexp(n, rate=log(2)/4)) %>%
  median() ## should be close to overall_median

Description

This function computes the rate parameters lambda in each of the time windows. lambda are natural parameters of piecewise exponential distribution, but in practice, users may define the distribution by specifying the survival probabilities at time points where event rates change.

This function returns a data frame, which can be used as input of the argument risk of the data generator PiecewiseConstantExponentialRNG.

Usage

solvePiecewiseConstantExponentialDistribution(surv_prob, times)

Arguments

Value

a data frame of two columns

end_time

End time for a constant event rate. The start time of the first time window is 0.

piecewise_risk

A constant event rate in the time window ending with end_time on the same row.

Examples

solvePiecewiseConstantExponentialDistribution(
  surv_prob = c(.9, .75, .64, .42, .28),
  times = c(.4, 1.2, 4, 5.5, 9)
)

Description

The illness-death model consists of three states, initial, progression, and death. It can be used to model the progression-free survival (PFS) and overall survival (OS) in clinical trial simulation. It models the correlation between PFS and OS without assumptions on latent status and copula. Also, it does not assume PFS and OS satisfy the proportional hazard assumption simultaneously. The three-state illness-death model ensures a nice property that PFS <= OS with probability one. However, it requires three hazard parameters under the homogeneous Markov assumption. In practice, hazard parameters are hard to specify intuitively especially when no trial data is available at the planning stage.

This function reparametrizes the illness-death model in term of three parameters, i.e. median of PFS, median of OS, and correlation between PFS and OS. The output of this function, which consists of the three hazard parameters, can be used to generate PFS and OS with desired property. It can be used with the built-in data generator CorrelatedPfsAndOs3() when defining endpoints in TrialSimulator.

For more information, refer to this vignette.

Usage

solveThreeStateModel(
  median_pfs,
  median_os,
  corr,
  h12 = seq(0.05, 0.2, length.out = 50)
)

Arguments

Value

a data frame with columns:

corr

target Peason's correlation coefficients.

h01

hazard from stable to progression.

h02

hazard from stable to death.

h12

hazard from progression to death.

error

absolute error between target correlation and correlation derived from h01, h02, and h12.

Examples

dat <- CorrelatedPfsAndOs3(1e6, h01 = .1, h02 = .05, h12 = .12)

cor(dat$pfs, dat$os) ## 0.65

median(dat$pfs) ## 4.62

median(dat$os) ## 9.61

## find h01, h02, h12 that can match to median_pfs, median_os and corr
## should be close to h01 = 0.10, h02 = 0.05, h12 = 0.12 when corr = 0.65
ret <- solveThreeStateModel(median_pfs = 4.6, median_os = 9.6,
                            corr = seq(.5, .7, length.out=5))
ret

Description

It assumes a uniform enrollment with constant rate in each of the time windows. This function can be used as the enroller when calling trial() to define a trial.

Usage

StaggeredRecruiter(n, accrual_rate)

Arguments

Details

StaggeredRecruiter is the only enroller accepted by trial(): a piecewise constant accrual rate is flexible enough to approximate realistic recruitment in practice, e.g., site ramp-up, steady accrual, and temporary pauses.

The returned enrollment times are deterministic, not random. Within a window of positive rate, patients enroll one by one with spacing 1/piecewise_rate; under a constant rate r, the k-th patient enrolls exactly at k / r. In particular, the first patient enrolls at 1/piecewise_rate rather than at time 0, and a milestone triggered by enrollment(n = n) occurs exactly at the time the planned cumulative accrual reaches n.

A window with piecewise_rate = 0 models a recruitment pause (a hold for safety review, a site not yet activated, a seasonal gap, etc.): no patient is enrolled in that window, and enrollment resumes after its end_time. Pauses may occur in the first window or span several consecutive windows; a leading pause defers the first enrollment accordingly.

A valid accrual_rate must satisfy all of the following:

• it is a data frame with columns end_time and piecewise_rate;

• end_time is positive and strictly increasing, and the last entry is Inf with a positive rate, so that the schedule can supply any number of patients (TrialSimulator may internally request more than the planned sample size, e.g., for adaptive resizing via resize());

• rates are non-negative and finite;

• a finite window with a positive rate must expect at least one patient, i.e., window length x piecewise_rate >= 1. A tiny positive rate meant as a pause is rejected with an error; use piecewise_rate = 0 for a true pause.

Value

a sorted numeric vector of n enrollment times.

Examples

## constant accrual of 25 patients/month: patient k enrolls at k / 25
accrual_rate <- data.frame(end_time = Inf, piecewise_rate = 25)

StaggeredRecruiter(30, accrual_rate)

## recruitment pause: 30/mo through month 12, paused during months 12-18,
## then 30/mo again. Monthly counts show months 13-17 are empty and
## enrollment resumes at the end of the pause (month 18).
accrual_rate <- data.frame(
  end_time = c(12, 18, Inf),
  piecewise_rate = c(30, 0, 30)
)

enroll_time <- StaggeredRecruiter(400, accrual_rate)
table(ceiling(enroll_time))

## leading pause (first rate is 0): enrollment opens 3 months after study
## start, e.g., the first site is activated with a delay, then 30/mo
accrual_rate <- data.frame(
  end_time = c(3, Inf),
  piecewise_rate = c(0, 30)
)

StaggeredRecruiter(30, accrual_rate)

## approximate a linear ramp-up by monthly steps: accrual grows by 5/mo
## each month, from 5/mo up to 30/mo, then stays steady at 30/mo
accrual_rate <- data.frame(
  end_time = c(1:6, Inf),
  piecewise_rate = c(seq(5, 30, by = 5), 30)
)

enroll_time <- StaggeredRecruiter(200, accrual_rate)

## monthly enrolled counts show the ramp (5, 10, ..., 30) and the plateau (30)
table(ceiling(enroll_time))

Description

stop follow-up of a subset of enrolled patients at a specified time at or after the current milestone. Data of affected patients are censored (time-to-event endpoints) or set to missing (non-time-to-event endpoints with readout after the stopping time), as if those patients were no longer followed since then. This function can be used in adaptive designs; its application includes, but is not limited to, treatment discontinuation, early termination of follow-up for a sub-population, or enrichment design where follow-up of a de-selected sub-population is stopped after an interim analysis. It can also be called at a pre-specified milestone that splits a trial into cohorts, e.g., a milestone marking the last patient of the first cohort and the first patient of the second cohort. Such a milestone is usually event driven, so its time is unknown until the trial is simulated. Stopping follow-up of the earlier cohort at that milestone, or after a pre-specified, fixed additional_followup beyond it, makes statistics computed from the two cohorts independent, which facilitates tests requiring independence, e.g., combination tests.

Only patients who are enrolled by the time this function is called and satisfy the subset conditions in ... (if any) are affected. Patients enrolled afterwards are followed as usual.

Note that this function should only be called within action functions of milestones. It is users' responsibility to ensure that and TrialSimulator has no way to track it. Calling it before any milestone has been triggered is an error.

This is a user-friendly wrapper of the member function of trial, i.e., Trials$stop_followup(), which is used in vignettes. Users who are not familiar with the concept of classes may consider using this wrapper directly.

Usage

stop_followup(trial, ..., additional_followup)

Arguments

Value

no return value, called for its side effect of updating trial.

Description

A minimum alternative to summarytools::dfSummary to avoid package dependency. This function is used to generate summary reports of endpoints and arms. No meant to be used by end users. However, users may find it helpful in their own applications if the interface is okay with them.

Usage

summarizeDataFrame(
  data,
  exclude_vars = NULL,
  tte_vars = NULL,
  event_vars = NULL,
  categorical_vars = NULL,
  title = "Summary",
  sub_title = ""
)

Arguments

Value

a data frame of summary

Examples

set.seed(123)

n <- 1000
data <- data.frame(
  age = rnorm(n, 65, 10),
  gender = sample(c('M', 'F', NA), n, replace = TRUE, prob = c(.4, .4, .2)),
  time_to_death = rexp(n, .01),
  death = rbinom(n, 1, .6),
  type = sample(LETTERS[1:8], n, replace = TRUE)
)

summarizeDataFrame(data, tte_vars = 'time_to_death', event_vars = 'death')

Description

Summary of Milestone Time from Simulated Trials

Usage

summarizeMilestoneTime(output)

Arguments

Value

A data frame of class milestone_time_summary. It comes with a plot method for visualization.

Examples

# a minimum, meaningful, and executable example,
# where a randomized trial with two arms is simulated and analyzed.

control <- arm(name = 'control arm')
active <- arm(name = 'active arm')

pfs_in_control <- endpoint(name = 'PFS', type = 'tte', generator = rexp, rate = log(2) / 5)
control$add_endpoints(pfs_in_control)

pfs_in_active <- endpoint(name = 'PFS', type = 'tte', generator = rexp, rate = log(2) / 6)
active$add_endpoints(pfs_in_active)

accrual_rate <- data.frame(end_time = c(10, Inf), piecewise_rate = c(30, 50))
trial <- trial(name = 'trial',
               n_patients = 1000,
               enroller = StaggeredRecruiter,
               accrual_rate = accrual_rate,
               dropout = rweibull, shape = 2, scale = 38,
               silent = TRUE)

trial$add_arms(sample_ratio = c(1, 1), control, active)

action_at_final <- function(trial){
  locked_data <- trial$get_locked_data('final analysis')
  fitLogrank(Surv(PFS, PFS_event) ~ arm, placebo = 'control arm',
             data = locked_data, alternative = 'less')
  invisible(NULL)
}

final <- milestone(name = 'final analysis',
                   action = action_at_final,
                   when = eventNumber(endpoint = 'PFS', n = 300))

listener <- listener(silent = TRUE)
listener$add_milestones(final)

controller <- controller(trial, listener)
controller$run(n = 10, plot_event = FALSE, silent = TRUE)

output <- controller$get_output()
time <- summarizeMilestoneTime(output)
time

plot(time)

Description

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

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$add_arms(sample_ratio = c(1, 2), placebo, active)

## updated information after arms are registered
trial

Description

Create a class of trial.

Public methods in this R6 class are used in developing this package. Thus, we have to export the whole R6 class which exposures all public methods. However, only the public methods in the sections below are useful to end users, and users are encouraged to restrict themselves to them. The remaining public methods are internal machinery of the package and should not be called directly (see the last section).

Adaptation methods. The following methods adapt an ongoing trial and should be called within action functions of milestones. Each of them has a user-friendly wrapper of the same name, e.g., resize(trial, ...) for trial$resize(...).

• $resize() set maximum sample size of a trial. This function can be used to increase sample size under adaptive designs (e.g., sample size reassessment).

• $remove_arms() drop arms from a trial. This function can be used in adaptive designs, e.g., dose selection, enrichment design, etc.

• $update_sample_ratio() change sample ratio of arm. This function can be used under adaptive designs, e.g., response-adaptive design, etc.

• $update_generator() change endpoint generator of arm. This function can be used in enrichment design.

• $add_arms() add arms to a trial. This function is used to add arms to a newly defined trial, or add arms under adaptive design, e.g., dose-ranging, etc.

• $crossover() apply a milestone-triggered crossover to eligible patients in the trial. Called inside a milestone action; only alters patients' post-switch endpoint values and leaves already-observed data intact.

• $stop_followup() stop follow-up of a subset of enrolled patients at or after a milestone. Their data are censored (time-to-event endpoints) or set to missing (non-time-to-event endpoints) accordingly. This function can be used in adaptive designs, e.g., to simulate treatment discontinuation, early termination of follow-up for a sub-population, or enrichment design where follow-up of a de-selected sub-population is stopped after an interim analysis. It can also stop follow-up of an earlier cohort at a pre-specified, event-driven milestone (e.g., the last patient of the first cohort), optionally with a fixed additional follow-up beyond it, making statistics of the cohorts independent to facilitate, e.g., combination tests.

• $update_accrual_rate() update the accrual rate of the recruitment curve at a milestone, e.g., to revise or pause recruitment after dose selection or enrichment. end_time of the new accrual rate is measured from the milestone; patients not yet enrolled are re-planned and re-randomized under the new schedule.

• $update_milestone() update the trigger condition and/or the action of a not-yet-triggered milestone. The update takes effect right after the current action function returns.

Methods callable within action functions. In addition to the adaptation methods above, users can call the following methods within action functions to access and manipulate data, to query the current status of a trial, and to carry out statistical testing.

Data access and manipulation:

• $get_locked_data() request for data snapshot at a milestone. Calling this function is recommended as the first action in any action function as long as trial data is needed in statistical analysis or decision making.

• $save() save intermediate result for simulation summary. Results across multiple replicates of simulation are saved, which can be retrieved by calling get_output() anytime.

• $bind() row bind and save intermediate results across milestones if those results are data frames of similar formats. The life cycle of the save results is within a single replicate of simulation and is reset to NULL in next simulated trial. Saved results can be retrieved by calling get() anytime.

• $save_custom_data() save intermediate results of any format. The life cycle of the saved result is within a single replicate of simulation and is cleared before the next simulated trial. Saved results can be retrieved by calling get() anytime.

• $get() retrieve intermediate results saved by calling functions save_custom_data() or bind().

• $get_global_data() retrieve read-only data registered through the global_data argument of trial(), e.g., design parameters or a template object of a testing procedure, which is available in every replicate of a simulation. R6 objects are returned as independent deep clones so the registered template is never changed.

• $get_output() retrieve intermediate results saved by calling function save().