Skip to contents

Simulate dose-finding trials with covariates

sim_covariate_jointBLRM.Rd

Simulates dose-finding trials with up to six parallel monotherapy or two-drug combination therapy trials modeled together in a joint BLRM. The function assumes that two different compounds are involved, compounds 1 and 2 (and their combination). Up to two monotherapy trials for each compound can be actively simulated, and additionally two combination therapy trials. Additionally, for each trial the binary covariate included in the model can be activated or deactivated.

A general introduction to the use of the simulation functions provided in this package can be found in the introduction vignette:vignette("intro_jointBLRM", package = "decider").

Note that the function sim_covariate_jointBLRM() uses the foreach framework to allow parallelized simulations. For this, a parallel backend needs to be registered by the user. A basic example of this is available in the following vignette: vignette("parallelization_jointBLRM", package = "decider").

Please refer to scenario_covariate_jointBLRM() for details on the model specification and sim_jointBLRM() for details on most of the arguments used by the function. Note that function sim_covariate_jointBLRM() uses to a large extent the same arguments as sim_jointBLRM(). The additionally added arguments for handling of the binary covariate are two_sided1, two_sided2, prior.mu.covar, prior.tau.covar, and covar.[...], where [...] is one of the trial names, i.e. mono1.a, mono1.b, mono2.a, mono2.b, combi.a, and combi.b.

Usage

