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.

Usage

add_arms(trial, sample_ratio, ...)

Arguments

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

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()

• $print()

Methods

Public methods

• Arms$new()

• Arms$add_endpoints()

• Arms$get_name()

• Arms$get_number_endpoints()

• 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()

return name of arm.

Usage

Arms$get_name()

Method get_number_endpoints()

return number of endpoints in the arm.

Usage

Arms$get_number_endpoints()

Method has_endpoint()

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()

return name of endpoints registered to the arm.

Usage

Arms$get_endpoints_name()

Method update_endpoint_generator()

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

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,
               duration = 40,
               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()

• $get_output()

• $reset()

Methods

Public methods

• Controllers$new()

• Controllers$get_listener()

• Controllers$get_trial()

• Controllers$mute()

• Controllers$reset()

• Controllers$get_output()

• Controllers$run()

• Controllers$clone()

Method new()

initialize a controller of the trial

Usage

Controllers$new(trial, listener)

Arguments

Method get_listener()

return listener in a controller.

Usage

Controllers$get_listener()

Method get_trial()

return trial in a controller.

Usage

Controllers$get_trial()

Method mute()

mute all messages (not including warnings).

Usage

Controllers$mute()

Arguments

Method reset()

reset the trial and listener registered to the controller before running additional replicate of simulation. This is usually done between two calls of controller$run().

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.

Usage

Controllers$run(
  n = 1,
  n_workers = 1,
  plot_event = TRUE,
  silent = FALSE,
  dry_run = 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

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()), modifying trial duration (set_duration()), 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

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()

Methods

Public methods

• Endpoints$new()

• Endpoints$test_generator()

• Endpoints$get_generator()

• Endpoints$update_generator()

• Endpoints$get_readout()

• Endpoints$get_uid()

• Endpoints$get_name()

• Endpoints$get_type()

• 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()

update endpoint generator

Usage

Endpoints$update_generator(generator, ...)

Arguments

Method get_readout()

return readout function

Usage

Endpoints$get_readout()

Method get_uid()

return uid

Usage

Endpoints$get_uid()

Method get_name()

return endpoints' name

Usage

Endpoints$get_name()

Method get_type()

return endpoints' type

Usage

Endpoints$get_type()

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 three 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 three 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 three 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 statistics of log hazard ratios.

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

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

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.

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

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()

Methods

Public methods

• Listeners$new()

• Listeners$add_milestones()

• Listeners$get_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_milestones()

return registered milestones

Usage

Listeners$get_milestones(milestone_name = NULL)

Arguments

Method get_milestone_names()

return names of registered milestones

Usage

Listeners$get_milestone_names()

Method monitor()

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

Usage

Listeners$monitor(trial, dry_run)

Arguments

Method mute()

mute all messages (not including warnings)

Usage

Listeners$mute(silent)

Arguments

Method reset()

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

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.

Methods

Public methods

• Milestones$new()

• Milestones$get_name()

• Milestones$get_type()

• Milestones$get_trigger_condition()

• Milestones$get_action()

• Milestones$set_dry_run()

• Milestones$execute_action()

• 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()

return name of milestone

Usage

Milestones$get_name()

Method get_type()

return type(s) of milestone

Usage

Milestones$get_type()

Method get_trigger_condition()

return trigger_condition function

Usage

Milestones$get_trigger_condition()

Method get_action()

return action function

Usage

Milestones$get_action()

Method set_dry_run()

set if dry run should be carried out for the milestone. For more details, refer to Controller::run.

Usage

Milestones$set_dry_run(dry_run)

Arguments

Method execute_action()

execute action function

Usage

Milestones$execute_action(trial)

Arguments

Method get_trigger_status()

return trigger status

Usage

Milestones$get_trigger_status()

Method reset()

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.

Usage

Milestones$reset()

Method trigger_milestone()

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()

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

Description

Plot result of three-state illness-death model

Usage

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

Arguments

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

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

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.

Methods

Public methods

• Regimens$new()

• Regimens$get_number_treatment_allocator()

• Regimens$get_treatment_allocator()

• Regimens$get_number_time_selector()

• Regimens$get_time_selector()

• Regimens$get_number_data_modifier()

• 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()

return number of treatment allocators for regimen

Usage

Regimens$get_number_treatment_allocator()

Method get_treatment_allocator()

return user-defined new treatment for a patient

Usage

Regimens$get_treatment_allocator(index = NULL)

Arguments

Method get_number_time_selector()

return number of time selector for regimen

Usage

Regimens$get_number_time_selector()

Method get_time_selector()

return user-defined time selector

Usage

Regimens$get_time_selector(index = NULL)

Arguments

Method get_number_data_modifier()

return number of data modifier for regimen

Usage

Regimens$get_number_data_modifier()

Method get_data_modifier()

return user-defined endpoint data modifier

Usage

Regimens$get_data_modifier(index = NULL)

Arguments

Method get_treatment_allocator_args()

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

Usage

Regimens$get_treatment_allocator_args(index)

Arguments

Method get_time_selector_args()

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

Usage

Regimens$get_time_selector_args(index)

Arguments

Method get_data_modifier_args()

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

Usage

Regimens$get_data_modifier_args(index)

Arguments

Method get_earliest_crossover_calendar_time()