sim_covariate_jointBLRM(
   active.mono1.a = FALSE,
   active.mono1.b = FALSE,
   active.mono2.a = FALSE,
   active.mono2.b = FALSE,
   active.combi.a = FALSE,
   active.combi.b = FALSE,
   doses.mono1.a,
   doses.mono2.a,
   doses.mono1.b,
   doses.mono2.b,
   doses.combi.a,
   doses.combi.b,
   dose.ref1,
   dose.ref2,
   tox.mono1.a,
   tox.mono2.a,
   tox.combi.a,
   tox.mono1.b,
   tox.mono2.b,
   tox.combi.b,
   start.dose.mono1.a,
   start.dose.mono2.a,
   start.dose.mono1.b,
   start.dose.mono2.b,
   start.dose.combi.a1,
   start.dose.combi.a2,
   start.dose.combi.b1,
   start.dose.combi.b2,
   cohort.queue = rep( c(1,2,3,4,5,6), times= 100),
   historical.data = NULL,
   esc.rule = "ewoc",
   esc.comp.max=1,
   dosing.intervals = c(0.16, 0.33, 0.6),
   ewoc.threshold = 0.25,
   loss.weights = c(1, 0, 1, 2),
   dynamic.weights =  rbind(
       c(0.32, 0, 0.32, 0.36),
       c(0.29, 0, 0.31, 0.40),
       c(0.27, 0, 0.33, 0.40),
       c(0.20, 0, 0.30, 0.50)),
   prior.mu = list(
       mu_a1 = c(logit(0.33), 2),
       mu_b1 = c(0, 1),
       mu_a2 = c(logit(0.33), 2),
       mu_b2 = c(0, 1),
       mu_eta = c(0, 1.121)),
   prior.mu.covar = list(
       mu_g1 = c(0, 1),
       mu_g2 = c(0, 1)),
   prior.tau = list(
       tau_a1 = c(log(0.25), log(4)/1.96),
       tau_b1 = c(log(0.125), log(4)/1.96),
       tau_a2 = c(log(0.25), log(4)/1.96),
       tau_b2 = c(log(0.125), log(4)/1.96),
       tau_eta = c(log(0.125),log(4)/1.96)),
   prior.tau.covar = list(
       tau_g1 = c(log(0.125),log(4)/1.96),
       tau_g2 = c(log(0.125),log(4)/1.96)),
   saturating = FALSE,
   esc.step = NULL,
   esc.step.mono1.a = esc.step,
   esc.step.mono2.a = esc.step,
   esc.step.mono1.b = esc.step,
   esc.step.mono2.b = esc.step,
   esc.step.combi.a1 = esc.step,
   esc.step.combi.b1 = esc.step,
   esc.step.combi.a2 = esc.step,
   esc.step.combi.b2 = esc.step,
   esc.constrain = FALSE,
   esc.constrain.mono1.a=esc.constrain,
   esc.constrain.mono2.a=esc.constrain,
   esc.constrain.mono1.b=esc.constrain,
   esc.constrain.mono2.b=esc.constrain,
   esc.constrain.combi.a1=esc.constrain,
   esc.constrain.combi.b1=esc.constrain,
   esc.constrain.combi.a2=esc.constrain,
   esc.constrain.combi.b2=esc.constrain,
   cohort.size = c(3),
   cohort.size.mono1.a = cohort.size,
   cohort.size.mono1.b = cohort.size,
   cohort.size.mono2.a = cohort.size,
   cohort.size.mono2.b = cohort.size,
   cohort.size.combi.a = cohort.size,
   cohort.size.combi.b = cohort.size,
   cohort.prob = NULL,
   cohort.prob.mono1.a = cohort.prob,
   cohort.prob.mono1.b = cohort.prob,
   cohort.prob.mono2.a = cohort.prob,
   cohort.prob.mono2.b = cohort.prob,
   cohort.prob.combi.a = cohort.prob,
   cohort.prob.combi.b = cohort.prob,
   max.n = 42,
   max.n.mono1.a = max.n,
   max.n.mono1.b = max.n,
   max.n.mono2.a = max.n,
   max.n.mono2.b = max.n,
   max.n.combi.a = max.n,
   max.n.combi.b = max.n,
   mtd.decision = list(
       target.prob = 0.5,
       pat.at.mtd = 6,
       min.pat = 12,
       min.dlt = 1,
       rule = 2),
   mtd.decision.combi.a = mtd.decision,
   mtd.decision.combi.b = mtd.decision,
   mtd.decision.mono1.a = mtd.decision,
   mtd.decision.mono1.b = mtd.decision,
   mtd.decision.mono2.a = mtd.decision,
   mtd.decision.mono2.b = mtd.decision,
   mtd.enforce = FALSE,
   mtd.enforce.mono1.a = mtd.enforce,
   mtd.enforce.mono2.a = mtd.enforce,
   mtd.enforce.mono1.b = mtd.enforce,
   mtd.enforce.mono2.b = mtd.enforce,
   mtd.enforce.combi.a = mtd.enforce,
   mtd.enforce.combi.b = mtd.enforce,
   backfill.mono1.a = FALSE,
   backfill.mono1.b = FALSE,
   backfill.mono2.a = FALSE,
   backfill.mono2.b = FALSE,
   backfill.combi.a = FALSE,
   backfill.combi.b = FALSE,
   backfill.size = c(3),
   backfill.prob = NULL,
   backfill.size.mono1.a = backfill.size,
   backfill.size.mono1.b = backfill.size,
   backfill.size.mono2.a = backfill.size,
   backfill.size.mono2.b = backfill.size,
   backfill.size.combi.a = backfill.size,
   backfill.size.combi.b = backfill.size,
   backfill.prob.mono1.a = backfill.prob,
   backfill.prob.mono1.b = backfill.prob,
   backfill.prob.mono2.a = backfill.prob,
   backfill.prob.mono2.b = backfill.prob,
   backfill.prob.combi.a = backfill.prob,
   backfill.prob.combi.b = backfill.prob,
   backfill.start.mono1.a = NULL,
   backfill.start.mono1.b = NULL,
   backfill.start.mono2.a = NULL,
   backfill.start.mono2.b = NULL,
   backfill.start.combi.a1 = NULL,
   backfill.start.combi.a2 = NULL,
   backfill.start.combi.b1 = NULL,
   backfill.start.combi.b2 = NULL,
   two_sided1 = TRUE,
   two_sided2 = TRUE,
   covar.mono1.a = FALSE,
   covar.mono2.a = FALSE,
   covar.mono1.b = FALSE,
   covar.mono2.b = FALSE,
   covar.combi.a = FALSE,
   covar.combi.b = FALSE,
   n.studies = 1,
   seed = sample.int(.Machine$integer.max, 1),
   chains = 4,
   iter = 13500,
   warmup = 1000,
   adapt_delta = 0.8,
   max_treedepth = 15,
   refresh=0,
   file.name = NULL,
   path = NULL,
   monitor.path = NULL,
   working.path = NULL,
   clean.working.path = FALSE,
   output.sim.config =TRUE
)

Arguments

active.mono1.a, active.mono1.b, active.mono2.a, active.mono2.b, active.combi.a, active.combi.b

Logicals, default to FALSE. Refer to sim_jointBLRM() for details.

doses.mono1.a, doses.mono1.b, doses.mono2.a, doses.mono2.b

Numericals, one dimensional vectors with positive, strictly ascending entries. Refer to sim_jointBLRM() for details.

doses.combi.a, doses.combi.b

Numericals, two dimensional arrays with two rows, arbitrarily many columns, and positive entries. Refer to sim_jointBLRM() for details.

dose.ref1

Positive numerical value. Reference dose of compound 1.

dose.ref2

Positive numerical value. Reference dose of compound 2.

tox.mono1.a, tox.mono1.b, tox.mono2.a, tox.mono2.b

Numericals, one dimensional vectors with entries in \((0,1)\). Refer to sim_jointBLRM() for details.

tox.combi.a, tox.combi.b

Numericals, one dimensional vectors with entries in \((0,1)\). Refer to sim_jointBLRM() for details.

start.dose.mono1.a, start.dose.mono2.a, start.dose.mono1.b, start.dose.mono2.b

Positive numerical values that specify the starting dose for the simulated monotherapy trials. Refer to sim_jointBLRM() for details.

start.dose.combi.a1, start.dose.combi.a2, start.dose.combi.b1, start.dose.combi.b2

Positive numerical values that specify the starting dose for the simulated combination therapy trials. Refer to sim_jointBLRM() for details.

cohort.queue

Optional numerical or character vector that specifies the order or pattern in which cohorts are enrolled in the simulated trials. Refer to sim_jointBLRM() for details.

historical.data

Optional parameter that must be NULL (the default) or a named list that specifies the historical data to be included in the trial. Refer to sim_jointBLRM() for details, and to scenario_covariate_jointBLRM() for the required input format of historical data.

esc.rule

Optional character string, must have one of the following values: "ewoc", "ewoc.opt", "ewoc.max". Refer to sim_jointBLRM() for details.

esc.comp.max

Optional integer, must be either 1 (the default) or 2. Refer to sim_jointBLRM() for details.

dosing.intervals

Optional numeric vector with ascending entries between 0 and 1. Refer to sim_jointBLRM() for details.

ewoc.threshold

Optional numerical value between 0 and 1 (excluding the boundaries), defaults to 0.25. Refer to sim_jointBLRM() for details.

loss.weights

Optional numerical vector with four entries (which can be arbitrary numbers), the default is c(1,0,1,2). Refer to sim_jointBLRM() for details.

dynamic.weights

Optional numerical matrix with four rows and four columns, and arbitrary numbers as entries. Refer to sim_jointBLRM() for details.

prior.mu

Optional list that gives the prior distribution for the hyper means \(\mu\). Refer to sim_jointBLRM() for details.

prior.mu.covar

Optional named list that gives the prior distribution for the hyper-means of the additional parameters included in the joint BLRM to realize the binary covariate. Refer to scenario_covariate_jointBLRM() for details.

prior.tau

Optional list that gives the prior distribution for the between-trial heterogeneities (hyper SD) \(\tau\). Refer to sim_jointBLRM() for details.

prior.tau.covar

Optional named list that gives the prior distribution for the between-trial heterogeneities of the additional parameters included in the joint BLRM to realize the binary covariate. Refer to scenario_covariate_jointBLRM() for details.

saturating

Optional logical, defaults to FALSE. Refer to sim_jointBLRM() for details.

esc.step, esc.step.mono1.a, esc.step.mono2.a, esc.step.combi.a1, esc.step.combi.a2

Optional numerical values that specify the maximum factor of dose escalations that is demanded additionally to the selected escalation rule. Refer to sim_jointBLRM() for details.

esc.step.mono1.b, esc.step.mono2.b, esc.step.combi.b1, esc.step.combi.b2

Same as esc.step.[...].a (where [...] is mono1, mono2, or combi) but for the second potentially simulated trial (suffix .b) of the respective trial type.

esc.constrain, esc.constrain.mono1.a, esc.constrain.mono2.a

Optional logicals, default to FALSE. Refer to sim_jointBLRM() for details.

esc.constrain.mono1.b, esc.constrain.mono2.b, esc.constrain.combi.b1, esc.constrain.combi.b2

Same as esc.constrain.[...].a (where [...] is mono1, mono2, or combi) but for the second potentially simulated trial (suffix .b) of the respective trial type.

esc.constrain.combi.a1, esc.constrain.combi.a2

Optional logicals, default to FALSE. Refer to sim_jointBLRM() for details.

cohort.size, cohort.size.mono1.a, cohort.size.mono2.a, cohort.size.combi.a

Optional positive integer vectors that specify the available cohort sizes for simulated cohorts. Refer to sim_jointBLRM() for details.

cohort.size.mono1.b, cohort.size.mono2.b, cohort.size.combi.b

Same as cohort.size.[...].a (where [...] is mono1, mono2, or combi) but for the second potentially simulated trial (suffix .b) of the respective trial type.

cohort.prob, cohort.prob.mono1.a, cohort.prob.mono2.a, cohort.prob.combi.a

Optional positive numeric vectors with values between 0 and 1 that specify the probability for each of the available cohort sizes in the corresponding argument cohort.size.[...]. Refer to sim_jointBLRM() for details.