return the earliest crossover calendar time of triplet(s)

Usage

Regimens$get_earliest_crossover_calendar_time(index = NULL)

Arguments

Method append_triplet()

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. In addition, data of the removed arms are censored or truncated by the time of arm removal.

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.

Usage

remove_arms(trial, arms_name)

Arguments

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

Description

set trial duration in an adaptive designed trial. New duration must be longer than the old one. All patients enrolled before resetting the duration are truncated (non-TTE endpoints) or censored (TTE endpoints) at the original duration. This helps maintain proper type I error or family-wise error rate and control multiplicity when conducting testing statistics. For more details of why this is necessary, please refer to Jorgens et al. 2019.

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$set_duration(), which is used in vignettes. Users who are not familiar with the concept of classes may consider using this wrapper directly.

Usage

set_duration(trial, duration)

Arguments

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

Examples

accrual_rate <- data.frame(
  end_time = c(12, 13:17, Inf),
  piecewise_rate = c(15, 15 + 6 * (1:5), 45)
)

StaggeredRecruiter(30, accrual_rate)

accrual_rate <- data.frame(
  end_time = c(3, 4, 5, 8, Inf),
  piecewise_rate = c(1, 2, 2, 3, 4)
)

StaggeredRecruiter(30, accrual_rate)

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,
               duration = 40,
               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/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,
  dropout = NULL,
  stratification_factors = NULL,
  silent = FALSE,
  ...
)

Arguments

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 time follows an exponential distribution, with median 5
trial <- trial(
  name = 'Trial-3415', n_patients = 100,
  seed = 31415926, duration = 100,
  enroller = rexp, rate = log(2) / 5)

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 list below are useful to end users.

• $set_duration() set duration of a trial. This function can be used to extend duration under adaptive designs.

• $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.

• $add_regimen() register a regimen object to a trial. Must be called before $add_arms(). Applied at enrollment.

• $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.

• $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 reset to NULL in 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_output() retrieve intermediate results saved by calling function save().

• $dunnettTest() perform Dunnett's test.

• $closedTest() perform combination test based on Dunnett's test.

Methods

Public methods

• Trials$new()

• Trials$get_trial_data()

• Trials$get_duration()

• Trials$set_duration()

• Trials$set_enroller()

• Trials$get_enroller()

• Trials$set_dropout()

• Trials$get_dropout()

• Trials$roll_back()

• Trials$remove_arms()

• Trials$update_sample_ratio()

• Trials$update_generator()

• Trials$resize()

• Trials$add_arms()

• Trials$add_regimen()

• Trials$get_regimen()

• Trials$has_regimen()

• Trials$crossover()

• Trials$get_name()

• Trials$get_description()

• Trials$get_arms()

• Trials$get_arms_name()

• Trials$get_number_arms()

• Trials$has_arm()

• Trials$get_an_arm()

• Trials$get_sample_ratio()

• Trials$get_number_patients()

• Trials$get_number_enrolled_patients()

• Trials$get_number_unenrolled_patients()

• Trials$get_stratum_queue()

• Trials$get_randomization_queue()

• Trials$get_enroll_time()

• Trials$enroll_patients()

• Trials$set_current_time()

• Trials$get_current_time()

• Trials$get_event_tables()

• Trials$get_data_lock_time_by_event_number()

• Trials$get_data_lock_time_by_enrollment()

• Trials$get_data_lock_time_by_calendar_time()

• Trials$get_locked_data()

• Trials$get_locked_data_name()

• Trials$get_event_number()

• Trials$save_milestone_time()

• Trials$get_milestone_time()

• Trials$lock_data()

• Trials$event_plot()

• Trials$censor_trial_data()

• Trials$save()

• Trials$bind()

• Trials$save_custom_data()

• Trials$get_custom_data()

• Trials$get()

• Trials$get_output()

• Trials$mute()

• Trials$tidy_output()

• Trials$independentIncrement()

• Trials$dunnettTest()

• Trials$closedTest()

• Trials$get_seed()

• Trials$print()

• Trials$get_snapshot_copy()

• Trials$make_snapshot()

• Trials$make_arms_snapshot()

• Trials$reset()

• Trials$set_arm_added_time()

• Trials$get_arm_added_time()

• Trials$set_arm_removal_time()

• Trials$get_arm_removal_time()

• Trials$get_stratification_factors()

• Trials$has_stratification_factors()

• Trials$clone()

Method new()

initialize a trial

Usage

Trials$new(
  name,
  n_patients,
  duration,
  description = name,
  seed = NULL,
  enroller,
  dropout = NULL,
  stratification_factors = NULL,
  silent = FALSE,
  ...
)

Arguments

Method get_trial_data()

return trial data of enrolled patients at the time of this function is called

Usage

Trials$get_trial_data()

Method get_duration()

return maximum duration of a trial

Usage

Trials$get_duration()

Method set_duration()

set trial duration in an adaptive designed trial. All patients enrolled before resetting the duration are truncated (non-tte endpoints) or censored (tte endpoints) at the original duration. Remaining patients are re-randomized. New duration must be longer than the old one.

Usage

Trials$set_duration(duration)

Arguments

Method set_enroller()

set recruitment curve when initialize a trial.

Usage

Trials$set_enroller(func, ...)

Arguments