cohort.prob.mono1.b, cohort.prob.mono2.b, cohort.prob.combi.b

Same as cohort.prob.[...].a (where [...] is mono1, mono2, or combi) but for the second potentially simulated trial (suffix .b) of the respective trial type.

max.n, max.n.mono1.a, max.n.mono2.a, max.n.combi.a

Optional positive integer values that specify the maximum number of patients to be enrolled in simulated trials. Refer to sim_jointBLRM() for details.

max.n.mono1.b, max.n.mono2.b, max.n.combi.b

Same as max.n.[...].a (where [...] is mono1, mono2, or combi) but for the second potentially simulated trial (suffix .b) of the respective trial type.

mtd.decision, mtd.decision.mono1.a, mtd.decision.mono2.a, mtd.decision.combi.a

Optional named lists that specify the rules for MTD selection. Refer to sim_jointBLRM() for details.

mtd.decision.mono1.b, mtd.decision.mono2.b, mtd.decision.combi.b

Same as mtd.decision.[...].a (where [...] is mono1, mono2, or combi) but for the second potentially simulated trial (suffix .b) of the respective trial type.

mtd.enforce, mtd.enforce.mono1.a, mtd.enforce.mono2.a, mtd.enforce.combi.a

Optional logicals, default to FALSE. Refer to sim_jointBLRM() for details.

mtd.enforce.mono1.b, mtd.enforce.mono2.b, mtd.enforce.combi.b

Same as mtd.enforce.[...].a (where [...] is mono1, mono2, or combi) but for the second potentially simulated trial (suffix .b) of the respective trial type.

backfill.mono1.a, backfill.mono2.a, backfill.combi.a

Optional logicals, indicating whether back-fill cohorts are simulated for the trial.

backfill.mono1.b, backfill.mono2.b, backfill.combi.b

Same as backfill.[...].a (where [...] is mono1, mono2, or combi) but for the second potentially simulated trial (suffix .b) of the respective trial type.

backfill.size, backfill.size.mono1.a, backfill.size.mono2.a, backfill.size.combi.a

Optional numericals, provide the size of simulated back-fill cohorts. Interpreted in the same fashion as cohort.size.

backfill.prob, backfill.prob.mono1.a, backfill.prob.mono2.a, backfill.prob.combi.a

Optional numericals, provide the probabilities if multiple possible back-fill cohort sizes are given. Interpreted in the same fashion as cohort.prob.

backfill.size.mono1.b, backfill.size.mono2.b, backfill.size.combi.b

Same as backfill.size.[...].a (where [...] is mono1, mono2, or combi) but for the second potentially simulated trial (suffix .b) of the respective trial type.

backfill.prob.mono1.b, backfill.prob.mono2.b, backfill.prob.combi.b

Same as backfill.prob.[...].a (where [...] is mono1, mono2, or combi) but for the second potentially simulated trial (suffix .b) of the respective trial type.

backfill.start.mono1.a, backfill.start.mono2.a, backfill.start.combi.a1, backfill.start.combi.a2

Optional numericals. Specify the first dose on which back-fill cohorts are enrolled. If not provided, the lowest available dose will be assumed to be the starting point of back-fill cohorts in the respective trial.

backfill.start.mono1.b, backfill.start.mono2.b, backfill.start.combi.b1, backfill.start.combi.b2

Same as backfill.start.[...].a (where [...] is mono1, mono2, or combi) but for the second potentially simulated trial (suffix .b) of the respective trial type.

two_sided1

Optional logical, defaults to TRUE. Refer to scenario_covariate_jointBLRM() for details.

two_sided2

Optional logical, defaults to TRUE. Refer to scenario_covariate_jointBLRM() for details.

covar.mono1.a, covar.mono1.b, covar.mono2.a, covar.mono2.b, covar.combi.a, covar.combi.b

Optional logicals, default to FALSE. Specify whether the corresponding simulated trial has a value of 0 or 1 in the binary covariate. Set covar.[...]=TRUE when the trial shall have covariate 1. By default, all trials do not have the property indicated by the binary covariate. This is equivalent to a joint BLRM without covariate.

n.studies

Positive integer that specifies the number of studies to be simulated, defaults to 1. Refer to sim_jointBLRM() for details.

seed

Optional positive integer that specified the seed to be used for the simulation. Refer to sim_jointBLRM() for details.

chains

Optional positive integer that specifies the number of Markov chains to be used during MCMC sampling, defaults to 4. Refer to sim_jointBLRM() for details.

iter

Optional positive integer that specifies the total number of iterations per chain to be used during MCMC sampling, defaults to 13500. Refer to sim_jointBLRM() for details.

warmup

Optional positive integer that specifies the number of iterations per chain that are discarded from the total number of iterations, iter. Defaults to 1000. Refer to sim_jointBLRM() for details.

adapt_delta

Optional numerical that must be at least 0.6 and smaller than 1, defaults to 0.8. Refer to sim_jointBLRM() for details.

max_treedepth

Optional integer that must be at least 10, defaults to 15. Refer to sim_jointBLRM() for details.

refresh

Optional integer, defaults to 0. Refer to sim_jointBLRM() for details.

file.name

Optional character string that provides a name for potential output files. Refer to sim_jointBLRM() for details.

path

Optional character string that specifies the path to the output directory. Refer to sim_jointBLRM() for details.

monitor.path

Optional character string that specifies a path to an additional output directory for monitoring simulation progress. Refer to sim_jointBLRM() for details.

working.path

Optional character string that specifies a path to a directory for temporary results. Refer to sim_jointBLRM() for details.

clean.working.path

Optional logical, defaults to FALSE. Refer to sim_jointBLRM() for details.

output.sim.config

Optional logical that specifies whether the input parameters of the call to sim_jointBLRM() are added to the output list. Refer to sim_jointBLRM() for details.

Value

List that contains a number of metrics that summarize the results of the simulation for each simulated trial, and, depending on the specification, additional list entries that save the given input specification.

By default, the following list entries are generated for each simulated trial (where [...]

is the corresponding suffix of the trial):

  • ...$'results [...]'
    Overview of number of MTDs per dosing interval (under, target, over), and number of trials that stopped without finding an MTD, either due to the stopping rule (when EWOC-based escalation is used) or due to reaching the maximal patient number.

  • ...$'summary [...]'
    Summary statistics (mean, median, min, max, 2.5% and 97.5% quantile) of the number of patients, patients per dosing interval, DLTs, and DLTs per dosing interval.

  • ...$'MTDs [...]'
    Number of MTDs per dose level and their assumed DLT rates.

  • ...$'#pat [...]'
    Mean, median, minimum and maximum number of patients enrolled at each dose level.

Additionally, if output.sim.config is active, the list will include the following entries:

  • ...$'historical.data'
    Only included when historical data was included in the simulations. Contains the specified cohorts from historical data.

  • ...$'prior'
    The prior distribution for the hyper-parameters that was used by the BLRM.

  • ...$'specifications'
    All other simulation specifications. Includes e. g. reference doses, decision rules, escalation steps, and the seed.

  • ...$'Stan options'
    Options given to Stan, such as the number of MCMC iterations and chains.

Details

The joint BLRM is defined according to (Neuenschwander et al., 2014 and 2016). It allows to perform Bayesian logistic regression to estimate the dose-toxicity relationship of two different monotherapies and combination therapy with these compounds in a joint model, which includes a hierarchical prior for robust borrowing across trials. Refer to the documentation of scenario_jointBLRM() for a detailed model description. Further, refer to the documentation of scenario_covariate_jointBLRM() for a description of the model including covariates.

References

Stan Development Team (2020). RStan: the R interface to Stan. R package version 2.21.2. https://mc-stan.org.

Neuenschwander, B., Branson, M., & Gsponer, T. (2008). Critical aspects of the Bayesian approach to phase I cancer trials. Statistics in medicine, 27(13), 2420-2439, doi:10.1002/sim.3230.

Neuenschwander, B., Matano, A., Tang, Z., Roychoudhury, S., Wandel, S., & Bailey, S. (2014). A Bayesian Industry Approach to Phase I Combination Trials in Oncology. In: Zhao. W & Yang, H. (editors). Statistical methods in drug combination studies. Chapman and Hall/CRC, 95-135, doi:10.1201/b17965.

Neuenschwander, B., Roychoudhury, S., & Schmidli, H. (2016). On the use of co-data in clinical trials. Statistics in Biopharmaceutical Research, 8(3), 345-354, doi:10.1080/19466315.2016.1174149.

Babb, J., Rogatko, A., & Zacks, S. (1998). Cancer phase I clinical trials: Efficient dose escalation with overdose control. Statistics in medicine 17(10), 1103-1120.

Zhou, H., Yuan, Y., & Nie, L. (2018). Accuracy, safety, and reliability of novel phase I designs. Clinical Cancer Research, 24(21), 5483-5484 <doi: 10.1158/1078-0432.ccr-18-0168>.

See also

scenario_jointBLRM(), rstan::sampling(), rstan-package, scenario_covariate_jointBLRM(),