Package {simFastBOIN}


Type: Package
Title: Fast Simulation of Bayesian Optimal Interval Designs for Phase I and Phase I/II Trials
Version: 2.2.0
Date: 2026-11-20
Description: Design and evaluate phase I dose-finding trials that use the Bayesian optimal interval (BOIN) design of Liu and Yuan (2015) <doi:10.1111/rssc.12089>. Functions are provided to tabulate the decision boundaries, to simulate trials, to estimate the dose-toxicity curve under a monotonicity constraint and to select the maximum tolerated dose. The simulation engine is written in C++ and draws one random variate per patient in enrollment order, which reproduces the reference implementation in the 'BOIN' package trial by trial for a given seed. The traditional 3+3 design is provided as a comparator, with operating characteristics obtained in closed form rather than by simulation. For toxicity that is observed late, the time-to-event BOIN design is provided with the two estimators of Yuan and colleagues (2018) <doi:10.1158/1078-0432.CCR-18-0246> and Lin and Yuan (2020) <doi:10.1093/biostatistics/kxz007>. Patients who arrive while the dose escalation waits can be backfilled to lower doses with the designs of Zhao and colleagues (2024) <doi:10.1158/1078-0432.CCR-23-2585> and Chen and colleagues (2026) <doi:10.1007/s43441-026-00994-0>, the latter with the suspension rules of Chen and colleagues (2025) <doi:10.1158/1078-0432.CCR-24-3669>. Trials of two drugs given together are handled by the drug-combination design of Lin and Yin (2017) <doi:10.1177/0962280215594494>. The optimal biological dose, which weighs the response against the toxicity, is found with the BOIN-ET design of Takeda and colleagues (2018) <doi:10.1002/pst.1864>, with the estimators and selection rules of the 'boinet' package, its time-to-event version (Takeda and colleagues, 2020) <doi:10.1002/pst.1995> and its backfill version (Takeda and colleagues, 2025) <doi:10.1002/pst.2470>, and with the BOIN12 design of Lin and colleagues (2020) <doi:10.1200/PO.20.00257>, which weighs them by a utility, and its time-to-event version (Zhou and colleagues, 2022) <doi:10.1002/sim.9337>. For two drugs given together, the optimal dose combination is found with the Comb-BOIN12 design of Lu and colleagues (2025) <doi:10.1080/19466315.2024.2370403>, also in its time-to-event version, and the BOIN-ETC design of Kakizume and colleagues (2024) <doi:10.1177/09622802241236936>. The titration of the BOIN design can be limited to the lowest doses, as in the accelerated design of Kojima and colleagues (2024) <doi:10.1007/s43441-024-00692-9>. The operating characteristics of several designs can be tabulated and plotted side by side.
License: MIT + file LICENSE
Encoding: UTF-8
Depends: R (≥ 3.5.0)
Imports: Iso, Rcpp (≥ 1.0.0), stats, utils
LinkingTo: Rcpp
Suggests: BOIN, bfboinet, boinet, ggplot2 (≥ 3.4.0), knitr, mfp, rmarkdown, spelling, testthat (≥ 3.0.0)
Language: en-US
URL: https://gosukehommaex.github.io/simFastBOIN/, https://github.com/gosukehommaEX/simFastBOIN
BugReports: https://github.com/gosukehommaEX/simFastBOIN/issues
Config/testthat/edition: 3
VignetteBuilder: knitr
Config/roxygen2/version: 8.0.0
NeedsCompilation: yes
Packaged: 2026-11-20 09:43:17 UTC; i_lik
Author: Gosuke Homma ORCID iD [aut, cre]
Maintainer: Gosuke Homma <my.name.is.gosuke@gmail.com>
Repository: CRAN
Date/Publication: 2026-11-20 14:30:15 UTC

simFastBOIN: Fast Simulation of Bayesian Optimal Interval Designs

Description

Tools for designing and evaluating phase I dose-finding trials that use the Bayesian optimal interval (BOIN) design of Liu and Yuan (2015). The simulation engine is written in C++ and reproduces the reference implementation in the BOIN package exactly, including the order in which random variates are consumed, so that results obtained with the same seed agree to the last trial.

Design tools

boin_lambda

Escalation and de-escalation interval boundaries.

boin_p_tox

The toxic threshold giving a required de-escalation boundary.

boin_boundary

Integer decision boundaries as a function of sample size.

boin_decision_table

Decision table indexed by DLTs and patients, with print and plot methods.

boin_stopping_table

Safety stopping boundary as a two-row table.

tite_boin_decision_table

Decision table of the time-to-event BOIN design, which treats new patients while earlier DLT data are pending, with print and plot methods.

Simulation tools

sim_boin

Operating characteristics for one scenario.

sim_boin_multi

Operating characteristics for several scenarios.

boin_simulate

Raw trial data from the simulation engine.

boin_isotonic

Isotonic estimates of the DLT probability.

boin_select_mtd

MTD selection from completed trials.

sim_tite_boin

Operating characteristics of the time-to-event BOIN design for one scenario, with trial duration and suspensions of accrual.

sim_tite_boin_multi

The same for several scenarios.

tite_boin_simulate

Raw trial data from the time-to-event BOIN engine, with patients arriving over time and DLTs observed late.

Backfilling

sim_bf_boin

Operating characteristics of the BOIN design with backfilling (BF-BOIN) for one scenario of DLT and response probabilities.

sim_bf_boin_multi

The same for several scenarios.

bf_boin_simulate

Raw trial data from the BF-BOIN engine, with backfilled patients and responses.

sim_be_boin

Operating characteristics of BE-BOIN, which combines backfilling with the time-to-event BOIN design, for one scenario.

sim_be_boin_multi

The same for several scenarios.

be_boin_simulate

Raw trial data from the BE-BOIN engine.

Drug combinations

sim_comb_boin

Operating characteristics of the BOIN drug-combination design of Lin and Yin (2017) for one matrix of DLT probabilities.

sim_comb_boin_multi

The same for several matrices.

comb_boin_simulate

Raw trial data from the drug-combination engine.

comb_boin_select_mtd

Selection of the MTD combination from completed trials.

comb_boin_next

The combination for the next cohort of a trial in progress, with print and plot methods.

Optimal biological dose (BOIN-ET)

boin_et_boundary

Boundaries of the BOIN-ET design of Takeda, Taguri and Morita (2018), which decides from both the DLT and the response.

boin_et_decision_table

Decision table indexed by DLTs and responses, with a print method.

sim_boin_et

Operating characteristics of BOIN-ET for one scenario of DLT and response probabilities, with the selection of the optimal biological dose (OBD).

sim_boin_et_multi

The same for several scenarios.

boin_et_simulate

Raw trial data from the BOIN-ET engine.

boin_et_select_obd

Selection of the OBD from completed trials, with the estimators and selection rules of the 'boinet' package.

sim_tite_boin_et

Operating characteristics of the time-to-event TITE-BOIN-ET design of Takeda, Morita and Taguri (2020).

sim_tite_boin_et_multi

The same for several scenarios.

tite_boin_et_simulate

Raw trial data from the TITE-BOIN-ET engine.

sim_bf_boin_et

Operating characteristics of the backfill BF-BOIN-ET design of Takeda, Zhu and Hirakawa (2025).

sim_bf_boin_et_multi

The same for several scenarios.

Optimal biological dose (BOIN12 and TITE-BOIN12)

boin12_decision_table

Desirability scores of the BOIN12 design of Lin et al. (2020), indexed by patients, DLTs and responses.

sim_boin12

Operating characteristics of BOIN12 for one scenario of DLT and response probabilities, with the selection of the OBD.

sim_boin12_multi

The same for several scenarios.

boin12_simulate

Raw trial data from the BOIN12 engine.

boin12_select_obd

OBD selection from completed trials.

sim_tite_boin12

Operating characteristics of the time-to-event TITE-BOIN12 design of Zhou et al. (2022).

sim_tite_boin12_multi

The same for several scenarios.

tite_boin12_simulate

Raw trial data from the TITE-BOIN12 engine.

The 3+3 design

oc_3p3

Operating characteristics of the traditional 3+3 design, in closed form.

sim_3p3

The same design by simulation, as a check on the closed form.

decision_table_3p3

Decision table of the 3+3 design, with print and plot methods.

Tables and figures

oc_scenarios

True scenarios with the utilities and the true MTDs and OBDs, with print and plot methods.

oc_results

Results of several designs in one long table, with print and plot methods.

oc_compare

Several designs judged against the true doses, with print and plot methods.

Author(s)

Maintainer: Gosuke Homma my.name.is.gosuke@gmail.com (ORCID)

Authors:

References

Liu S. and Yuan, Y. (2015). Bayesian Optimal Interval Designs for Phase I Clinical Trials. Journal of the Royal Statistical Society: Series C, 64, 507-523.

Yan, F., Zhang, L., Zhou, Y., Pan, H., Liu, S. and Yuan, Y. (2020). BOIN: An R Package for Designing Single-Agent and Drug-Combination Dose-Finding Trials Using Bayesian Optimal Interval Designs. Journal of Statistical Software, 94(13), 1-32.

Yuan, Y., Lin, R., Li, D., Nie, L. and Warren, K. E. (2018). Time-to-Event Bayesian Optimal Interval Design to Accelerate Phase I Trials. Clinical Cancer Research, 24(20), 4921-4930.

Lin, R. and Yuan, Y. (2020). Time-to-Event Model-Assisted Designs for Dose-Finding Trials with Delayed Toxicity. Biostatistics, 21(4), 807-824.

Zhao, Y., Yuan, Y., Korn, E. L. and Freidlin, B. (2024). Backfilling Patients in Phase I Dose-Escalation Trials Using Bayesian Optimal Interval Design (BOIN). Clinical Cancer Research, 30(4), 673-679.

Chen, K., Zhao, Y., Takeda, K. and Yuan, Y. (2026). BE-BOIN: A Dose Optimization Design Accommodating Backfill and Late-Onset Toxicity. Therapeutic Innovation and Regulatory Science. doi:10.1007/s43441-026-00994-0

Lin, R. and Yin, G. (2017). Bayesian Optimal Interval Design for Dose Finding in Drug-Combination Trials. Statistical Methods in Medical Research, 26(5), 2155-2167.

Takeda, K., Taguri, M. and Morita, S. (2018). BOIN-ET: Bayesian optimal interval design for dose finding based on both efficacy and toxicity outcomes. Pharmaceutical Statistics, 17(4), 383-395. doi:10.1002/pst.1864

Takeda, K., Morita, S. and Taguri, M. (2020). TITE-BOIN-ET: Time-to-event Bayesian optimal interval design to accelerate dose-finding based on both efficacy and toxicity outcomes. Pharmaceutical Statistics, 19, 335-349. doi:10.1002/pst.1995

Takeda, K., Zhu, J. and Hirakawa, A. (2025). BF-BOIN-ET: A backfill Bayesian optimal interval design using efficacy and toxicity outcomes for dose optimization. Pharmaceutical Statistics, 24, e2470. doi:10.1002/pst.2470

Lin, R., Zhou, Y., Yan, F., Li, D. and Yuan, Y. (2020). BOIN12: Bayesian optimal interval phase I/II trial design for utility-based dose finding in immunotherapy and targeted therapies. JCO Precision Oncology, 4, 1393-1402. doi:10.1200/PO.20.00257

Zhou, Y., Lin, R., Lee, J. J., Li, D., Wang, L., Li, R. and Yuan, Y. (2022). TITE-BOIN12: A Bayesian phase I/II trial design to find the optimal biological dose with late-onset toxicity and efficacy. Statistics in Medicine, 41(11), 1918-1931. doi:10.1002/sim.9337

See Also

Useful links:


Coerce BOIN Decision Boundaries to a Data Frame

Description

Return the integer decision boundaries produced by boin_boundary as one row per sample size.

Usage

## S3 method for class 'boin_boundary'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

Arguments

x

An object of class boin_boundary.

row.names

Passed on for compatibility with the generic, normally unused.

optional

Passed on for compatibility with the generic, normally unused.

...

Further arguments, currently ignored.

Value

A data frame with columns n_pts, escalate_if_dlt_leq, deescalate_if_dlt_geq and eliminate_if_dlt_geq, plus stop_if_dlt_geq when the boundaries were built with extrasafe = TRUE.

Examples

bd <- boin_boundary(target = 0.30, max_n = 18)
as.data.frame(bd)[seq(3, 18, by = 3), ]


Simulate BE-BOIN Trials

Description

Run the BOIN design with backfilling and late-onset toxicity (BE-BOIN) of Chen et al. (2026) over many simulated trials. Dose escalation follows TITE-BOIN, which decides while some patients are still pending; patients who arrive while the escalation is suspended are backfilled to a lower dose that is safe and has shown a response. Every estimate imputes the pending patients, backfilled ones included. Return the patient, DLT, backfill and response counts at every dose together with the duration of each trial.

Usage

be_boin_simulate(
  target,
  p_true,
  p_resp,
  n_cohort,
  cohort_size,
  window,
  accrual_rate,
  n_cap = 12,
  backfill_dose = c("highest", "lowest"),
  conflict_dose = c("lowest", "highest"),
  no_slot = c("wait", "leave"),
  accrual = c("exponential", "uniform", "fixed"),
  dlt_time = c("weibull", "uniform"),
  late_fraction = 0.5,
  resp_window = window,
  resp_late_fraction = 0.5,
  resp_cor = 0,
  max_pending_ratio = 0.49,
  min_completed = 0,
  min_follow_up = 0.25,
  n_trials = 10000,
  start_dose = 1,
  n_earlystop = 18,
  p_saf = NULL,
  p_tox = NULL,
  cutoff_eli = 0.95,
  extrasafe = FALSE,
  offset = 0.05,
  n_earlystop_rule = c("with_stay", "simple"),
  seed = 123
)

Arguments

target

Numeric scalar. Target DLT probability, for example 0.25.

p_true

Numeric vector. True DLT probability at each dose level, in increasing dose order. The probability of a DLT within the assessment window.

p_resp

Numeric vector of the same length as p_true. True probability of a response within the response window at each dose. A response at or below a dose is what makes the dose eligible for backfilling.

n_cohort

Integer scalar. Number of cohorts in the dose escalation.

cohort_size

Integer scalar or vector. Number of patients per cohort of the dose escalation. A scalar is used for every cohort. A vector shorter than n_cohort is padded with its last element and a longer one is truncated.

window

Numeric scalar. Length of the DLT assessment window.

accrual_rate

Numeric scalar. Average number of patients arriving per unit of time, in the same unit as window.

n_cap

Integer scalar. A dose is no longer backfilled once this many patients, from the dose escalation and from backfilling together, have been treated at it. The dose escalation can still treat patients at the dose. Defaults to 12.

backfill_dose

Character scalar. Which dose receives a backfill patient when several are open: "highest" (the default, as in both articles) or "lowest".

conflict_dose

Character scalar. When the data of several backfilled doses conflict with those of the current dose, which of them anchors the pooled estimate: "lowest" (the default here, following Chen et al., 2026) or "highest" (the default of bf_boin_simulate, following Zhao et al., 2024).

no_slot

Character scalar. What happens to a patient who arrives when neither the dose escalation nor any backfill dose can take a patient: "wait" (the default), the patient waits and is treated as soon as one can, as in tite_boin_simulate; or "leave", the patient is turned away and the trial waits for the next arrival.

accrual

Character scalar. Distribution of the times between arrivals: "exponential" (the default) for a Poisson process, "uniform" for a uniform distribution on (0, 2 / accrual_rate), or "fixed" for arrivals exactly 1 / accrual_rate apart.

dlt_time

Character scalar. Distribution of the time to DLT within the window, and of the time to response within the response window: "weibull" (the default) or "uniform".

late_fraction

Numeric scalar strictly between 0 and 1. Share of the DLTs that occur in the second half of the assessment window under the Weibull distribution. Defaults to 0.5.

resp_window

Numeric scalar. Length of the window within which a response is observed. Defaults to window.

resp_late_fraction

Numeric scalar strictly between 0 and 1. Share of the responses that occur in the second half of the response window under the Weibull distribution. Defaults to 0.5.

resp_cor

Numeric scalar strictly between -1 and 1. Correlation of the Gaussian copula that links the DLT and the response of a patient; a positive value makes a response more likely in a patient with a DLT. Defaults to 0, independence.

max_pending_ratio

Numeric scalar greater than 0 and at most 1. Rule 1 of the design: the escalation is suspended when the proportion of pending patients at the current dose exceeds this value, unless the dose is de-escalated whatever their outcomes. Defaults to 0.49, which suspends when fewer than 51 percent have completed the assessment, as in Chen et al. (2026). See tite_boin_decision_table.

min_completed

Integer scalar. While some patients are pending, escalation requires at least this many patients with a completed assessment. Defaults to 0, which the design does not use. See tite_boin_decision_table.

min_follow_up

Numeric scalar between 0 and 1. Rule 2 of the design: escalation requires every pending patient at the current dose to have been followed for at least this fraction of the window. Defaults to 0.25, as in Chen et al. (2026). See tite_boin_decision_table.

n_trials

Integer scalar. Number of trials to simulate. Defaults to 10000.

start_dose

Integer scalar. Dose level for the first cohort. Defaults to 1.

n_earlystop

Integer scalar. The trial stops once this many patients, backfilled ones included, have been treated at the current dose and the design would stay there. Defaults to 18.

p_saf

Numeric scalar. Highest DLT probability deemed subtherapeutic. Defaults to 0.6 * target.

p_tox

Numeric scalar. Lowest DLT probability deemed overly toxic. Defaults to 1.4 * target.

cutoff_eli

Numeric scalar. Posterior probability cutoff for dose elimination. Defaults to 0.95.

extrasafe

Logical scalar. Apply the stricter safety stopping rule at the lowest dose. Defaults to FALSE.

offset

Numeric scalar between 0 and 0.5. Amount by which cutoff_eli is relaxed for the safety stopping rule. Defaults to 0.05.

n_earlystop_rule

Character scalar, either "with_stay" or "simple". See boin_simulate.

seed

Integer scalar or NULL. Random seed. When NULL the current state of the random number generator is used. The state of the calling session is restored on exit. Defaults to 123.

Details

Dose escalation. The dose for a cohort is decided when its first patient arrives, with the rules of tite_boin_decision_table for method = "imputation" and the suspension rules max_pending_ratio and min_follow_up; every patient at the current dose counts, backfilled ones included. A suspension lasts until a decision can be taken again, as in tite_boin_simulate. Elimination counts every treated patient, the pending ones as without DLT, and is checked at every dose.

Estimates. The DLT rate at a dose is the single mean imputation estimate of TITE-BOIN, equation (1) of Chen et al. (2026), and the rate pooled over several doses adds up the observed and imputed DLTs of each dose, each imputed with its own posterior mean, and divides by the number of treated patients, equation (2). Both enter the opening and closing of backfill doses and the resolution of conflicts, which otherwise follow bf_boin_simulate. The categories of a backfilled dose for the conflicts compare its estimate with the escalation and de-escalation boundaries directly.

End of the trial, arrivals and random numbers are as in bf_boin_simulate. When no dose is ever opened for backfilling, for example with every p_resp equal to 0, and with no_slot = "wait", the trials are identical to those of tite_boin_simulate with method = "imputation", the same suspension rules and the same seed.

Chen et al. (2026) report their operating characteristics for scenarios that are given only as figures, so they cannot be reproduced. The decision table of their supplementary materials is reproduced by tite_boin_decision_table, and their trial example is replayed patient by patient in the tests of the package.

Value

An object of class c("be_boin_trials", "backfill_trials"), with the components described in bf_boin_simulate.

References

Chen, K., Zhao, Y., Takeda, K. and Yuan, Y. (2026). BE-BOIN: A Dose Optimization Design Accommodating Backfill and Late-Onset Toxicity. Therapeutic Innovation and Regulatory Science. doi:10.1007/s43441-026-00994-0

Chen, K., Chen, T.-Y., Zhang, Y., Lin, R. and Yuan, Y. (2025). Practical Considerations for Using the TITE-BOIN Design to Handle Late-Onset Toxicity or Fast Accrual in Phase I Trials. Clinical Cancer Research, 31(13), 2573-2580.

Zhao, Y., Yuan, Y., Korn, E. L. and Freidlin, B. (2024). Backfilling Patients in Phase I Dose-Escalation Trials Using Bayesian Optimal Interval Design (BOIN). Clinical Cancer Research, 30(4), 673-679.

See Also

bf_boin_simulate, tite_boin_simulate

Examples

# A three month window with two patients a month
trials <- be_boin_simulate(
  target = 0.25,
  p_true = c(0.04, 0.12, 0.25, 0.43, 0.63),
  p_resp = c(0.10, 0.20, 0.30, 0.45, 0.58),
  n_cohort = 10,
  cohort_size = 3,
  window = 3,
  accrual_rate = 2,
  n_earlystop = 9,
  n_trials = 200,
  seed = 123
)
trials

summary(trials$duration)


Simulate BF-BOIN Trials

Description

Run the BOIN design with backfilling (BF-BOIN) of Zhao et al. (2024) over many simulated trials. Dose escalation proceeds in fully staggered cohorts with the BOIN decision table; patients who arrive while the escalation waits for the DLT assessment of its current cohort are backfilled to a lower dose that is safe and has shown a response. Return the patient, DLT, backfill and response counts at every dose together with the duration of each trial.

Usage

bf_boin_simulate(
  target,
  p_true,
  p_resp,
  n_cohort,
  cohort_size,
  window,
  accrual_rate,
  n_cap = 12,
  backfill_dose = c("highest", "lowest"),
  conflict_dose = c("highest", "lowest"),
  no_slot = c("wait", "leave"),
  accrual = c("exponential", "uniform", "fixed"),
  dlt_time = c("weibull", "uniform"),
  late_fraction = 0.5,
  resp_window = window,
  resp_late_fraction = 0.5,
  resp_cor = 0,
  n_trials = 10000,
  start_dose = 1,
  n_earlystop = 18,
  p_saf = NULL,
  p_tox = NULL,
  cutoff_eli = 0.95,
  extrasafe = FALSE,
  offset = 0.05,
  stay_on_1_of_3 = FALSE,
  n_earlystop_rule = c("with_stay", "simple"),
  seed = 123
)

Arguments

target

Numeric scalar. Target DLT probability, for example 0.25.

p_true

Numeric vector. True DLT probability at each dose level, in increasing dose order. The probability of a DLT within the assessment window.

p_resp

Numeric vector of the same length as p_true. True probability of a response within the response window at each dose. A response at or below a dose is what makes the dose eligible for backfilling.

n_cohort

Integer scalar. Number of cohorts in the dose escalation.

cohort_size

Integer scalar or vector. Number of patients per cohort of the dose escalation. A scalar is used for every cohort. A vector shorter than n_cohort is padded with its last element and a longer one is truncated.

window

Numeric scalar. Length of the DLT assessment window.

accrual_rate

Numeric scalar. Average number of patients arriving per unit of time, in the same unit as window.

n_cap

Integer scalar. A dose is no longer backfilled once this many patients, from the dose escalation and from backfilling together, have been treated at it. The dose escalation can still treat patients at the dose. Defaults to 12.

backfill_dose

Character scalar. Which dose receives a backfill patient when several are open: "highest" (the default, as in both articles) or "lowest".

conflict_dose

Character scalar. When the data of several backfilled doses conflict with those of the current dose, which of them anchors the pooled estimate: "highest" (the default here, following Zhao et al., 2024) or "lowest" (the default of be_boin_simulate, following Chen et al., 2026). See the details.

no_slot

Character scalar. What happens to a patient who arrives when neither the dose escalation nor any backfill dose can take a patient: "wait" (the default), the patient waits and is treated as soon as one can, as in tite_boin_simulate; or "leave", the patient is turned away and the trial waits for the next arrival.

accrual

Character scalar. Distribution of the times between arrivals: "exponential" (the default) for a Poisson process, "uniform" for a uniform distribution on (0, 2 / accrual_rate), or "fixed" for arrivals exactly 1 / accrual_rate apart.

dlt_time

Character scalar. Distribution of the time to DLT within the window, and of the time to response within the response window: "weibull" (the default) or "uniform".

late_fraction

Numeric scalar strictly between 0 and 1. Share of the DLTs that occur in the second half of the assessment window under the Weibull distribution. Defaults to 0.5.

resp_window

Numeric scalar. Length of the window within which a response is observed. Defaults to window.

resp_late_fraction

Numeric scalar strictly between 0 and 1. Share of the responses that occur in the second half of the response window under the Weibull distribution. Defaults to 0.5.

resp_cor

Numeric scalar strictly between -1 and 1. Correlation of the Gaussian copula that links the DLT and the response of a patient; a positive value makes a response more likely in a patient with a DLT. Defaults to 0, independence.

n_trials

Integer scalar. Number of trials to simulate. Defaults to 10000.

start_dose

Integer scalar. Dose level for the first cohort. Defaults to 1.

n_earlystop

Integer scalar. The trial stops once this many patients, backfilled ones included, have been treated at the current dose and the design would stay there. Defaults to 18.

p_saf

Numeric scalar. Highest DLT probability deemed subtherapeutic. Defaults to 0.6 * target.

p_tox

Numeric scalar. Lowest DLT probability deemed overly toxic. Defaults to 1.4 * target.

cutoff_eli

Numeric scalar. Posterior probability cutoff for dose elimination. Defaults to 0.95.

extrasafe

Logical scalar. Apply the stricter safety stopping rule at the lowest dose. Defaults to FALSE.

offset

Numeric scalar between 0 and 0.5. Amount by which cutoff_eli is relaxed for the safety stopping rule. Defaults to 0.05.

stay_on_1_of_3

Logical scalar. When TRUE, one DLT out of three patients leads to staying rather than de-escalating, in every use of the decision table. Zhao et al. (2024) use this modification in their main simulation. Defaults to FALSE. See boin_boundary.

n_earlystop_rule

Character scalar, either "with_stay" or "simple". See boin_simulate.

seed

Integer scalar or NULL. Random seed. When NULL the current state of the random number generator is used. The state of the calling session is restored on exit. Defaults to 123.

Details

Dose escalation. Cohorts are fully staggered: the next cohort starts only when every patient of the current one has completed the DLT assessment. The decision then follows the BOIN decision table applied to the patients at the current dose who have completed the assessment, backfilled ones included; pending backfill patients are left out, as in Zhao et al. (2024). Dose elimination is checked at the same moments, with the same completed patients, at every dose.

Backfilling. A patient who arrives while the escalation waits is backfilled to the highest dose b (or the lowest, with backfill_dose = "lowest") that is below the current dose, has not been eliminated, has fewer than n_cap patients, and has a response observed at b or at a lower dose. A dose is closed for backfilling when its own DLT rate exceeds the de-escalation boundary and so does the rate pooled with the next higher dose; the doses above it close with it. The rules are evaluated whenever a patient arrives, so a closed dose reopens when new data no longer meet the closing condition.

Conflicts. When the data of a backfilled dose b below the current dose call for a more conservative decision than those of the current dose (Table 2 of Zhao et al., 2024), the decision is taken instead from the data pooled from dose b* to the current dose, where b* is the highest conflicting dose by default. A de-escalation then goes to the highest dose k at or above b* whose data pooled from b* stay at or below the de-escalation boundary, or to b* - 1 if there is none, and to the lowest dose if b* is the lowest.

End of the trial. The trial stops when the escalation has treated n_cohort cohorts, when n_earlystop is reached with a decision to stay, or when the lowest dose is eliminated. Backfilling stops with the escalation. Every enrolled patient is followed to the end of the assessment, and the data of all patients, backfilled ones included, are those from which the MTD is selected.

Arrivals and outcomes. Patients arrive one at a time. The DLT of a patient and its time follow p_true and dlt_time as in tite_boin_simulate; the response and its time follow p_resp, resp_window and resp_late_fraction in the same way, linked to the DLT by resp_cor. Neither article states how responses are timed or correlated with DLTs. The Weibull time to response with half of the responses in the second half of the window and the Gaussian copula follow Takeda et al. (2025), who set the correlation to 0.2; the default here is independence.

Random numbers. The DLT variates of the escalation patients are drawn from R's stream exactly as in boin_simulate; arrivals and the variates of backfill patients and of responses come from two generators of their own seeded with seed. As a result, when no dose is ever opened for backfilling, for example with every p_resp equal to 0, the trials are identical to those of boin_simulate with the same seed.

Agreement with the article. With stay_on_1_of_3 = TRUE, n_earlystop = 9, accrual = "uniform" and no_slot = "leave", the operating characteristics of Table 4 of Zhao et al. (2024) are reproduced within simulation error, durations included. The article states a Poisson process, but its durations, for BOIN as well as for BF-BOIN, agree with uniform times between arrivals and patients turned away while the escalation waits. The trial example of Figure 1 of the article is replayed patient by patient in the tests of the package.

Value

An object of class c("bf_boin_trials", "backfill_trials"), which is a list with components

n_pts

Integer matrix, n_trials by number of doses, of patients treated, backfilled ones included.

n_tox

Integer matrix of the same shape, of DLTs, counted once every patient has completed the assessment.

n_bf

Integer matrix of the same shape, of backfilled patients.

n_resp

Integer matrix of the same shape, of patients with a response within the response window.

eliminated

Logical matrix of the same shape, marking doses eliminated during the trial.

cohorts_used

Integer vector of dose escalation cohorts treated in each trial.

stop_reason

Character vector giving why each trial ended, with the values of boin_simulate.

duration

Numeric vector. Time from the first arrival until every enrolled patient has completed the DLT assessment.

n_suspensions

Integer vector. Number of dose escalation decisions at which the escalation had to wait.

time_suspended

Numeric vector. Total time the escalation waited.

n_turned_away

Integer vector. Patients turned away, which happens only with no_slot = "leave".

boundary

The boin_boundary object used.

settings

List of the design parameters.

References

Zhao, Y., Yuan, Y., Korn, E. L. and Freidlin, B. (2024). Backfilling Patients in Phase I Dose-Escalation Trials Using Bayesian Optimal Interval Design (BOIN). Clinical Cancer Research, 30(4), 673-679.

Chen, K., Zhao, Y., Takeda, K. and Yuan, Y. (2026). BE-BOIN: A Dose Optimization Design Accommodating Backfill and Late-Onset Toxicity. Therapeutic Innovation and Regulatory Science. doi:10.1007/s43441-026-00994-0

Takeda, K., Zhu, J. and Hirakawa, A. (2025). BF-BOIN-ET: A Backfill Bayesian Optimal Interval Design Using Efficacy and Toxicity Outcomes for Dose Optimization. Pharmaceutical Statistics, 24(2), e2470.

See Also

be_boin_simulate, boin_simulate

Examples

# Scenario 3 of Zhao et al. (2024)
trials <- bf_boin_simulate(
  target = 0.25,
  p_true = c(0.04, 0.12, 0.25, 0.43, 0.63),
  p_resp = c(0.10, 0.20, 0.30, 0.45, 0.58),
  n_cohort = 10,
  cohort_size = 3,
  window = 1,
  accrual_rate = 3,
  n_earlystop = 9,
  stay_on_1_of_3 = TRUE,
  n_trials = 200,
  seed = 123
)
trials

colMeans(trials$n_bf)


Desirability Score Table of the BOIN12 Design

Description

Tabulate the desirability of a dose for every possible outcome of the patients treated there, as in Table 3 of Lin et al. (2020): the posterior probability that the utility of the dose exceeds the benchmark, its rank-based desirability score (RDS) and whether the dose is admissible.

Usage

boin12_decision_table(
  target,
  target_resp,
  n = c(0, 3, 6, 9),
  p_saf = NULL,
  p_tox = NULL,
  cutoff_eli = 0.95,
  cutoff_eli_resp = 0.9,
  psi00 = 40,
  psi11 = 60,
  benchmark_weight = 0.5,
  utility_prior = c(1, 1)
)

Arguments

target

Numeric scalar. Highest acceptable DLT probability, called phi_T by Lin et al. (2020). It is the target of the BOIN boundaries lambda_e and lambda_d, of the admissibility of a dose and of the MTD that bounds the OBD. Lin et al. recommend a value slightly above the target of a design that only considers toxicity, for example 0.35 instead of 0.30.

target_resp

Numeric scalar. Lowest acceptable response probability, phi_E. Note that this is a lower limit, as in sim_bf_boin_et, whereas the target_resp of sim_boin_et is a target.

n

Integer vector. Numbers of patients at a dose to tabulate. Defaults to c(0, 3, 6, 9).

p_saf, p_tox

Numeric scalars or NULL. Highest DLT probability deemed subtherapeutic and lowest deemed overly toxic, which give the BOIN boundaries. Default to 0.6 * target and 1.4 * target.

cutoff_eli

Numeric scalar. A dose is inadmissible, together with every higher dose, when the posterior probability that its DLT rate exceeds target is at least this cutoff. Defaults to 0.95.

cutoff_eli_resp

Numeric scalar. A dose is inadmissible when the posterior probability that its response rate is below target_resp is at least this cutoff. Defaults to 0.90.

psi00, psi11

Numeric scalars from 0 to 100. Utility of a patient without DLT and without response, and with both. The utility of a response without DLT is 100 and that of a DLT without response is 0. Default to 40 and 60, the example of Lin et al. (2020).

benchmark_weight

Numeric scalar above 0 and at most 1. The utility benchmark is benchmark_weight * u_low + (1 - benchmark_weight) * 100, where u_low is the expected utility of a dose whose DLT and response probabilities are target and target_resp, the two outcomes being independent. Defaults to 0.5, the benchmark of Lin et al. (2020); Lu et al. (2025) use 0.6.

utility_prior

Numeric vector of two positive numbers. Beta prior of the utility of a dose divided by 100. Defaults to c(1, 1).

Details

The utility of a patient is 100 for a response without DLT, psi00 for neither, psi11 for both and 0 for a DLT without response. The utility of a dose, divided by 100, has a beta posterior under the quasi-binomial model with the prior utility_prior, and the desirability is its posterior probability of exceeding u_benchmark / 100. The score ranks the desirability among the admissible outcomes of the table, from 1 for the lowest, equal desirabilities sharing the lowest rank. A dose is inadmissible ("E" in the printed table) when the posterior probability, under a uniform prior, that its DLT rate exceeds target is at least cutoff_eli, or that its response rate is below target_resp is at least cutoff_eli_resp. During a trial only the order of the desirabilities of the doses compared matters, so the score gives the same decisions.

Value

A data frame of class boin12_decision_table with one row per outcome and columns n, n_tox, n_resp, n_tox_resp (patients with both a DLT and a response; only when psi00 + psi11 is not 100, since the utility otherwise depends on the margins alone), admissible, desirability and score. The design parameters are kept in the attribute "design", a list with lambda_e, lambda_d, u_low and u_benchmark among others.

References

Lin, R., Zhou, Y., Yan, F., Li, D. and Yuan, Y. (2020). BOIN12: Bayesian optimal interval phase I/II trial design for utility-based dose finding in immunotherapy and targeted therapies. JCO Precision Oncology, 4, 1393-1402. doi:10.1200/PO.20.00257

See Also

boin12_simulate, sim_boin12

Examples

# Table 3 of Lin et al. (2020)
tab <- boin12_decision_table(target = 0.35, target_resp = 0.25)
tab

# A utility whose scores psi00 and psi11 do not add up to 100
boin12_decision_table(target = 0.35, target_resp = 0.25, n = c(0, 3),
                      psi00 = 30, psi11 = 50)


Select the Optimal Biological Dose of BOIN12 Trials

Description

Select the optimal biological dose (OBD) from the final data of one or more trials of the BOIN12 design with the two-step procedure of Lin et al. (2020): the MTD from the isotonic DLT rates, then the admissible dose up to the MTD with the highest estimated utility.

Usage

boin12_select_obd(
  n_pts,
  n_tox,
  n_resp,
  n_tox_resp = NULL,
  target,
  target_resp,
  cutoff_eli = 0.95,
  cutoff_eli_resp = 0.9,
  psi00 = 40,
  psi11 = 60,
  benchmark_weight = 0.5,
  utility_prior = c(1, 1),
  est_method = c("posterior_mean", "observed", "tail_probability"),
  early_stop = NULL
)

Arguments

n_pts

Integer vector of patients treated at each dose, or a matrix with one row per trial.

n_tox, n_resp

DLT and response counts of the same shape as n_pts.

n_tox_resp

Counts of the patients with both a DLT and a response, of the same shape as n_pts, or NULL. Needed unless psi00 + psi11 is 100, in which case the utility depends on the margins alone. Defaults to NULL.

target

Numeric scalar. Highest acceptable DLT probability, called phi_T by Lin et al. (2020). It is the target of the BOIN boundaries lambda_e and lambda_d, of the admissibility of a dose and of the MTD that bounds the OBD. Lin et al. recommend a value slightly above the target of a design that only considers toxicity, for example 0.35 instead of 0.30.

target_resp

Numeric scalar. Lowest acceptable response probability, phi_E. Note that this is a lower limit, as in sim_bf_boin_et, whereas the target_resp of sim_boin_et is a target.

cutoff_eli

Numeric scalar. A dose is inadmissible, together with every higher dose, when the posterior probability that its DLT rate exceeds target is at least this cutoff. Defaults to 0.95.

cutoff_eli_resp

Numeric scalar. A dose is inadmissible when the posterior probability that its response rate is below target_resp is at least this cutoff. Defaults to 0.90.

psi00, psi11

Numeric scalars from 0 to 100. Utility of a patient without DLT and without response, and with both. The utility of a response without DLT is 100 and that of a DLT without response is 0. Default to 40 and 60, the example of Lin et al. (2020).

benchmark_weight

Numeric scalar above 0 and at most 1. The utility benchmark is benchmark_weight * u_low + (1 - benchmark_weight) * 100, where u_low is the expected utility of a dose whose DLT and response probabilities are target and target_resp, the two outcomes being independent. Defaults to 0.5, the benchmark of Lin et al. (2020); Lu et al. (2025) use 0.6.

utility_prior

Numeric vector of two positive numbers. Beta prior of the utility of a dose divided by 100. Defaults to c(1, 1).

est_method

Character scalar. Estimate of the utility of a dose: "posterior_mean" (the default), the posterior mean of the quasi-binomial model given in Section 4 of the Supplement of Lin et al. (2020); "observed", the observed mean utility, which the example of Section 6 of that Supplement reports; or "tail_probability", the desirability used during the trial, which the 'escalation' package uses.

early_stop

Logical vector or NULL. TRUE for the trials stopped early, which select no OBD. Defaults to NULL, no early stop.

Details

Only the doses with at least one patient are considered. The DLT rates are made monotone by isotonic regression with equal weights, and the MTD is the dose whose estimate is closest to target, ties to the higher dose as in the 'escalation' package. The OBD is the admissible dose, in the sense of boin12_simulate, at or below the MTD with the highest estimate, ties to the lower dose. When no dose up to the MTD is admissible, no OBD is selected.

Value

A list with components

obd

Integer vector of the selected dose levels, NA when no dose is selected.

reason

Character vector: "selected", "early_stop" or "no_admissible_dose".

utility

Numeric matrix of the utility estimates (on the scale 0 to 100; for "tail_probability", 100 times the probability), NA for the doses not tried.

References

Lin, R., Zhou, Y., Yan, F., Li, D. and Yuan, Y. (2020). BOIN12: Bayesian optimal interval phase I/II trial design for utility-based dose finding in immunotherapy and targeted therapies. JCO Precision Oncology, 4, 1393-1402. doi:10.1200/PO.20.00257

See Also

sim_boin12, boin12_simulate

Examples

# The example of Section 6 of the Supplement of Lin et al. (2020)
boin12_select_obd(
  n_pts = c(3, 3, 6, 12, 6), n_tox = c(0, 1, 1, 3, 3),
  n_resp = c(0, 1, 2, 6, 3), target = 0.35, target_resp = 0.25,
  est_method = "observed"
)


Simulate BOIN12 Trials

Description

Simulate trials of the BOIN12 design of Lin et al. (2020), which assigns each cohort to the most desirable dose by a utility that weighs the response against the DLT, and return the patients, DLTs and responses at every dose. This is the simulation engine behind sim_boin12.

Usage

boin12_simulate(
  target,
  target_resp,
  p_true,
  p_resp,
  n_cohort,
  cohort_size,
  n_trials = 10000,
  start_dose = 1,
  n_earlystop = NULL,
  n_earlystop_rule = c("with_stay", "simple"),
  p_saf = NULL,
  p_tox = NULL,
  cutoff_eli = 0.95,
  cutoff_eli_resp = 0.9,
  psi00 = 40,
  psi11 = 60,
  benchmark_weight = 0.5,
  utility_prior = c(1, 1),
  n_star = 6,
  n_explore = 9,
  tie_break = c("higher", "random"),
  no_candidate = c("nearest", "stop"),
  explore_from = c("any", "admissible"),
  resp_cor = 0,
  resp_cor_type = c("copula", "binary"),
  seed = 123
)

Arguments

target

Numeric scalar. Highest acceptable DLT probability, called phi_T by Lin et al. (2020). It is the target of the BOIN boundaries lambda_e and lambda_d, of the admissibility of a dose and of the MTD that bounds the OBD. Lin et al. recommend a value slightly above the target of a design that only considers toxicity, for example 0.35 instead of 0.30.

target_resp

Numeric scalar. Lowest acceptable response probability, phi_E. Note that this is a lower limit, as in sim_bf_boin_et, whereas the target_resp of sim_boin_et is a target.

p_true

Numeric vector. True DLT probability at each dose.

p_resp

Numeric vector. True response probability at each dose.

n_cohort

Integer scalar. Number of cohorts in a trial.

cohort_size

Integer scalar or vector. Number of patients per cohort. A scalar is used for every cohort; a shorter vector is padded with its last element.

n_trials

Integer scalar. Number of trials to simulate. Defaults to 10000.

start_dose

Integer scalar. Dose level of the first cohort. Defaults to 1.

n_earlystop

Integer scalar or NULL. Number of patients at the current dose that ends the trial when the next cohort would stay there (see n_earlystop_rule). Defaults to NULL, which runs every trial to the maximum sample size, as in Lin et al. (2020).

n_earlystop_rule

Character scalar. "with_stay" (the default) ends the trial at n_earlystop only when the next cohort would stay at the current dose, as in the example of Zhou et al. (2022); "simple" ends it in any case.

p_saf, p_tox

Numeric scalars or NULL. Highest DLT probability deemed subtherapeutic and lowest deemed overly toxic, which give the BOIN boundaries. Default to 0.6 * target and 1.4 * target.

cutoff_eli

Numeric scalar. A dose is inadmissible, together with every higher dose, when the posterior probability that its DLT rate exceeds target is at least this cutoff. Defaults to 0.95.

cutoff_eli_resp

Numeric scalar. A dose is inadmissible when the posterior probability that its response rate is below target_resp is at least this cutoff. Defaults to 0.90.

psi00, psi11

Numeric scalars from 0 to 100. Utility of a patient without DLT and without response, and with both. The utility of a response without DLT is 100 and that of a DLT without response is 0. Default to 40 and 60, the example of Lin et al. (2020).

benchmark_weight

Numeric scalar above 0 and at most 1. The utility benchmark is benchmark_weight * u_low + (1 - benchmark_weight) * 100, where u_low is the expected utility of a dose whose DLT and response probabilities are target and target_resp, the two outcomes being independent. Defaults to 0.5, the benchmark of Lin et al. (2020); Lu et al. (2025) use 0.6.

utility_prior

Numeric vector of two positive numbers. Beta prior of the utility of a dose divided by 100. Defaults to c(1, 1).

n_star

Integer scalar. With at least this many patients at the current dose and a DLT rate between lambda_e and lambda_d, the next dose is chosen from the current dose and the dose below. Defaults to 6.

n_explore

Integer scalar. With at least this many patients at the current dose, a DLT rate below lambda_d and an untried admissible dose above, the next cohort goes to that dose. Defaults to 9.

tie_break

Character scalar. Choice among the doses of equal desirability: "higher" (the default) takes the highest of them, the rule of the BOIN12 software according to the 'escalation' package; "random" takes one of them at random, as stated in Table S2 of the Supplement of Lin et al. (2020). See Details.

no_candidate

Character scalar. What happens when none of the doses allowed for the next cohort is admissible: "nearest" (the default) goes to the admissible dose nearest to the current one; "stop" ends the trial without an OBD. See Details.

explore_from

Character scalar. Doses from which the exploration rule (see n_explore) escalates: "any" (the default) from any dose, as in the 'escalation' package; "admissible" only from an admissible dose, as the results published by Lin et al. (2020) indicate. See Details.

resp_cor

Numeric scalar between -1 and 1. Correlation between the DLT and the response of a patient, see resp_cor_type. Defaults to 0.

resp_cor_type

Character scalar. "copula" (the default) links the two outcomes by a Gaussian copula with correlation resp_cor, the bivariate normal model of Lin et al. (2020); "binary" sets the correlation of the two binary outcomes, as in boin_et_simulate.

seed

Integer scalar or NULL. Random seed. The state of the calling session is restored on exit. Defaults to 123.

Details

After each cohort, with phat the DLT rate at the current dose: the trial stops when no dose is admissible; when n_explore patients have been treated at the current dose, phat is below lambda_d and the dose above is untried, the dose is escalated (with explore_from = "admissible", only when the current dose is admissible); otherwise, when phat is at least lambda_d, the next dose is the highest admissible dose below the current one (the current one if there is none); when phat is above lambda_e and at least n_star patients have been treated, the next dose is the more desirable of the current dose and the dose below; otherwise it is the most desirable of the dose below, the current dose and the dose above. Only admissible doses are considered. Ties go to the higher dose, as in the BOIN12 software according to the 'escalation' package, or with tie_break = "random" to one of the tied doses drawn at random. When none of these doses is admissible, the admissible dose nearest to the current one is chosen, ties to the lower dose. The desirability is that of boin12_decision_table.

With no_candidate = "stop", the trial stops instead, without an OBD and with the stopping reason "no_admissible_candidate", when none of these doses is admissible and when phat is at least lambda_d and no dose below the current one is admissible. At the lowest dose, a phat of at least lambda_d still keeps the next cohort there when that dose is admissible.

Lin et al. (2020) leave three points open, decided here as follows. A dose made inadmissible by its DLT data also makes every higher dose inadmissible, as in BOIN and in Lu et al. (2025), whereas the 'escalation' package only checks the doses next to the current one. A de-escalation never goes to an inadmissible dose; 'escalation' moves to the dose below whatever its data. The trial stops when no dose is admissible; 'escalation' goes on at the lowest dose when its DLT rate is high. The article breaks ties at random; the software chooses the higher dose. tie_break = "random", no_candidate = "stop" and explore_from = "admissible" are the settings compared with the results published by Lin et al. (2020) in inst/reproduce/reproduce_Lin2020.R; the last two rules are not stated in the article and were inferred from those results.

Each patient draws two uniform variates in enrollment order, the first for the DLT and the second for the response. With tie_break = "random", a decision among tied doses draws one more variate, so that the trials depart from those with "higher" after the first tie.

Value

An object of class boin12_trials, which is a list with components

n_pts, n_tox, n_resp, n_tox_resp

Integer matrices, one row per trial and one column per dose, of the patients treated, the DLTs, the responses and the patients with both a DLT and a response.

cohorts_used

Integer vector of the cohorts enrolled.

stop_reason

Character vector: "no_admissible_dose", "n_earlystop", "max_cohorts" or "no_admissible_candidate" (only with no_candidate = "stop").

early_stop

Logical vector, TRUE for the trials stopped because no dose was admissible or, with no_candidate = "stop", because no dose allowed for the next cohort was admissible. These trials select no OBD.

design

"BOIN12".

boundary

List with lambda_e, lambda_d, u_low and u_benchmark.

settings

List of the design parameters.

References

Lin, R., Zhou, Y., Yan, F., Li, D. and Yuan, Y. (2020). BOIN12: Bayesian optimal interval phase I/II trial design for utility-based dose finding in immunotherapy and targeted therapies. JCO Precision Oncology, 4, 1393-1402. doi:10.1200/PO.20.00257

Zhou, Y., Lin, R., Lee, J. J., Li, D., Wang, L., Li, R. and Yuan, Y. (2022). TITE-BOIN12: A Bayesian phase I/II trial design to find the optimal biological dose with late-onset toxicity and efficacy. Statistics in Medicine, 41(11), 1918-1931. doi:10.1002/sim.9337

Lu, M., Zhang, J., Yuan, Y. and Lin, R. (2025). Comb-BOIN12: A utility-based Bayesian optimal interval design for dose optimization in cancer drug-combination trials. Statistics in Biopharmaceutical Research, 17(2), 266-276. doi:10.1080/19466315.2024.2370403

See Also

sim_boin12, boin12_select_obd, boin12_decision_table

Examples

# Scenario 1 of Lin et al. (2020)
trials <- boin12_simulate(
  target = 0.35, target_resp = 0.25,
  p_true = c(0.05, 0.12, 0.27, 0.35, 0.50),
  p_resp = c(0.20, 0.35, 0.36, 0.37, 0.38),
  n_cohort = 12, cohort_size = 3, n_trials = 200, seed = 123
)
trials


Integer Decision Boundaries for the BOIN Design

Description

Tabulate, for every attainable number of patients treated at a dose, the number of DLTs that triggers escalation, de-escalation, elimination and, when requested, the stricter safety stopping rule at the lowest dose.

Usage

boin_boundary(
  target,
  max_n,
  p_saf = NULL,
  p_tox = NULL,
  cutoff_eli = 0.95,
  extrasafe = FALSE,
  offset = 0.05,
  stay_on_1_of_3 = FALSE
)

Arguments

target

Numeric scalar. Target DLT probability, for example 0.30.

max_n

Integer scalar. Largest number of patients that can be treated at a single dose, which is the number of columns of the resulting table. For a trial with n_cohort cohorts of size cohort_size this is n_cohort * cohort_size.

p_saf

Numeric scalar. Highest DLT probability deemed subtherapeutic. Defaults to 0.6 * target.

p_tox

Numeric scalar. Lowest DLT probability deemed overly toxic. Defaults to 1.4 * target.

cutoff_eli

Numeric scalar. Posterior probability cutoff above which a dose is eliminated for toxicity. Defaults to 0.95.

extrasafe

Logical scalar. When TRUE, also tabulate the safety stopping boundary applied at the lowest dose. Defaults to FALSE.

offset

Numeric scalar between 0 and 0.5. Amount by which cutoff_eli is relaxed for the safety stopping rule. Defaults to 0.05.

stay_on_1_of_3

Logical scalar. When TRUE, one DLT out of three patients leads to staying at the current dose rather than de-escalating. Defaults to FALSE. See the details.

Details

The escalation boundary is floor(lambda_e * n) and the de-escalation boundary is ceiling(lambda_d * n), with the convention that when lambda_d * n is a whole number de-escalation requires one more DLT. The elimination boundary is the smallest positive number of DLTs for which Pr(p > target | data) exceeds cutoff_eli under a uniform Beta(1, 1) prior, and is not evaluated before three patients have been treated. The de-escalation boundary is capped at the elimination boundary.

With the default thresholds these definitions reproduce BOIN::get.boundary() exactly.

Value

An object of class boin_boundary, which is a list with components

lambda_e

Escalation interval boundary.

lambda_d

De-escalation interval boundary.

n

Number of patients, 1 to max_n.

b_esc

Escalate when the number of DLTs is at most this value.

b_deesc

De-escalate when the number of DLTs reaches this value.

b_elim

Eliminate the dose when the number of DLTs reaches this value, NA when no elimination is possible at that sample size.

b_stop

Safety stopping boundary at the lowest dose, all NA unless extrasafe is TRUE.

stay_on_1_of_3

Whether the modification was requested.

stay_on_1_of_3_applied

Whether it changed the boundaries.

together with the design parameters used.

Staying on one DLT out of three

For some target rates the optimal BOIN decision after one DLT in three patients is to de-escalate, because the likelihood of overdosing then exceeds the likelihood of proper dosing. Long practice with the 3+3 design has nonetheless made staying at the dose the widely accepted choice, and stay_on_1_of_3 = TRUE aligns the design with that practice by raising the de-escalation boundary at three patients from one DLT to two. Nothing else in the table changes.

The modification is applied only where it is meaningful, that is when one DLT out of three currently triggers de-escalation. It never overrides an escalation, and it never overrides an elimination, which is a safety rule. Whether it took effect is reported in stay_on_1_of_3_applied. With the default thresholds it takes effect for target rates from about 0.098 to 0.279; below that range one DLT out of three already eliminates the dose, and above it the design already stays.

References

Liu S. and Yuan, Y. (2015). Bayesian Optimal Interval Designs for Phase I Clinical Trials. Journal of the Royal Statistical Society: Series C, 64, 507-523.

See Also

boin_lambda, boin_decision_table

Examples

bd <- boin_boundary(target = 0.30, max_n = 18)
bd

# At a target of 0.25 one DLT out of three de-escalates by default
boin_boundary(target = 0.25, max_n = 18)$b_deesc[3]

# and stays once the modification is switched on
modified <- boin_boundary(target = 0.25, max_n = 18, stay_on_1_of_3 = TRUE)
modified$b_deesc[3]
modified$stay_on_1_of_3_applied

# At a target of 0.30 the design already stays, so nothing changes
boin_boundary(target = 0.30, max_n = 18, stay_on_1_of_3 = TRUE)$stay_on_1_of_3_applied


Decision Table for the BOIN Design

Description

Build the lookup table that maps a pair of DLT and patient counts at the current dose to the dose assignment decision.

Usage

boin_decision_table(
  target,
  max_n,
  p_saf = NULL,
  p_tox = NULL,
  cutoff_eli = 0.95,
  stay_on_1_of_3 = FALSE
)

Arguments

target

Numeric scalar. Target DLT probability.

max_n

Integer scalar. Largest number of patients treated at a single dose.

p_saf

Numeric scalar. Highest DLT probability deemed subtherapeutic. Defaults to 0.6 * target.

p_tox

Numeric scalar. Lowest DLT probability deemed overly toxic. Defaults to 1.4 * target.

cutoff_eli

Numeric scalar. Posterior probability cutoff for dose elimination. Defaults to 0.95.

stay_on_1_of_3

Logical scalar. When TRUE, one DLT out of three patients leads to staying at the current dose rather than de-escalating. Defaults to FALSE. See boin_boundary for what the modification does.

Details

The table is derived from boin_boundary and therefore agrees with the decisions taken by the simulation engine. Elimination takes precedence over the other rules, then escalation, then de-escalation.

Value

An object of class boin_decision_table, which is a character matrix with max_n + 1 rows, labeled by the number of DLTs from 0 to max_n, and max_n columns, labeled by the number of patients from 1 to max_n. Entries are "E" to escalate, "S" to stay, "D" to de-escalate and "DE" to de-escalate and eliminate the dose together with all higher doses. Combinations with more DLTs than patients are NA. The object has print and plot methods; subsetting it returns a plain matrix.

See Also

boin_boundary, plot.boin_decision_table

Examples

decisions <- boin_decision_table(target = 0.30, max_n = 12)
decisions

# Only the sample sizes reached at the end of a cohort of three
print(decisions, cohort_size = 3)

# One DLT out of three de-escalates at a target of 0.25
boin_decision_table(target = 0.25, max_n = 9)["1", "3"]

# and stays once the modification is switched on
boin_decision_table(target = 0.25, max_n = 9, stay_on_1_of_3 = TRUE)["1", "3"]


Boundaries of the BOIN-ET Design

Description

Find the lower and upper DLT boundaries and the lower response boundary of the BOIN-ET design of Takeda, Taguri and Morita (2018). The three boundaries minimize the probability of an incorrect dose assignment under six hypotheses about the DLT and response probabilities at the current dose, and are searched on a grid of step 0.01, as in the 'boinet' package.

Usage

boin_et_boundary(
  target,
  target_resp,
  p_saf = NULL,
  p_tox = NULL,
  p_saf_resp = NULL,
  prior = rep(1/6, 6)
)

Arguments

target

Numeric scalar. Target DLT probability, for example 0.30.

target_resp

Numeric scalar. Target response probability, for example 0.60.

p_saf

Numeric scalar. Highest DLT probability deemed subtherapeutic. Defaults to 0.1 * target, the value recommended by Takeda et al. (2018), which is far below the 0.6 * target of the BOIN design.

p_tox

Numeric scalar. Lowest DLT probability deemed overly toxic. Defaults to 1.4 * target.

p_saf_resp

Numeric scalar. Highest response probability deemed subtherapeutic. Defaults to 0.6 * target_resp.

prior

Numeric vector of length 6. Prior probabilities of the six hypotheses. Defaults to rep(1 / 6, 6), the noninformative choice of the article. The third hypothesis, under which every decision is correct, does not enter the criterion.

Details

The grids run from p_saf to target for lambda1, from target to p_tox for lambda2 and from p_saf_resp to target_resp for eta1, all by 0.01. At each grid point the probability of an incorrect decision is evaluated with binomial probabilities for 100 patients, and the first minimum in the order of the grids is returned. This is the search of boinet::gridoptim(), including its expression for the fourth hypothesis, and with the default design parameters and a target of 0.30 for the DLT and 0.60 for the response it gives the boundaries 0.14, 0.35 and 0.48 reported by Takeda et al. (2018).

Value

An object of class boin_et_boundary, which is a list with components

lambda1

Lower DLT boundary. The dose is escalated when the observed DLT rate is at most lambda1 and the observed response rate is at most eta1.

lambda2

Upper DLT boundary. The dose is de-escalated when the observed DLT rate is at least lambda2.

eta1

Lower response boundary.

prob_incorrect

The minimized probability of an incorrect decision.

target, target_resp, p_saf, p_tox, p_saf_resp, prior

The design parameters.

References

Takeda, K., Taguri, M. and Morita, S. (2018). BOIN-ET: Bayesian optimal interval design for dose finding based on both efficacy and toxicity outcomes. Pharmaceutical Statistics, 17(4), 383-395. doi:10.1002/pst.1864

Yamaguchi, Y., Takeda, K. and Maruo, K. (2025). boinet: An R Package for Bayesian Optimal Interval Design for Dose Finding Based on Both Efficacy and Toxicity Outcomes. The R Journal, 17(2), 15-34. doi:10.32614/RJ-2025-012

See Also

boin_et_decision_table, sim_boin_et

Examples

bd <- boin_et_boundary(target = 0.30, target_resp = 0.60)
bd

c(bd$lambda1, bd$lambda2, bd$eta1)


Decision Table for the BOIN-ET Design

Description

Tabulate the decision of the BOIN-ET design for every number of DLTs and responses at the current dose, for the given numbers of patients, in the form of Table 2 of Takeda, Taguri and Morita (2018). The table also marks the counts for which the dose is no longer admissible.

Usage

boin_et_decision_table(
  target,
  target_resp,
  n = c(3, 6, 9, 12),
  p_saf = NULL,
  p_tox = NULL,
  p_saf_resp = NULL,
  cutoff_eli = 0.95,
  cutoff_eli_resp = 0.99,
  p_eli = NULL,
  p_eli_resp = NULL,
  prior = rep(1/6, 6)
)

Arguments

target

Numeric scalar. Target DLT probability, for example 0.30.

target_resp

Numeric scalar. Target response probability, for example 0.60.

n

Integer vector. Numbers of patients at the current dose to tabulate. Defaults to c(3, 6, 9, 12).

p_saf

Numeric scalar. Highest DLT probability deemed subtherapeutic. Defaults to 0.1 * target, the value recommended by Takeda et al. (2018), which is far below the 0.6 * target of the BOIN design.

p_tox

Numeric scalar. Lowest DLT probability deemed overly toxic. Defaults to 1.4 * target.

p_saf_resp

Numeric scalar. Highest response probability deemed subtherapeutic. Defaults to 0.6 * target_resp.

cutoff_eli

Numeric scalar. A dose is no longer admissible when the posterior probability that its DLT rate is below p_eli falls below 1 - cutoff_eli. Defaults to 0.95.

cutoff_eli_resp

Numeric scalar. A dose is no longer admissible when the posterior probability that its response rate is above p_eli_resp falls below 1 - cutoff_eli_resp. Defaults to 0.99.

p_eli

Numeric scalar or NULL. DLT probability of the rule above. Defaults to NULL, which uses target as the 'boinet' package does. Takeda et al. (2018) used 0.40 with a cutoff of 0.90.

p_eli_resp

Numeric scalar or NULL. Response probability of the rule above. Defaults to NULL, which uses p_saf_resp as the 'boinet' package does. Takeda et al. (2018) used 0.20 with a cutoff of 0.90.

prior

Numeric vector of length 6. Prior probabilities of the six hypotheses. Defaults to rep(1 / 6, 6), the noninformative choice of the article. The third hypothesis, under which every decision is correct, does not enter the criterion.

Details

When the observed DLT rate is at most lambda1 and the observed response rate at most eta1, the dose is escalated; when the DLT rate is below lambda2 and the response rate above eta1, the next cohort stays; when the DLT rate is at least lambda2, the dose is de-escalated. Otherwise the dose is escalated when the next dose has not been tried, and the next cohort goes to the dose with the highest observed response rate among the current dose and its neighbors, with ties broken at random. An inadmissible dose is skipped by boin_et_simulate.

Value

An object of class boin_et_decision_table, which is a data frame with one row per combination of n patients, n_tox DLTs and n_resp responses, and the columns

n, n_tox, n_resp

The counts.

decision

"E" to escalate, "S" to stay, "D" to de-escalate and "E/S/D" when the next dose is chosen among the current dose and its neighbors by their observed response rates.

tox_excluded, resp_excluded

Whether the DLT data or the response data make the dose inadmissible.

The boundaries are attached as the attribute "boundary", an object of class boin_et_boundary.

References

Takeda, K., Taguri, M. and Morita, S. (2018). BOIN-ET: Bayesian optimal interval design for dose finding based on both efficacy and toxicity outcomes. Pharmaceutical Statistics, 17(4), 383-395. doi:10.1002/pst.1864

See Also

boin_et_boundary, boin_et_simulate

Examples

# Table 2 of Takeda et al. (2018)
tab <- boin_et_decision_table(target = 0.30, target_resp = 0.60, n = c(3, 6))
tab

head(as.data.frame(tab))


Select the Optimal Biological Dose of BOIN-ET Trials

Description

Select the optimal biological dose (OBD) from the final data of one or more trials of the BOIN-ET design, with the estimators and selection rules of the 'boinet' package.

Usage

boin_et_select_obd(
  n_pts,
  n_tox,
  n_resp,
  target,
  target_resp,
  p_saf = NULL,
  p_tox = NULL,
  p_saf_resp = NULL,
  cutoff_eli = 0.95,
  cutoff_eli_resp = 0.99,
  p_eli = NULL,
  p_eli_resp = NULL,
  est_method = c("observed", "multi_iso", "fp_logistic"),
  obd_method = c("max_resp", "utility_weighted", "utility_truncated_linear",
    "utility_scoring"),
  w1 = 0.33,
  w2 = 1.09,
  t_low = NULL,
  t_upp = NULL,
  e_low = NULL,
  e_upp = NULL,
  psi00 = 40,
  psi11 = 60,
  early_stop = NULL,
  boinet_compatible = FALSE
)

Arguments

n_pts

Integer vector of patients treated at each dose, or a matrix with one row per trial.

n_tox

DLT counts of the same shape as n_pts.

n_resp

Response counts of the same shape as n_pts.

target

Numeric scalar. Target DLT probability, for example 0.30.

target_resp

Numeric scalar. Target response probability, for example 0.60.

p_saf

Numeric scalar. Highest DLT probability deemed subtherapeutic. Defaults to 0.1 * target, the value recommended by Takeda et al. (2018), which is far below the 0.6 * target of the BOIN design.

p_tox

Numeric scalar. Lowest DLT probability deemed overly toxic. Defaults to 1.4 * target.

p_saf_resp

Numeric scalar. Highest response probability deemed subtherapeutic. Defaults to 0.6 * target_resp.

cutoff_eli

Numeric scalar. A dose is no longer admissible when the posterior probability that its DLT rate is below p_eli falls below 1 - cutoff_eli. Defaults to 0.95.

cutoff_eli_resp

Numeric scalar. A dose is no longer admissible when the posterior probability that its response rate is above p_eli_resp falls below 1 - cutoff_eli_resp. Defaults to 0.99.

p_eli

Numeric scalar or NULL. DLT probability of the rule above. Defaults to NULL, which uses target as the 'boinet' package does. Takeda et al. (2018) used 0.40 with a cutoff of 0.90.

p_eli_resp

Numeric scalar or NULL. Response probability of the rule above. Defaults to NULL, which uses p_saf_resp as the 'boinet' package does. Takeda et al. (2018) used 0.20 with a cutoff of 0.90.

est_method

Character scalar. Estimator of the response rates: "observed" (the default) for the observed rates, "multi_iso" for the model-averaged unimodal isotonic regression of Lin and Yin (2017), or "fp_logistic" for the fractional polynomial logistic regression of Takeda et al. (2018), which needs the 'mfp' package.

obd_method

Character scalar. Selection rule: "max_resp" (the default) for the admissible dose with the highest estimated response rate up to the estimated MTD, or the dose that maximizes the utility "utility_weighted", "utility_truncated_linear" or "utility_scoring" among the admissible doses.

w1, w2

Numeric scalars. Weights of the weighted utility q - w1 * p - w2 * p * (p > p_tox), where p and q are the estimated DLT and response rates. Default to 0.33 and 1.09.

t_low, t_upp

Numeric scalars or NULL. DLT rates between which the truncated linear utility falls from one to zero. Default to p_saf and p_tox.

e_low, e_upp

Numeric scalars or NULL. Response rates between which the truncated linear utility rises from zero to one. Default to p_saf_resp / 2 and target_resp.

psi00, psi11

Numeric scalars. Scores of the scoring utility for a patient with neither DLT nor response and for a patient with both, the scores of a response without DLT and of a DLT without response being 100 and 0. Default to 40 and 60.

early_stop

Logical vector or NULL. TRUE for the trials stopped early, which select no OBD. Defaults to NULL, no early stop.

boinet_compatible

Logical scalar. Apply the rules of the 'boinet' package (version 1.6.0) exactly, in which a dose excluded by its DLT data does not exclude the doses above it. Defaults to FALSE; see Details.

Details

Only the doses with at least one patient are considered. A dose is admissible when the posterior probability that its DLT rate is below p_eli is at least 1 - cutoff_eli and the posterior probability that its response rate is above p_eli_resp is at least 1 - cutoff_eli_resp, under uniform priors, and when no lower dose is excluded by its DLT data. When no dose is admissible, no OBD is selected. Otherwise the DLT rates of the doses tried are estimated by isotonic regression of the observed rates with equal weights. Under "max_resp" the estimated MTD is the highest dose whose estimate is as close to target as that of the closest admissible dose, and the OBD is the admissible dose up to the MTD with the highest response estimate. Ties go to the lowest dose. These are the rules of boinet::obd.select(), except that in 'boinet' a dose excluded by its DLT data does not exclude the doses above it, which can then be selected; boinet_compatible = TRUE applies this rule, and boin_et_simulate explains the change.

The model-based estimates are computed in R once for every distinct set of final data; the selection itself runs in C++.

Value

A list with components

obd

Integer vector of the selected dose levels, NA when no dose is selected.

reason

Character vector: "selected", "early_stop" or "no_admissible_dose".

probe

Numeric matrix of the response estimates, NA for the doses not tried.

References

Takeda, K., Taguri, M. and Morita, S. (2018). BOIN-ET: Bayesian optimal interval design for dose finding based on both efficacy and toxicity outcomes. Pharmaceutical Statistics, 17(4), 383-395. doi:10.1002/pst.1864

Yamaguchi, Y., Takeda, K., Yoshida, S. and Maruo, K. (2024). Optimal biological dose selection in dose-finding trials with model-assisted designs based on efficacy and toxicity: a simulation study. Journal of Biopharmaceutical Statistics, 34(3), 379-393. doi:10.1080/10543406.2023.2202259

Lin, R. and Yin, G. (2017). STEIN: A simple toxicity and efficacy interval design for seamless phase I/II clinical trials. Statistics in Medicine, 36(26), 4106-4120. doi:10.1002/sim.7428

See Also

sim_boin_et, boin_et_simulate

Examples

# One trial: patients, DLTs and responses at four doses
boin_et_select_obd(
  n_pts = c(3, 6, 12, 3), n_tox = c(0, 1, 3, 2), n_resp = c(0, 2, 7, 2),
  target = 0.30, target_resp = 0.60
)

# The OBD under a utility
boin_et_select_obd(
  n_pts = c(3, 6, 12, 3), n_tox = c(0, 1, 3, 2), n_resp = c(0, 2, 7, 2),
  target = 0.30, target_resp = 0.60, obd_method = "utility_scoring"
)$obd


Simulate BOIN-ET Trials

Description

Run the BOIN-ET dose-finding algorithm of Takeda, Taguri and Morita (2018) over many simulated trials and return the patient, DLT and response counts at every dose. This is the simulation engine behind sim_boin_et, exposed for users who want the raw trial data.

Usage

boin_et_simulate(
  target,
  target_resp,
  p_true,
  p_resp,
  n_cohort,
  cohort_size,
  n_trials = 10000,
  start_dose = 1,
  n_earlystop = NULL,
  p_saf = NULL,
  p_tox = NULL,
  p_saf_resp = NULL,
  cutoff_eli = 0.95,
  cutoff_eli_resp = 0.99,
  p_eli = NULL,
  p_eli_resp = NULL,
  resp_cor = 0.2,
  resp_cor_type = c("copula", "binary"),
  boinet_compatible = FALSE,
  prior = rep(1/6, 6),
  seed = 123
)

Arguments

target

Numeric scalar. Target DLT probability, for example 0.30.

target_resp

Numeric scalar. Target response probability, for example 0.60.

p_true

Numeric vector. True DLT probability at each dose level, in increasing dose order.

p_resp

Numeric vector of the same length as p_true. True response probability at each dose level.

n_cohort

Integer scalar. Number of cohorts in a trial.

cohort_size

Integer scalar or vector. Number of patients per cohort. A scalar is used for every cohort. A vector shorter than n_cohort is padded with its last element and a longer one is truncated.

n_trials

Integer scalar. Number of trials to simulate. Defaults to 10000.

start_dose

Integer scalar. Dose level for the first cohort. Defaults to 1.

n_earlystop

Integer scalar or NULL. The trial stops once this many patients have been treated at any dose. Defaults to NULL, the maximum sample size, which is the default of the 'boinet' package.

p_saf

Numeric scalar. Highest DLT probability deemed subtherapeutic. Defaults to 0.1 * target, the value recommended by Takeda et al. (2018), which is far below the 0.6 * target of the BOIN design.

p_tox

Numeric scalar. Lowest DLT probability deemed overly toxic. Defaults to 1.4 * target.

p_saf_resp

Numeric scalar. Highest response probability deemed subtherapeutic. Defaults to 0.6 * target_resp.

cutoff_eli

Numeric scalar. A dose is no longer admissible when the posterior probability that its DLT rate is below p_eli falls below 1 - cutoff_eli. Defaults to 0.95.

cutoff_eli_resp

Numeric scalar. A dose is no longer admissible when the posterior probability that its response rate is above p_eli_resp falls below 1 - cutoff_eli_resp. Defaults to 0.99.

p_eli

Numeric scalar or NULL. DLT probability of the rule above. Defaults to NULL, which uses target as the 'boinet' package does. Takeda et al. (2018) used 0.40 with a cutoff of 0.90.

p_eli_resp

Numeric scalar or NULL. Response probability of the rule above. Defaults to NULL, which uses p_saf_resp as the 'boinet' package does. Takeda et al. (2018) used 0.20 with a cutoff of 0.90.

resp_cor

Numeric scalar strictly between -1 and 1. Correlation between the DLT and the response of a patient. Defaults to 0.2, the default of the 'boinet' package.

resp_cor_type

Character scalar. How resp_cor links the two outcomes: "copula" (the default) uses it as the correlation of a Gaussian copula, which is how the 'boinet' package generates its data; "binary" uses it as the correlation of the two binary outcomes, as in the simulations of Takeda et al. (2018).

boinet_compatible

Logical scalar. Apply the rules of the 'boinet' package (version 1.6.0) exactly. Defaults to FALSE, which keeps to Takeda et al. (2018), who do not allow dose skipping during escalation; see Details.

prior

Numeric vector of length 6. Prior probabilities of the six hypotheses. Defaults to rep(1 / 6, 6), the noninformative choice of the article. The third hypothesis, under which every decision is correct, does not enter the criterion.

seed

Integer scalar or NULL. Random seed. When NULL the current state of the random number generator is used. The state of the calling session is restored on exit. Defaults to 123.

Details

Every cohort is treated at the current dose and its outcomes are observed before the next decision, which follows boin_et_decision_table. After each cohort the admissibility of every dose is re-derived from its data, and a dose excluded by its DLT data also excludes every higher dose. The trial stops early when no dose is admissible, or when the dose should be lowered and no admissible dose is found at or below the intended one. When the intended dose is not admissible, an escalation moves to the lowest admissible dose above it, which can only skip a dose excluded by its response data (the next cohort stays when there is none), and a stay or a de-escalation moves to the highest admissible dose below it. An escalation from the highest dose stays there, or ends the trial when that dose is not admissible. The trial also ends once a dose has n_earlystop patients. These two ends are not early stops: the OBD is still selected.

These are the rules of boinet::boinet() with two changes, which follow Takeda et al. (2018), who do not allow dose skipping during escalation, and the later rules of the same group (Takeda et al., 2025, and the 'bfboinet' package). In 'boinet', a dose excluded by its DLT data does not exclude the doses above it, so that an escalation can skip it and reach an untried dose, and an escalation from the highest dose stays there even when it is excluded. boinet_compatible = TRUE applies these rules of 'boinet'.

Each patient draws two uniform variates in enrollment order, the first for the DLT and the second for the response, and a tie under the rule for the neighboring doses draws one more. The 'boinet' package draws its random numbers differently (event times from a copula, and arrival times), so the trials agree with it in distribution, not one by one.

Possible values of stop_reason are "no_admissible_dose", "no_lower_admissible_dose", "n_earlystop", "max_cohorts" and "top_dose_excluded"; the first two are early stops.

Value

An object of class boin_et_trials, which is a list with components

n_pts

Integer matrix, n_trials by number of doses, of patients treated.

n_tox

Integer matrix of the same shape, of DLTs observed.

n_resp

Integer matrix of the same shape, of responses observed.

cohorts_used

Integer vector of cohorts enrolled in each trial.

stop_reason

Character vector giving why each trial ended.

early_stop

Logical vector, TRUE for the trials stopped early, which select no OBD.

design

"BOIN-ET".

boundary

The boin_et_boundary object used.

settings

List of the design parameters.

References

Takeda, K., Taguri, M. and Morita, S. (2018). BOIN-ET: Bayesian optimal interval design for dose finding based on both efficacy and toxicity outcomes. Pharmaceutical Statistics, 17(4), 383-395. doi:10.1002/pst.1864

Takeda, K., Zhu, J. and Hirakawa, A. (2025). BF-BOIN-ET: A backfill Bayesian optimal interval design using efficacy and toxicity outcomes for dose optimization. Pharmaceutical Statistics, 24, e2470. doi:10.1002/pst.2470

Yamaguchi, Y., Takeda, K. and Maruo, K. (2025). boinet: An R Package for Bayesian Optimal Interval Design for Dose Finding Based on Both Efficacy and Toxicity Outcomes. The R Journal, 17(2), 15-34. doi:10.32614/RJ-2025-012

See Also

sim_boin_et, boin_et_select_obd

Examples

trials <- boin_et_simulate(
  target = 0.30, target_resp = 0.60,
  p_true = c(0.05, 0.15, 0.25, 0.30, 0.35, 0.40),
  p_resp = c(0.05, 0.35, 0.55, 0.65, 0.75, 0.70),
  n_cohort = 12, cohort_size = 3, n_trials = 200, seed = 123
)
trials

head(trials$n_resp)
table(trials$stop_reason)


Select the Optimal Dose Combination of BOIN-ETC Trials

Description

Select the optimal dose combination (ODC) of one or more trials of the BOIN-ETC design of Kakizume et al. (2024) from their final data. The DLT rates are made monotone along both drugs by bivariate isotonic regression, the maximum tolerated dose combination (MTDC) of every row bounds the candidates of that row, and the ODC is the candidate with the highest estimated utility.

Usage

boin_etc_select_obd(
  n_pts,
  n_tox,
  n_resp,
  n_tox_resp = NULL,
  target,
  psi00 = 40,
  psi11 = 60,
  utility_prior = c(1, 1),
  odc_tie = c("lowest", "all"),
  cutoff_eli = 0.95,
  p_eli = NULL,
  excluded = NULL,
  early_stop = NULL
)

Arguments

n_pts, n_tox, n_resp

Numeric matrices for a single trial, with one row per level of drug A and one column per level of drug B, or arrays with dimensions trial by level of drug A by level of drug B, of the patients treated, the DLTs and the responses.

n_tox_resp

Array or matrix of the same size, or NULL. Patients with both a DLT and a response. Needed only when psi00 + psi11 is not 100. Defaults to NULL.

target

Numeric scalar. Target DLT probability, phi.

psi00, psi11

Numeric scalars from 0 to 100. Utilities of a patient with neither a DLT nor a response and with both; a response without DLT scores 100 and a DLT without response 0. Default to 40 and 60, the utilities (100, 40, 60, 0) of Kakizume et al. (2024).

utility_prior

Numeric vector of two positive numbers. Beta prior of the utility of a combination divided by 100. Defaults to c(1, 1).

odc_tie

Character scalar. How tied candidates are reported: "lowest" (the default) selects the one with the lowest sum of the two levels; "all" also marks every tied candidate in tied, which sim_boin_etc then counts as selected, as Kakizume et al. (2024) do. The ODC returned in obd_a and obd_b is the same in both cases.

cutoff_eli, p_eli

As in boin_etc_simulate. Used only when excluded is NULL.

excluded

Logical array or matrix of the same size, or NULL. Combinations excluded by the DLT rule during the trial (component excluded of boin_etc_simulate), which are never selected. Defaults to NULL: a combination is excluded when its own final DLT data fail the rule of cutoff_eli.

early_stop

Logical vector or NULL. Trials stopped early, which select no ODC. Defaults to NULL, no trial.

Details

The DLT rate of every combination, tried or not, is estimated by (y + 0.05) / (n + 0.1) (the beta(0.05, 0.05) posterior mean of Kakizume et al., 2024) and made non-decreasing in both levels by the unweighted least-squares fit of bivariate isotonic regression, as in the code of the authors (Iso::biviso() without weights), computed by the algorithm of Dykstra and Robertson (1982) until no estimate changes by 1e-13 in a cycle. In every row (level of drug A) the MTDC is the combination whose estimate is closest to target; among combinations within 1e-8 of the smallest distance, which are tied in exact arithmetic, the highest level of drug B. The candidates are the tried combinations that are not excluded and not above the MTDC of their row.

The utility of a candidate is estimated by 100 * (q + a) / (n + a + b), with (a, b) the utility_prior and the quasi-binomial number of events q = (100 x + psi00 (n - y - x) + (psi00 + psi11 - 100) z) / 100 of n patients with y DLTs, x responses and z both, the estimate of the code of the authors (Kakizume et al., 2024, do not state it). The ODC is the candidate with the highest estimate; the candidates within 1e-6 of it are tied, and the one with the lowest sum of the levels, then the first in column-major order, is selected.

The code of the authors also lets untried combinations (utility 50) and excluded ones be selected, and counts every tied combination; on the published trials, leaving out the untried ones changes the selection of 0.0 to 0.3 0.14 errors of about 1e-6, so that which of tied MTDCs it takes depends on them; the published percentages of trials selecting a correct ODC are on average about 1 point lower than with exact ties (see inst/reproduce/reproduce_Kakizume2024.R).

Value

A list with components

obd_a, obd_b

Integer vectors, the levels of drug A and drug B of the ODC of every trial (NA when none is selected).

n_tied

Integer vector, the number of tied candidates.

tied

Logical array, the tied candidates of every trial (with odc_tie = "lowest", only the selected ODC).

mtd_col

Integer matrix, trial by level of drug A, the level of drug B of the MTDC of every row.

reason

Character vector: "selected", "early_stop" or "no_admissible_dose".

tox_est

Array of the isotonic estimates of the DLT rates.

utility

Array of the estimated utilities of the tried combinations, on the scale 0 to 100.

References

Kakizume, T., Takeda, K., Taguri, M. and Morita, S. (2024). BOIN-ETC: A Bayesian optimal interval design considering efficacy and toxicity to identify the optimal dose combinations. Statistical Methods in Medical Research, 33(4), 716-727. doi:10.1177/09622802241236936

Dykstra, R. L. and Robertson, T. (1982). An algorithm for isotonic regression for two or more independent variables. The Annals of Statistics, 10(3), 708-716. doi:10.1214/aos/1176345866

See Also

sim_boin_etc, boin_etc_simulate

Examples

n_pts <- matrix(c(3, 6, 0, 9, 6, 3), nrow = 2)
n_tox <- matrix(c(0, 1, 0, 2, 2, 2), nrow = 2)
n_resp <- matrix(c(0, 2, 0, 5, 4, 2), nrow = 2)
boin_etc_select_obd(n_pts, n_tox, n_resp, target = 0.30)


Simulate BOIN-ETC Trials

Description

Simulate trials of the BOIN-ETC design of Kakizume et al. (2024), which finds the optimal dose combination of two drugs given together by dividing the dose matrix into subtrials along which the DLT probability increases (the waterfall approach) and running the BOIN-ET design of Takeda et al. (2018) within each subtrial. Return the patients, DLTs and responses at every combination. This is the simulation engine behind sim_boin_etc.

Usage

boin_etc_simulate(
  target,
  target_resp,
  p_true,
  p_resp,
  n_cohort,
  cohort_size,
  n_trials = 10000,
  subtrials = c("etc1", "etc2", "etc3"),
  n_earlystop = 6,
  etc1_start = c("diagonal", "below"),
  rule4 = c("paper", "authors_code"),
  p_saf = NULL,
  p_tox = NULL,
  p_saf_resp = NULL,
  prior = rep(1/6, 6),
  cutoff_eli = 0.95,
  p_eli = NULL,
  resp_cor = 0,
  resp_cor_type = c("copula", "binary"),
  seed = 123
)

Arguments

target

Numeric scalar. Target DLT probability, phi.

target_resp

Numeric scalar. Target response probability, delta, as in sim_boin_et.

p_true

Numeric matrix. True DLT probability of every combination, with one row per level of drug A and one column per level of drug B. At least two levels of each drug.

p_resp

Numeric matrix of the same size. True response probability of every combination.

n_cohort

Integer scalar. Number of cohorts in a trial; with cohort_size it gives the maximum sample size.

cohort_size

Integer scalar or vector. Number of patients per cohort. A scalar is used for every cohort; a shorter vector is padded with its last element.

n_trials

Integer scalar. Number of trials to simulate. Defaults to 10000.

subtrials

Character scalar. The division of the dose matrix into subtrials and their starting combinations: "etc1" (the default), "etc2" or "etc3", BOIN-ETC1, 2 and 3 of the figures and tables of Kakizume et al. (2024). See Details.

n_earlystop

Integer scalar. A subtrial ends when the combination chosen for the next cohort has this many patients (n_stop of Kakizume et al., 2024). Defaults to 6.

etc1_start

Character scalar. Starting combination of a row subtrial of "etc1": "diagonal" (the default) one level of drug B below the candidate of the previous subtrial, as the text and the figures of Kakizume et al. (2024) state; "below" the same level of drug B, the rule of the code of the authors that produced their published results. See Details.

rule4

Character scalar. Choice among the neighboring combinations when the DLT rate is between lambda1 and lambda2 and the response rate at most eta1: "paper" (the default) the rule of the text; "authors_code" the rule of the code of the authors, needed to reproduce their results for BOIN-ETC1. See Details.

p_saf, p_tox, p_saf_resp, prior

Design parameters of the BOIN-ET boundaries, as in boin_et_boundary. The defaults give (lambda1, lambda2, eta1) = (0.14, 0.35, 0.48) for a target DLT probability of 0.30 and a target response probability of 0.60.

cutoff_eli

Numeric scalar. A combination is excluded, with the higher combinations of its subtrial, when the posterior probability that its DLT rate exceeds p_eli is above this cutoff. Defaults to 0.95.

p_eli

Numeric scalar or NULL. DLT probability of the exclusion rule. Defaults to NULL, target.

resp_cor

Numeric scalar between -1 and 1. Correlation between the DLT and the response of a patient, see resp_cor_type. Defaults to 0, as in the simulations of Kakizume et al. (2024); the BOIN-ET functions default to 0.2.

resp_cor_type

Character scalar. "copula" (the default) or "binary", as in sim_boin_et.

seed

Integer scalar or NULL. Random seed. The state of the calling session is restored on exit. Defaults to 123.

Details

With L levels of drug A and M of drug B (AaBb is the combination of level a of drug A and level b of drug B), the first subtrial is A1B1, A2B1, ..., ALB1, ALB2, ..., ALBM, started at A1B1. Then:

"etc1", "etc2"

one subtrial per row l = L - 1, ..., 1, AlB2, ..., AlBM. When the candidate of the first subtrial is AlB1, the rows start at row l - 1 (at row 1 when l is 1) and the rows above are skipped. "etc2" starts every row at its lowest combination. "etc1" starts the row below the candidate AlBm of the previous subtrial at level m - 1 of drug B (etc1_start = "diagonal") or at level m ("below"), and at level 2 when that level is 1, after a candidate in the first column and after a subtrial that ended without one.

"etc3"

L-shaped subtrials j = 1, ..., min(L, M) - 1: column j + 1 of drug B from level 1 of drug A up to level L - j, then row L - j from column j + 2 to M, each started at its lowest combination. With L > M the shapes run out of columns after M - 1 of them, which still covers the matrix.

Within a subtrial, after each cohort at a combination with DLT rate p and response rate q: the combination and the higher combinations of the subtrial are excluded when its DLT data fail the rule of cutoff_eli; the subtrial ends without a candidate when its lowest combination is excluded, and the trial ends when that combination is A1B1. Otherwise the next cohort escalates when p <= lambda1 and q <= eta1 (it stays at the highest combination of the subtrial and below an excluded one), de-escalates when p >= lambda2 (it stays at the lowest), stays when q > eta1, and otherwise (rule 4) goes to the next combination up if it has not been treated, or else to the treated, not excluded combination of the current one and its two neighbors in the subtrial with the highest response rate, a tie being broken at random. The subtrial ends when the combination chosen for the next cohort has n_earlystop patients (that combination is the candidate of the subtrial), and the trial ends when all cohorts have been enrolled or all subtrials have been run.

Kakizume et al. (2024) do not state the rules in every case; the following were checked against their code and their published results (inst/reproduce/reproduce_Kakizume2024.R):

The response of a patient does not exclude a combination, as in Kakizume et al. (2024). Each patient draws two uniform variates in enrollment order, the first for the DLT and the second for the response; a tie under rule 4 draws one more after the cohort.

Value

An object of class boin_etc_trials, which is a list with components

n_pts, n_tox, n_resp, n_tox_resp

Integer arrays with dimensions trial by level of drug A by level of drug B, of the patients treated, the DLTs, the responses and the patients with both a DLT and a response.

excluded

Logical array of the same dimensions, TRUE for the combinations excluded by the DLT rule during the trial.

cohorts_used, n_subtrials

Integer vectors of the cohorts enrolled and of the subtrials run.

stop_reason

Character vector: "lowest_excluded" (the lowest combination was excluded), "subtrials_completed" or "max_cohorts" (the maximum sample size was reached).

early_stop

Logical vector, TRUE for the trials stopped because the lowest combination was excluded. These trials select no optimal dose combination.

design

"BOIN-ETC1", "BOIN-ETC2" or "BOIN-ETC3".

boundary

List with lambda1, lambda2 and eta1.

settings

List of the design parameters.

References

Kakizume, T., Takeda, K., Taguri, M. and Morita, S. (2024). BOIN-ETC: A Bayesian optimal interval design considering efficacy and toxicity to identify the optimal dose combinations. Statistical Methods in Medical Research, 33(4), 716-727. doi:10.1177/09622802241236936

Takeda, K., Taguri, M. and Morita, S. (2018). BOIN-ET: Bayesian optimal interval design for dose finding based on both efficacy and toxicity outcomes. Pharmaceutical Statistics, 17(4), 383-395. doi:10.1002/pst.1864

See Also

sim_boin_etc, boin_etc_select_obd, boin_et_simulate

Examples

# Scenario 1 of Kakizume et al. (2024)
p_true <- matrix(c(0.05, 0.10, 0.10, 0.30, 0.30, 0.50), nrow = 2)
p_resp <- matrix(c(0.10, 0.25, 0.25, 0.60, 0.60, 0.65), nrow = 2)
trials <- boin_etc_simulate(
  target = 0.30, target_resp = 0.60, p_true = p_true, p_resp = p_resp,
  n_cohort = 8, cohort_size = 3, n_trials = 200, seed = 123
)
trials


Isotonic Estimates of the DLT Probability

Description

Estimate the DLT probability at each dose under the constraint that toxicity does not decrease with dose, using the pool adjacent violators algorithm.

Usage

boin_isotonic(n_pts, n_tox, admissible = NULL)

Arguments

n_pts

Integer matrix with one row per trial and one column per dose, or a vector for a single trial, giving the number of patients treated.

n_tox

Integer matrix or vector of the same shape as n_pts, giving the number of DLTs observed.

admissible

Logical matrix of the same shape as n_pts, or NULL. Doses that are FALSE are left out of the estimation and returned as NA. Defaults to all doses that have treated at least one patient.

Details

Pseudo-counts of 0.05 DLTs and 0.1 patients are added before the fit, and doses are pooled with inverse variance weights. Doses left out through admissible do not influence the estimates of the remaining doses, which matters when eliminated doses must be excluded before selecting the MTD.

Value

A numeric matrix with one row per trial and one column per dose. Doses that did not enter the estimation are NA.

References

Liu S. and Yuan, Y. (2015). Bayesian Optimal Interval Designs for Phase I Clinical Trials. Journal of the Royal Statistical Society: Series C, 64, 507-523.

See Also

boin_select_mtd

Examples

# A single trial
boin_isotonic(n_pts = c(3, 6, 9, 12), n_tox = c(0, 1, 3, 4))

# Several trials at once
n_pts <- matrix(c(3, 6, 9, 12,
                  3, 6, 9, 12,
                  3, 6, 9, 12), nrow = 3, byrow = TRUE)
n_tox <- matrix(c(0, 1, 3, 4,
                  0, 0, 2, 3,
                  1, 2, 4, 6), nrow = 3, byrow = TRUE)
boin_isotonic(n_pts, n_tox)


Escalation and De-escalation Interval Boundaries

Description

Compute the two boundaries that define the BOIN decision interval. A dose is escalated when the observed DLT rate falls at or below lambda_e and de-escalated when it reaches lambda_d.

Usage

boin_lambda(target, p_saf = NULL, p_tox = NULL)

Arguments

target

Numeric scalar. Target DLT probability, for example 0.30.

p_saf

Numeric scalar. Highest DLT probability deemed subtherapeutic, so that dose escalation should be undertaken. Defaults to 0.6 * target.

p_tox

Numeric scalar. Lowest DLT probability deemed overly toxic, so that dose de-escalation is required. Defaults to 1.4 * target.

Details

The boundaries minimize the probability of incorrect dose assignment under a three-point hypothesis on the DLT probability at the current dose. Values of p_saf and p_tox close to target should be avoided, because the sample sizes of phase I trials cannot distinguish the target rate from rates close to it.

Value

A list with components lambda_e and lambda_d.

References

Liu S. and Yuan, Y. (2015). Bayesian Optimal Interval Designs for Phase I Clinical Trials. Journal of the Royal Statistical Society: Series C, 64, 507-523.

Examples

boin_lambda(target = 0.30)

boin_lambda(target = 0.25, p_saf = 0.12, p_tox = 0.40)


Toxic Threshold Giving a Required De-escalation Boundary

Description

Find the value of p_tox for which the BOIN de-escalation boundary lambda_d equals a required value. This inverts boin_lambda, which maps p_tox to lambda_d.

Usage

boin_p_tox(target, lambda_d)

Arguments

target

Numeric scalar. Target DLT probability.

lambda_d

Numeric scalar. Required de-escalation boundary. Must lie strictly between target and 1.

Details

lambda_d increases strictly with p_tox, from target in the limit as p_tox approaches target to 1 in the limit as p_tox approaches 1, so the solution exists and is unique for any lambda_d strictly between those bounds. The root is found numerically.

A boundary close to the target needs a toxic threshold close to the target, and the rest of the package refuses a p_tox within ten percent of target, on the grounds that phase I sample sizes cannot tell the two rates apart. The value is still returned, since the inversion is well defined, but a warning names the smallest boundary that leaves a usable threshold. For a target of 0.30 that smallest boundary is about 0.315.

A design team that wants to tighten the de-escalation boundary usually states the boundary rather than the threshold behind it. This function turns that statement into the p_tox to pass to the other functions, so that the whole design follows from it.

Value

A numeric scalar, the value of p_tox that produces lambda_d.

See Also

boin_lambda, boin_boundary

Examples

# A target of 0.30 gives a de-escalation boundary of 0.359 by default
boin_lambda(target = 0.30)$lambda_d

# The toxic threshold that tightens it to 0.33
p_tox <- boin_p_tox(target = 0.30, lambda_d = 0.33)
p_tox

# which is what it claims to be
boin_lambda(target = 0.30, p_tox = p_tox)$lambda_d

# A boundary too close to the target leaves an unusable threshold, and says so
boin_p_tox(target = 0.30, lambda_d = 0.31)

# and shifts the de-escalation boundary down by one DLT at every cohort end
as.data.frame(boin_boundary(0.30, 18))[seq(3, 18, 3), ]
as.data.frame(boin_boundary(0.30, 18, p_tox = p_tox))[seq(3, 18, 3), ]


Select the MTD from Completed Trials

Description

Choose the maximum tolerated dose for each of a set of completed trials from the final patient and DLT counts.

Usage

boin_select_mtd(
  n_pts,
  n_tox,
  target,
  cutoff_eli = 0.95,
  extrasafe = FALSE,
  offset = 0.05,
  bound_mtd = FALSE,
  p_tox = NULL,
  mtd_max_estimate = NULL,
  min_mtd_sample = 1
)

Arguments

n_pts

Integer matrix with one row per trial and one column per dose, or a vector for a single trial, giving the number of patients treated.

n_tox

Integer matrix or vector of the same shape as n_pts, giving the number of DLTs observed.

target

Numeric scalar. Target DLT probability.

cutoff_eli

Numeric scalar. Posterior probability cutoff for dose elimination. Defaults to 0.95.

extrasafe

Logical scalar. Apply the stricter safety rule at the lowest dose, in which case no dose is selected when the lowest dose is judged too toxic. Defaults to FALSE.

offset

Numeric scalar between 0 and 0.5. Amount by which cutoff_eli is relaxed for the safety rule. Defaults to 0.05.

bound_mtd

Logical scalar. Require the isotonic estimate at the selected dose to be at or below the de-escalation boundary. Defaults to FALSE.

p_tox

Numeric scalar. Lowest DLT probability deemed overly toxic, used to derive the de-escalation boundary when bound_mtd is TRUE. Defaults to 1.4 * target.

mtd_max_estimate

Numeric scalar or NULL. Largest isotonic estimate a dose may have and still be selected. Supplying it bounds the selection whatever bound_mtd says, and replaces the de-escalation boundary that bound_mtd would otherwise use. Defaults to NULL.

min_mtd_sample

Integer scalar. Smallest number of patients a dose must have received to be eligible. Defaults to 1, which admits every dose that treated a patient.

Details

Dose elimination is re-derived from the final data of each trial rather than carried over from the dose-finding stage, which is what the reference implementation does and which matters when a trial ends at its maximum sample size. The isotonic fit is computed over the admissible doses only, so that eliminated doses do not influence the estimates of the doses that remain. The dose whose estimate is closest to target is selected, with ties broken by a small increasing perturbation across the admissible doses.

bound_mtd caps the estimate at the de-escalation boundary, which always lies above target. A cap at or below the target rate therefore cannot be expressed that way, and needs mtd_max_estimate. The two caps are independent of the decision table, so bounding the selection does not change how the trial was run.

Values of reason are "selected", "lowest_dose_eliminated", "no_admissible_dose" and "no_dose_below_bound".

Value

A data frame with one row per trial and columns

trial

Trial index.

mtd

Selected dose level, or NA when no dose is selected.

reason

Why the dose was or was not selected.

References

Liu S. and Yuan, Y. (2015). Bayesian Optimal Interval Designs for Phase I Clinical Trials. Journal of the Royal Statistical Society: Series C, 64, 507-523.

See Also

boin_isotonic, boin_simulate

Examples

n_pts <- matrix(c(3, 6, 9, 3,
                  3, 6, 9, 3), nrow = 2, byrow = TRUE)
n_tox <- matrix(c(0, 1, 3, 2,
                  0, 1, 2, 1), nrow = 2, byrow = TRUE)

boin_select_mtd(n_pts, n_tox, target = 0.30)

boin_select_mtd(n_pts, n_tox, target = 0.30, bound_mtd = TRUE)

# Require the isotonic estimate at the selected dose to be at most 0.30,
# which the de-escalation boundary cannot express
boin_select_mtd(n_pts, n_tox, target = 0.30, mtd_max_estimate = 0.30)


Simulate BOIN Trials

Description

Run the BOIN dose-finding algorithm over many simulated trials and return the patient and DLT counts at every dose. This is the simulation engine behind sim_boin, exposed for users who want the raw trial data.

Usage

boin_simulate(
  target,
  p_true,
  n_cohort,
  cohort_size,
  n_trials = 10000,
  start_dose = 1,
  n_earlystop = 18,
  p_saf = NULL,
  p_tox = NULL,
  cutoff_eli = 0.95,
  extrasafe = FALSE,
  offset = 0.05,
  titration = FALSE,
  stay_on_1_of_3 = FALSE,
  n_earlystop_rule = c("with_stay", "simple"),
  seed = 123,
  titration_doses = NULL
)

Arguments

target

Numeric scalar. Target DLT probability, for example 0.30.

p_true

Numeric vector. True DLT probability at each dose level, in increasing dose order.

n_cohort

Integer scalar. Number of cohorts in a trial.

cohort_size

Integer scalar or vector. Number of patients per cohort. A scalar is used for every cohort. A vector shorter than n_cohort is padded with its last element and a longer one is truncated.

n_trials

Integer scalar. Number of trials to simulate. Defaults to 10000.

start_dose

Integer scalar. Dose level for the first cohort. Defaults to 1. It is ignored when titration is TRUE, because the titration phase always begins at the lowest dose.

n_earlystop

Integer scalar. The trial stops once this many patients have been treated at the current dose and the design would stay there. Defaults to 18.

p_saf

Numeric scalar. Highest DLT probability deemed subtherapeutic. Defaults to 0.6 * target.

p_tox

Numeric scalar. Lowest DLT probability deemed overly toxic. Defaults to 1.4 * target.

cutoff_eli

Numeric scalar. Posterior probability cutoff for dose elimination. Defaults to 0.95.

extrasafe

Logical scalar. Apply the stricter safety stopping rule at the lowest dose. Defaults to FALSE.

offset

Numeric scalar between 0 and 0.5. Amount by which cutoff_eli is relaxed for the safety stopping rule. Defaults to 0.05.

titration

Logical scalar. Start with single patient cohorts until the first DLT is seen. Ignored when the first cohort size is one. Defaults to FALSE.

stay_on_1_of_3

Logical scalar. When TRUE, one DLT out of three patients leads to staying at the current dose rather than de-escalating. Defaults to FALSE. See boin_boundary.

n_earlystop_rule

Character scalar, either "with_stay" or "simple". Under "with_stay" the trial stops at n_earlystop only when the design would remain at the current dose, which is the rule used by the reference implementation. Under "simple" it stops as soon as the threshold is reached.

seed

Integer scalar or NULL. Random seed. When NULL the current state of the random number generator is used. The state of the calling session is restored on exit. Defaults to 123.

titration_doses

Integer scalar or NULL. Highest dose level that the titration treats with single patients. When no DLT is seen up to this dose, the next cohort, of full size, is treated at the dose above it, as in the accelerated BOIN design of Kojima et al. (2024). Needs titration = TRUE. Defaults to NULL, every dose, the titration of the BOIN package. When it is set, a value of n_earlystop of 6 or less, which the accelerated design uses, gives no warning.

Details

One uniform variate is drawn per patient, in enrollment order. Two details matter for reproducibility: the titration phase draws one variate per dose level whether or not it is used, and a cohort cut short by the maximum sample size still draws a full cohort's worth. This is the random number consumption of BOIN::get.oc(), so with the same seed and matching arguments a run reproduces the reference implementation trial by trial.

Possible values of stop_reason are "lowest_dose_eliminated", "lowest_dose_too_toxic", "n_earlystop", "max_sample_size" and "max_cohorts".

Value

An object of class boin_trials, which is a list with components

n_pts

Integer matrix, n_trials by number of doses, of patients treated.

n_tox

Integer matrix of the same shape, of DLTs observed.

eliminated

Logical matrix of the same shape, marking doses eliminated during the trial.

cohorts_used

Integer vector of cohorts completed in each trial.

stop_reason

Character vector giving why each trial ended.

boundary

The boin_boundary object used.

settings

List of the design parameters.

References

Liu S. and Yuan, Y. (2015). Bayesian Optimal Interval Designs for Phase I Clinical Trials. Journal of the Royal Statistical Society: Series C, 64, 507-523.

Kojima, M., Wende, W. and Zhao, H. (2024). Tips for Accelerating BOIN Design. Therapeutic Innovation and Regulatory Science, 58, 1129-1137. doi:10.1007/s43441-024-00692-9

See Also

sim_boin, boin_select_mtd

Examples

trials <- boin_simulate(
  target = 0.30,
  p_true = c(0.05, 0.15, 0.30, 0.45, 0.60),
  n_cohort = 10,
  cohort_size = 3,
  n_trials = 200,
  seed = 123
)
trials

head(trials$n_pts)
table(trials$stop_reason)


Safety Stopping Boundary as a Two-Row Table

Description

Present the safety stopping boundary at the lowest dose as a compact table with one column per sample size, which is the shape usually wanted in a protocol or a report.

Usage

boin_stopping_table(x, cohort_size = NULL)

Arguments

x

An object of class boin_boundary, built with extrasafe = TRUE.

cohort_size

Integer scalar or NULL. When supplied, only the sample sizes that are multiples of cohort_size are kept.

Details

The same numbers are available one row per sample size from as.data.frame() on the boundary object. This function transposes them and labels the rows, which suits a table pasted into a document or rendered with knitr::kable() or DT::datatable().

Value

A data frame with two rows, labeled by the quantity they hold, and one column per sample size. Sample sizes at which no number of DLTs triggers the rule are dropped.

See Also

boin_boundary

Examples

bd <- boin_boundary(target = 0.30, max_n = 18, extrasafe = TRUE)

boin_stopping_table(bd)

# Only the sample sizes reached at the end of a cohort of three
boin_stopping_table(bd, cohort_size = 3)


Select the OBD Combination of Comb-BOIN12 Trials

Description

Select the optimal biological dose combination (OBDC) of one or more trials of the Comb-BOIN12 design of Lu et al. (2025) from their final data. The DLT rates are made monotone along both drugs by bivariate isotonic regression, the maximum tolerated dose combination (MTDC) bounds the candidates, and the OBDC is the admissible candidate with the highest estimated utility.

Usage

comb_boin12_select_obd(
  n_pts,
  n_tox,
  n_resp,
  target,
  target_resp,
  cutoff_eli = 0.95,
  cutoff_eli_resp = 0.9,
  extrasafe = FALSE,
  offset = 0.05,
  psi00 = 40,
  psi11 = 60,
  est_method = c("logistic", "observed"),
  obd_bound = c("rectangle", "contour"),
  dose_a = NULL,
  dose_b = NULL,
  logistic_scale = c(2.5, 2.5),
  n_draws = 4000,
  early_stop = NULL
)

Arguments

n_pts, n_tox, n_resp

Numeric matrices for a single trial, with one row per level of drug A and one column per level of drug B, or arrays with dimensions trial by level of drug A by level of drug B, of the patients treated, the DLTs and the responses.

target, target_resp, cutoff_eli, cutoff_eli_resp, extrasafe, offset

As in comb_boin12_simulate. The admissibility of the combinations is judged again from the final data with the same rules.

psi00, psi11

Numeric scalars from 0 to 100. Utilities of a patient with neither a DLT nor a response and with both, as in sim_boin12. Default to 40 and 60.

est_method

Character scalar. Estimate of the response probability: "logistic" (the default) the posterior mean under the logistic model of Lu et al. (2025), see Details; "observed" the observed response rate.

obd_bound

Character scalar. Combinations from which the OBDC is chosen: "rectangle" (the default) those with both levels at most those of the MTDC, as Lu et al. (2025) write; "contour" those, in every column (level of drug B), at most the combination of that column whose isotonic DLT rate is closest to target, the rule that reproduces the results published by Lu et al. (2025). See Details.

dose_a, dose_b

Numeric vectors or NULL. Dose values of the levels of drug A and of drug B in the logistic model. Default to NULL, the level numbers. Each is standardized to mean 0 and standard deviation 0.5.

logistic_scale

Numeric vector of two positive numbers. Scales of the Cauchy priors of the intercept and of the other coefficients of the logistic model. Defaults to c(2.5, 2.5), as in Lu et al. (2025).

n_draws

Integer scalar. Number of points of the importance sampling of the logistic model. Defaults to 4000.

early_stop

Logical vector or NULL. Trials stopped early, which select no OBDC. Defaults to NULL, no trial.

Details

The DLT rates are estimated by (y + 0.05) / (n + 0.1) with weights n + 0.1, as in comb_boin_select_mtd, and made non-decreasing in both levels by the weighted least-squares fit of bivariate isotonic regression, computed by the algorithm of Dykstra and Robertson (1982) until no estimate changes by 1e-13 in a cycle. The MTDC is the tried combination whose estimate, plus 1e-5 times the sum of its two levels, is closest to target: below the target the small amount favors the higher combination, above it the lower one. Among combinations whose distances differ by at most 1e-8, such as two combinations with the same sum of levels in one block of the isotonic regression, the first in column-major order is the MTDC. Untried combinations are never selected.

The utility of a combination is estimated by 100 * pE * (1 - pT) + psi00 * (1 - pT) * (1 - pE) + psi11 * pT * pE, with pT the isotonic estimate and pE the estimate of est_method. When psi00 + psi11 is 100 it is a linear function of pE - wT * pT, the estimated utility of Lu et al. (2025), with wT = psi00 / psi11. The OBDC is the admissible tried candidate with the highest estimate; among the candidates within 1e-6 of it, the one with the lowest sum of the levels and then the first in column-major order.

Lu et al. (2025) state the candidates as the combinations (j, k) with j and k at most the levels of the MTDC. Applied to the trials that reproduce their allocation percentages, that rule gives selection percentages far from those published; obd_bound = "contour", which bounds every level of drug B by its own MTD along drug A, agrees with their Figure 2 and Supplementary Figure S2 (see inst/reproduce/reproduce_Lu2025.R). It treats the two drugs differently.

The logistic model is logit(pE) = g0 + g1 a + g2 b + g3 a^2 + g4 b^2, with a and b the standardized doses (mean 0 and standard deviation 0.5 over the levels of each drug, the scaling of Gelman et al., 2008, for these priors; Lu et al., 2025, do not state one) and independent Cauchy priors centered at 0. Lu et al. draw the posterior with Gibbs sampling; here its mean is computed by importance sampling with n_draws Halton points: the proposal is a multivariate t distribution with 4 degrees of freedom centered at the posterior mode, with the inverse of the negative Hessian as scale matrix, and it is fitted twice more to the weighted mean and covariance of the weighted points. No random number is used, so that the selection does not change the random number stream. In checks against long Markov chain Monte Carlo runs the estimates were within 0.01.

Value

A list with components

obd_a, obd_b

Integer vectors, the levels of drug A and drug B of the OBDC of every trial (NA when none is selected).

mtd_a, mtd_b

Integer vectors, the levels of the MTDC.

reason

Character vector: "selected", "early_stop" or "no_admissible_dose".

tox_est

Array of the isotonic estimates of the DLT rates.

resp_est

Array of the estimates of the response probabilities of the tried combinations (NA elsewhere and for the trials with no selection).

utility

Array of the estimated utilities of the tried combinations, on the scale 0 to 100.

References

Lu, M., Zhang, J., Yuan, Y. and Lin, R. (2025). Comb-BOIN12: A utility-based Bayesian optimal interval design for dose optimization in cancer drug-combination trials. Statistics in Biopharmaceutical Research, 17(2), 266-276. doi:10.1080/19466315.2024.2370403

Gelman, A., Jakulin, A., Pittau, M. G. and Su, Y.-S. (2008). A weakly informative default prior distribution for logistic and other regression models. The Annals of Applied Statistics, 2(4), 1360-1383. doi:10.1214/08-AOAS191

Dykstra, R. L. and Robertson, T. (1982). An algorithm for isotonic regression for two or more independent variables. The Annals of Statistics, 10(3), 708-716. doi:10.1214/aos/1176345866

See Also

sim_comb_boin12, comb_boin12_simulate

Examples

n_pts <- matrix(c(3, 6, 0, 9, 12, 3), nrow = 2)
n_tox <- matrix(c(0, 1, 0, 1, 2, 1), nrow = 2)
n_resp <- matrix(c(0, 1, 0, 3, 6, 2), nrow = 2)
comb_boin12_select_obd(n_pts, n_tox, n_resp, target = 0.33,
                       target_resp = 0.2)


Simulate Comb-BOIN12 Trials

Description

Simulate trials of the Comb-BOIN12 design of Lu et al. (2025), the extension of BOIN12 to two drugs given together, which assigns each cohort to the most desirable combination by a utility that weighs the response against the DLT, and return the patients, DLTs and responses at every combination. This is the simulation engine behind sim_comb_boin12.

Usage

comb_boin12_simulate(
  target,
  target_resp,
  p_true,
  p_resp,
  n_cohort,
  cohort_size,
  n_trials = 10000,
  start_dose = c(1, 1),
  n_earlystop = NULL,
  n_earlystop_rule = c("with_stay", "simple"),
  p_saf = NULL,
  p_tox = NULL,
  cutoff_eli = 0.95,
  cutoff_eli_resp = 0.9,
  extrasafe = FALSE,
  offset = 0.05,
  psi00 = 40,
  psi11 = 60,
  benchmark_weight = 0.5,
  utility_prior = c(1, 1),
  n_star = 6,
  tie_break = c("higher", "random"),
  no_candidate = c("nearest", "stop"),
  resp_cor = 0,
  resp_cor_type = c("copula", "binary"),
  seed = 123
)

Arguments

target

Numeric scalar. Highest acceptable DLT probability, phi_T. It is the target of the BOIN boundaries lambda_e and lambda_d, of the admissibility of a combination and of the MTD combination that bounds the OBD combination.

target_resp

Numeric scalar. Lowest acceptable response probability, phi_E, as in sim_boin12.

p_true

Numeric matrix. True DLT probability of every combination, with one row per level of drug A and one column per level of drug B.

p_resp

Numeric matrix of the same size. True response probability of every combination.

n_cohort

Integer scalar. Number of cohorts in a trial.

cohort_size

Integer scalar or vector. Number of patients per cohort. A scalar is used for every cohort; a shorter vector is padded with its last element.

n_trials

Integer scalar. Number of trials to simulate. Defaults to 10000.

start_dose

Integer vector of length 2. Levels of drug A and drug B of the first cohort. Defaults to c(1, 1).

n_earlystop

Integer scalar or NULL. Number of patients at the current combination that ends the trial when the next cohort would stay there (see n_earlystop_rule). Defaults to NULL, which runs every trial to the maximum sample size, as in Lu et al. (2025).

n_earlystop_rule

Character scalar. "with_stay" (the default) ends the trial at n_earlystop only when the next cohort would stay at the current combination; "simple" ends it in any case.

p_saf, p_tox

Numeric scalars or NULL. Highest DLT probability deemed subtherapeutic and lowest deemed overly toxic, which give the BOIN boundaries. Default to 0.6 * target and 1.4 * target.

cutoff_eli

Numeric scalar. A combination is inadmissible, together with every combination with at least the same levels of both drugs, when the posterior probability that its DLT rate exceeds target is at least this cutoff. Defaults to 0.95.

cutoff_eli_resp

Numeric scalar. A combination is inadmissible when the posterior probability that its response rate is below target_resp is at least this cutoff. Defaults to 0.90.

extrasafe

Logical scalar. Apply the cutoff cutoff_eli - offset to the lowest combination, as Lu et al. (2025) do with 0.85. Defaults to FALSE.

offset

Numeric scalar. Amount by which cutoff_eli is lowered at the lowest combination when extrasafe is TRUE. Defaults to 0.05, as in sim_comb_boin; Lu et al. (2025) use 0.10.

psi00, psi11

Numeric scalars from 0 to 100. Utility of a patient without DLT and without response, and with both, as in sim_boin12. Default to 40 and 60. The utility pE - wT * pT of Lu et al. (2025) is psi00 = 100 * wT / (1 + wT) and psi11 = 100 / (1 + wT); their wT = 0.11 is psi00 = 9.90991 and psi11 = 90.09009.

benchmark_weight

Numeric scalar above 0 and at most 1. Weight of the lowest acceptable utility in the utility benchmark, as in sim_boin12; it is the weight w_u of Lu et al. (2025), who use 0.6. Defaults to 0.5.

utility_prior

Numeric vector of two positive numbers. Beta prior of the utility of a combination divided by 100. Defaults to c(1, 1).

n_star

Integer scalar. With at least this many patients at the current combination and a DLT rate between lambda_e and lambda_d, the next combination is chosen from the current one and the two below it. Defaults to 6.

tie_break

Character scalar. Choice among the combinations of equal desirability: "higher" (the default) keeps those with the highest sum of the two levels and draws one of them at random when several remain; "random" draws one of all the tied combinations. See Details.

no_candidate

Character scalar. What happens when none of the combinations allowed for the next cohort is admissible: "nearest" (the default) goes to the admissible combination nearest to the current one; "stop" ends the trial without an OBD combination. See Details.

resp_cor

Numeric scalar between -1 and 1. Correlation between the DLT and the response of a patient, see resp_cor_type. Defaults to 0.

resp_cor_type

Character scalar. "copula" (the default) or "binary", as in sim_boin12.

seed

Integer scalar or NULL. Random seed. The state of the calling session is restored on exit. Defaults to 123.

Details

After each cohort, with phat the DLT rate at the current combination (j, k): the trial stops when no combination is admissible; when phat is at least lambda_d, the next combination is the most desirable of the admissible combinations below (j, k), that is with levels at most j and k, that have the highest sum of the two levels: (j - 1, k) or (j, k - 1) when either is admissible, as in Lu et al. (2025), and lower ones otherwise; the current one when there is none. When phat is above lambda_e and at least n_star patients have been treated, the next combination is the most desirable of (j, k), (j - 1, k) and (j, k - 1); otherwise of (j, k) and its four neighbors (j - 1, k), (j, k - 1), (j + 1, k) and (j, k + 1). Only admissible combinations inside the matrix are considered. When none of these is admissible, the admissible combination nearest to the current one (by the sum of the differences of the two levels) is chosen, then the one with the lowest sum of the levels, then the most desirable. The desirability is that of BOIN12 (boin12_decision_table). Untried combinations have a DLT rate of 0 and are admissible unless excluded by the DLT data of a lower combination.

With no_candidate = "stop", the trial stops instead, without an OBD combination and with the stopping reason "no_admissible_candidate", when none of these combinations is admissible and when phat is at least lambda_d and no combination below the current one is admissible. At the lowest combination, a phat of at least lambda_d still keeps the next cohort there when it is admissible.

Lu et al. (2025) do not state how ties of desirability are broken nor what happens when no candidate is admissible. With tie_break = "higher", among tied combinations those with the highest sum of the levels are kept, so that the design escalates when an untried combination is as desirable as the current one, and a tie that remains (between (j + 1, k) and (j, k + 1), for example) is broken at random. The allocation percentages published by Lu et al. (2025) agree with this rule, and not with a random choice among all the tied combinations nor with a fixed preference for one drug (see inst/reproduce/reproduce_Lu2025.R). The two settings of no_candidate could not be told apart from the published results. With one row or one column, the trials are those of boin12_simulate without its exploration rule; Lu et al. (2025) have no such rule.

When psi00 + psi11 is 100, as for the utility of Lu et al. (2025), the desirability does not depend on the number of patients with both a DLT and a response, and combinations with the same numbers of patients, DLTs and responses tie exactly, whatever the rounding of psi00 and psi11.

Each patient draws two uniform variates in enrollment order, the first for the DLT and the second for the response. A decision between tied combinations draws one more variate when a tie remains after the rule of tie_break.

Value

An object of class comb_boin12_trials, which is a list with components

n_pts, n_tox, n_resp, n_tox_resp

Integer arrays with dimensions trial by level of drug A by level of drug B, of the patients treated, the DLTs, the responses and the patients with both a DLT and a response.

cohorts_used

Integer vector of the cohorts enrolled.

stop_reason

Character vector: "no_admissible_dose", "n_earlystop", "max_cohorts" or "no_admissible_candidate" (only with no_candidate = "stop").

early_stop

Logical vector, TRUE for the trials stopped because no combination was admissible or, with no_candidate = "stop", because no combination allowed for the next cohort was admissible. These trials select no OBD combination.

design

"Comb-BOIN12".

boundary

List with lambda_e, lambda_d, u_low and u_benchmark.

settings

List of the design parameters.

References

Lu, M., Zhang, J., Yuan, Y. and Lin, R. (2025). Comb-BOIN12: A utility-based Bayesian optimal interval design for dose optimization in cancer drug-combination trials. Statistics in Biopharmaceutical Research, 17(2), 266-276. doi:10.1080/19466315.2024.2370403

Lin, R., Zhou, Y., Yan, F., Li, D. and Yuan, Y. (2020). BOIN12: Bayesian optimal interval phase I/II trial design for utility-based dose finding in immunotherapy and targeted therapies. JCO Precision Oncology, 4, 1393-1402. doi:10.1200/PO.20.00257

See Also

sim_comb_boin12, comb_boin12_select_obd, boin12_simulate

Examples

# Scenario 16 of Lu et al. (2025), with their utility (wT = 0.11)
p_true <- matrix(c(0.05, 0.10, 0.15, 0.15, 0.20, 0.45), nrow = 2)
p_resp <- matrix(c(0.10, 0.20, 0.30, 0.40, 0.50, 0.60), nrow = 2)
trials <- comb_boin12_simulate(
  target = 0.33, target_resp = 0.2, p_true = p_true, p_resp = p_resp,
  n_cohort = 14, cohort_size = 3, n_trials = 200,
  psi00 = 100 * 0.11 / 1.11, psi11 = 100 / 1.11, benchmark_weight = 0.6,
  extrasafe = TRUE, offset = 0.10, seed = 123
)
trials


Next Dose Combination in a BOIN Drug-Combination Trial

Description

Decide the dose combination for the next cohort of a trial run with the BOIN drug-combination design of Lin and Yin (2017), from the numbers of patients and DLTs observed so far at every combination and the combination that treated the last cohort. The rules are those of comb_boin_simulate, so the decisions taken during the trial are the ones whose operating characteristics sim_comb_boin reports.

Usage

comb_boin_next(
  target,
  n_pts,
  n_tox,
  current,
  n_earlystop = 18,
  p_saf = NULL,
  p_tox = NULL,
  cutoff_eli = 0.95,
  extrasafe = FALSE,
  offset = 0.05
)

Arguments

target

Numeric scalar. Target DLT probability, for example 0.30.

n_pts

Integer matrix. Number of patients treated so far at each dose combination, with one row per dose level of drug A and one column per dose level of drug B.

n_tox

Integer matrix of the same shape as n_pts. Number of patients with a DLT at each combination.

current

Integer vector of length two. Dose levels of drug A and drug B of the combination that treated the last cohort.

n_earlystop

Integer scalar. The trial stops once this many patients have been treated at the current combination and the design would neither escalate nor de-escalate, or cannot. Defaults to 18. Use the value of the simulations that support the protocol.

p_saf

Numeric scalar. Highest DLT probability deemed subtherapeutic. Defaults to 0.6 * target.

p_tox

Numeric scalar. Lowest DLT probability deemed overly toxic. Defaults to 1.4 * target.

cutoff_eli

Numeric scalar. Posterior probability cutoff for eliminating a combination. Defaults to 0.95.

extrasafe

Logical scalar. Apply the stricter safety stopping rule at the lowest combination. Defaults to FALSE.

offset

Numeric scalar between 0 and 0.5. Amount by which cutoff_eli is relaxed for the safety stopping rule. Defaults to 0.05.

Details

The decision follows the same steps as a simulated trial after each cohort. A combination whose DLT count reaches its elimination boundary is eliminated together with every combination with at least the same level of both drugs, and the trial stops if the lowest combination is eliminated or, with extrasafe, judged too toxic. The trial also stops when n_earlystop patients have been treated at the current combination and the design would neither escalate nor de-escalate. Otherwise the observed DLT rate at the current combination is compared with the boundaries of boin_boundary, and an escalation or a de-escalation moves one level of drug A or of drug B to the candidate with the higher score: the posterior probability, under a Beta(0.5, 0.5) prior, that its DLT rate lies between lambda_e and lambda_d, plus 0.0005 per patient already treated there. An eliminated combination is not a candidate for escalation. When the two scores are equal the design chooses at random, and the function returns both.

During a simulated trial a combination is eliminated as soon as its data reach the boundary and is never treated again, so the combinations eliminated by the data are exactly those eliminated in the course of the trial.

BOIN::next.comb() applies somewhat different rules from the simulations of BOIN::get.oc.comb(): it stops as soon as n.earlystop patients have been treated at the current combination, it does not escalate drug A when a combination with the next level of drug A and at most the current level of drug B has an observed DLT rate at or above lambda_d (and likewise for drug B), and it draws a random number to break ties. This function follows the simulations instead, so that a trial is run with the rules whose operating characteristics were evaluated. Where the rules coincide, the two functions agree.

Value

An object of class comb_boin_next, which is a list with components

decision

One of "escalate", "de-escalate", "stay" and "stop".

next_dose

Integer matrix with columns dose_a and dose_b: one row for the next combination, two rows when two candidates tie, and no row when the trial stops.

tie

Whether two candidates tie, in which case the design picks one of them at random.

stop_reason

NA, or why the trial stops: "lowest_dose_eliminated", "lowest_dose_too_toxic" or "n_earlystop".

note

A sentence explaining a decision to stay when the rule called for a move that is not available, otherwise NA.

candidates

Data frame of the two combinations considered for an escalation or a de-escalation, one level of drug A and one level of drug B away, with their data, the posterior probability that their DLT rate lies between lambda_e and lambda_d, the score used to choose between them and whether they are available; NULL when no move was considered.

eliminated

Logical matrix of the combinations eliminated by the data.

boundary

The escalation, de-escalation and elimination boundaries at the number of patients treated at the current combination.

together with the data, the current combination and the design parameters.

References

Lin, R. and Yin, G. (2017). Bayesian Optimal Interval Design for Dose Finding in Drug-Combination Trials. Statistical Methods in Medical Research, 26(5), 2155-2167.

See Also

plot.comb_boin_next, boin_decision_table, sim_comb_boin

Examples

# Three levels of drug A and four of drug B; the last cohort was treated at
# A2B2, where two of three patients had a DLT
n_pts <- matrix(c(6, 6, 0, 0,
                  3, 3, 0, 0,
                  0, 0, 0, 0), nrow = 3, byrow = TRUE)
n_tox <- matrix(c(0, 1, 0, 0,
                  1, 2, 0, 0,
                  0, 0, 0, 0), nrow = 3, byrow = TRUE)

nxt <- comb_boin_next(target = 0.25, n_pts = n_pts, n_tox = n_tox,
                      current = c(2, 2))
nxt
nxt$next_dose


Select the MTD Combination from Completed Drug-Combination Trials

Description

Choose the maximum tolerated dose combination for each of a set of completed trials of the BOIN drug-combination design from the final patient and DLT counts.

Usage

comb_boin_select_mtd(
  n_pts,
  n_tox,
  target,
  cutoff_eli = 0.95,
  extrasafe = FALSE,
  offset = 0.05,
  bound_mtd = FALSE,
  p_tox = NULL
)

Arguments

n_pts

Integer matrix giving the number of patients treated at each combination of one trial, with one row per dose level of drug A and one column per dose level of drug B, or an integer array with dimensions trial by level of drug A by level of drug B for several trials, as returned by comb_boin_simulate.

n_tox

Integer matrix or array of the same shape as n_pts, giving the number of DLTs observed.

target

Numeric scalar. Target DLT probability.

cutoff_eli

Numeric scalar. Posterior probability cutoff for eliminating a combination. Defaults to 0.95.

extrasafe

Logical scalar. Apply the stricter safety rule at the lowest combination, in which case no combination is selected when it is judged too toxic. Defaults to FALSE.

offset

Numeric scalar between 0 and 0.5. Amount by which cutoff_eli is relaxed for the safety rule. Defaults to 0.05.

bound_mtd

Logical scalar. Require the isotonic estimate at the selected combination to be below the de-escalation boundary. Defaults to FALSE.

p_tox

Numeric scalar. Lowest DLT probability deemed overly toxic, used to derive the de-escalation boundary when bound_mtd is TRUE. Defaults to 1.4 * target.

Details

The selection follows the reference implementation used by BOIN::get.oc.comb(). Elimination is re-derived from the final data: within each row, the first combination with at least three patients whose posterior probability of a DLT rate above target exceeds cutoff_eli is eliminated together with the rest of its row and the rest of its column. If the lowest combination is eliminated, no combination is selected. Otherwise the estimates (y + 0.05) / (n + 0.1) are smoothed by bivariate isotonic regression with weights n + 0.1, so that they increase along every row and column, and the treated, non-eliminated combination whose estimate is closest to target is selected. A small amount, 1e-5 times the sum of the two dose levels, is added to every estimate first, so that among equal estimates the higher combination is selected when they are below target and the lower one when they are above it.

The isotonic regression is Iso::biviso(), the routine the reference implementation calls. Combinations that the regression pools together have equal estimates in exact arithmetic but can differ in the last digits, and with the small amount above, these digits decide between combinations on the same anti-diagonal. Another algorithm for the same regression would therefore select differently in a few trials out of a thousand.

The article of Lin and Yin (2017) estimates the DLT rates as y / n and resolves ties differently; the package follows the reference implementation so that the two can be compared trial by trial.

Values of reason are "selected", "lowest_dose_eliminated" and "no_dose_below_bound".

Value

A data frame with one row per trial and columns

trial

Trial index.

mtd_a

Dose level of drug A in the selected combination, or NA when none is selected.

mtd_b

Dose level of drug B in the selected combination, or NA.

reason

Why a combination was or was not selected.

References

Lin, R. and Yin, G. (2017). Bayesian Optimal Interval Design for Dose Finding in Drug-Combination Trials. Statistical Methods in Medical Research, 26(5), 2155-2167.

See Also

comb_boin_simulate, sim_comb_boin

Examples

n_pts <- matrix(c(3, 6, 3,
                  3, 3, 0), nrow = 2, byrow = TRUE)
n_tox <- matrix(c(0, 1, 1,
                  0, 2, 0), nrow = 2, byrow = TRUE)

comb_boin_select_mtd(n_pts, n_tox, target = 0.30)


Simulate BOIN Drug-Combination Trials

Description

Run the BOIN drug-combination design of Lin and Yin (2017) over many simulated trials of two drugs given together, and return the patient and DLT counts at every dose combination. This is the simulation engine behind sim_comb_boin, exposed for users who want the raw trial data.

Usage

comb_boin_simulate(
  target,
  p_true,
  n_cohort,
  cohort_size,
  n_trials = 10000,
  start_dose = c(1, 1),
  n_earlystop = 18,
  p_saf = NULL,
  p_tox = NULL,
  cutoff_eli = 0.95,
  extrasafe = FALSE,
  offset = 0.05,
  titration = FALSE,
  seed = 123
)

Arguments

target

Numeric scalar. Target DLT probability, for example 0.30.

p_true

Numeric matrix. True DLT probability of each dose combination, with one row per dose level of drug A and one column per dose level of drug B, both in increasing dose order.

n_cohort

Integer scalar. Number of cohorts in a trial.

cohort_size

Integer scalar or vector. Number of patients per cohort. A scalar is used for every cohort. A vector shorter than n_cohort is padded with its last element and a longer one is truncated.

n_trials

Integer scalar. Number of trials to simulate. Defaults to 10000.

start_dose

Integer vector of length two. Dose levels of drug A and drug B for the first cohort. Defaults to c(1, 1). Titration, when requested, also starts here.

n_earlystop

Integer scalar. The trial stops once this many patients have been treated at the current combination and the design would neither escalate nor de-escalate, or cannot. Defaults to 18. Set it to a value above the maximum sample size to switch this rule off.

p_saf

Numeric scalar. Highest DLT probability deemed subtherapeutic. Defaults to 0.6 * target.

p_tox

Numeric scalar. Lowest DLT probability deemed overly toxic. Defaults to 1.4 * target.

cutoff_eli

Numeric scalar. Posterior probability cutoff for eliminating a combination. Defaults to 0.95.

extrasafe

Logical scalar. Apply the stricter safety stopping rule at the lowest combination. Defaults to FALSE.

offset

Numeric scalar between 0 and 0.5. Amount by which cutoff_eli is relaxed for the safety stopping rule. Defaults to 0.05.

titration

Logical scalar. Treat one patient per combination, moving up one level of either drug, until the first DLT, before switching to full cohorts. Ignored when the first cohort size is one. Defaults to FALSE.

seed

Integer scalar or NULL. Random seed. When NULL the current state of the random number generator is used. The state of the calling session is restored on exit. Defaults to 123.

Details

The decision boundaries are those of the single-agent design, from boin_boundary. After each cohort the observed DLT rate at the current combination is compared with them. When the design escalates, the next cohort goes one level up of drug A or of drug B, whichever has the larger posterior probability, under a Beta(0.5, 0.5) prior, that its DLT probability lies between lambda_e and lambda_d; de-escalation chooses one level down in the same way. Eliminated combinations are not escalated to. When a combination is eliminated, so is every combination with at least the same level of both drugs, and the trial stops when the lowest combination is eliminated.

The rules, and the order in which they are applied, are those of BOIN::get.oc.comb() with mtd.contour = FALSE. That implementation adds two things to the article: a candidate's posterior probability is increased by 0.0005 for every patient already treated there, so that ties go to the better informed combination, and the trial can stop at n_earlystop. Random variates are drawn in the same order as there: one per patient, one for the direction of every titration step that can go either way, and one for every escalation or de-escalation that has a candidate, even when there is only one. With the same seed and matching arguments a run therefore reproduces the reference implementation trial by trial.

During titration the patients treated before the first DLT are added to the planned cohorts, as in the reference implementation: the first full cohort only tops up the combination reached. A trial can therefore treat a few more patients than n_cohort cohorts hold.

Possible values of stop_reason are "lowest_dose_eliminated", "lowest_dose_too_toxic", "n_earlystop" and "max_cohorts".

Value

An object of class comb_boin_trials, which is a list with components

n_pts

Integer array of patients treated, with dimensions trial by level of drug A by level of drug B.

n_tox

Integer array of the same shape, of DLTs observed.

eliminated

Logical array of the same shape, marking combinations eliminated during the trial.

cohorts_used

Integer vector of cohorts completed in each trial.

stop_reason

Character vector giving why each trial ended.

boundary

The boin_boundary object used.

settings

List of the design parameters.

References

Lin, R. and Yin, G. (2017). Bayesian Optimal Interval Design for Dose Finding in Drug-Combination Trials. Statistical Methods in Medical Research, 26(5), 2155-2167.

Yan, F., Zhang, L., Zhou, Y., Pan, H., Liu, S. and Yuan, Y. (2020). BOIN: An R Package for Designing Single-Agent and Drug-Combination Dose-Finding Trials Using Bayesian Optimal Interval Designs. Journal of Statistical Software, 94(13), 1-32.

See Also

sim_comb_boin, comb_boin_select_mtd

Examples

p_true <- matrix(c(0.02, 0.04, 0.08, 0.14,
                   0.08, 0.25, 0.42, 0.48,
                   0.25, 0.45, 0.50, 0.60), nrow = 3, byrow = TRUE)

trials <- comb_boin_simulate(
  target = 0.25,
  p_true = p_true,
  n_cohort = 16,
  cohort_size = 3,
  n_trials = 200,
  seed = 123
)
trials

# Patients treated at each combination in the first trial
trials$n_pts[1, , ]


Decision Table for the 3+3 Design

Description

Tabulate the dose assignment rule of the traditional 3+3 design used by oc_3p3 and sim_3p3: for every number of DLTs among the three or six patients treated at the current dose, the decision taken during dose escalation and, for mtd_rule = "expand", during the search for the MTD that follows it.

Usage

decision_table_3p3(mtd_rule = c("previous", "expand"))

Arguments

mtd_rule

Character scalar, either "previous" or "expand". The definition of the MTD, as in oc_3p3. Defaults to "previous".

Details

During escalation three patients are treated at the current dose. No DLT escalates, one DLT adds three more patients at the same dose, and two or more stop escalation. With six patients, at most one DLT escalates and two or more stop escalation. Escalating from the highest dose also ends escalation.

With mtd_rule = "previous" the MTD is the dose below the one at which escalation stopped, or the highest dose when it was escalated from, and no MTD is selected when escalation stops at the starting dose. With mtd_rule = "expand" the search starts at the dose below the one at which escalation stopped, or at the highest dose when it was escalated from. A dose with three patients receives three more; a dose with at most one DLT out of six is selected as the MTD, and one with two or more passes the search to the next lower dose. No MTD is selected when the search moves below the starting dose.

Every number of DLTs from 0 to n is listed for six patients, although in a trial the six patients at a dose during escalation always include one DLT among the first three. The search examines only doses that were escalated from, so a dose with three patients has no DLT there, and only that state is listed.

The rules are those of oc_3p3: the tests follow this table through every possible course of a trial and obtain the operating characteristics of oc_3p3().

Value

An object of class decision_table_3p3, which is a data frame with one row per state of the current dose and the columns

stage

"escalation" for dose escalation, or "search" for the search for the MTD, which only mtd_rule = "expand" has.

n

Number of patients treated at the current dose, 3 or 6.

n_tox

Number of patients with a DLT, from 0 to n.

decision

Decision code. During escalation, "E" escalates to the next higher dose, "S" treats three more patients at the current dose and "STOP" stops escalation, this dose and all higher doses being too toxic. During the search, "S" treats three more patients at the current dose, "MTD" selects it as the MTD and "D" moves the search to the next lower dose.

The definition of the MTD is stored in the attribute mtd_rule. The object has print and plot methods.

See Also

print.decision_table_3p3, plot.decision_table_3p3, oc_3p3, boin_decision_table

Examples

decision_table_3p3()

# The other definition of the MTD adds the search for the MTD
decision_table_3p3(mtd_rule = "expand")


Exact Operating Characteristics of the 3+3 Design

Description

Compute the operating characteristics of the traditional 3+3 dose-finding design exactly. The probability of every path the design can take is evaluated in closed form, so the result carries no Monte Carlo error and no seed is involved. Use it as a comparator for the BOIN results returned by sim_boin.

Usage

oc_3p3(
  p_true,
  mtd_rule = c("previous", "expand"),
  start_dose = 1,
  overdose_cutoff = NULL
)

Arguments

p_true

Numeric vector. True DLT probability at each dose level, in increasing dose order.

mtd_rule

Character scalar, either "previous" or "expand". The two definitions of the MTD in common use. See Details. Defaults to "previous".

start_dose

Integer scalar. Dose level for the first cohort. Defaults to 1.

overdose_cutoff

Numeric scalar or NULL. Doses whose true DLT probability exceeds this value count as overdoses in the overdose component of the result. Defaults to NULL, which uses one third.

Details

The escalation rule is the traditional one. Three patients are treated at the current dose. No DLT leads to the next dose up. One DLT out of three leads to three more patients at the same dose, and then to the next dose up if no further DLT is seen and to stopping otherwise. Two or more DLTs out of three stop the trial at once. A trial that escalates past the highest dose ends there.

The two MTD rules differ only in what happens once escalation has stopped. "previous" names the dose below the one declared too toxic, and the highest dose when escalation ran out of doses. "expand" instead takes the MTD to be the highest dose at which at most one of six patients had a DLT: starting from the highest dose still eligible, a dose that has only three patients is expanded to six and assessed, and the search moves down a level whenever the expanded dose fails. Neither rule is universally the standard, so the comparator being matched should be checked before a rule is chosen. The two agree on which doses are visited during escalation, and so on the probability that a patient is exposed to an overly toxic dose; they differ in the sample size and in the selection percentages.

The 3+3 design has no fixed maximum sample size, so the within-trial exposure percentage and the 60 percent and 80 percent thresholds reported for BOIN in sim_boin have no counterpart here.

Value

An object of class oc_3p3, which is a list with components

sel_percent

Percentage of trials selecting each dose as the MTD.

percent_no_mtd

Percentage of trials ending without an MTD.

n_pts_dose

Average number of patients treated at each dose.

n_tox_dose

Average number of DLTs observed at each dose.

total_n_pts

Average total number of patients per trial.

total_n_tox

Average total number of DLTs per trial.

overdose

List describing the design's relationship with doses above overdose_cutoff: pct_patients (the percentage of all patients treated at such a dose, that is the probability that a patient is dosed above the cutoff), avg_n_patients, pct_trials_any (the percentage of trials treating at least one patient there), pct_trials_mtd_above (the percentage of all trials whose selected MTD is above the cutoff) and pct_mtd_above_when_selected (the same among the trials that selected an MTD). The cutoff and the dose levels doses that exceed it are also returned.

together with p_true, n_doses, mtd_rule, start_dose, method and the call.

See Also

sim_3p3, sim_boin

Examples

oc_3p3(p_true = c(0.30, 0.48, 0.67))

# The other definition of the MTD
oc_3p3(p_true = c(0.30, 0.48, 0.67), mtd_rule = "expand")

# Exposure to doses above a stated DLT rate
oc_3p3(p_true = c(0.20, 0.40, 0.60), overdose_cutoff = 1 / 3)$overdose


Compare Several Designs Against the True Doses

Description

Judge the results of several designs against the true doses of the scenarios: how often each design selects the true MTD (designs that select an MTD) or the true OBD (designs that select an OBD), how many patients it treats there, how often it selects an overdose and how many patients it treats at overdoses, how often it selects no dose, and its average sample size and duration. The result has print() and plot() methods.

Usage

oc_compare(..., truth, overdose_cutoff = NULL)

Arguments

...

Design results, named by the design, as for oc_results.

truth

The result of oc_scenarios for the same scenarios, with the same scenario names. The DLT probabilities of every scenario must agree with those stored in the results. Designs that select an OBD need scenarios with response probabilities.

overdose_cutoff

Numeric scalar or NULL. A dose whose true DLT probability is above this value is an overdose. Defaults to NULL, the tox_limit of truth.

Details

Every quantity is computed from the per-dose averages of the results (sel_percent and n_pts_dose), so nothing is simulated again and the results need not keep the trials. A dose is an overdose when its DLT probability exceeds overdose_cutoff by more than 1e-12.

Value

A data frame of class c("oc_compare", "data.frame") with one row per design and scenario and the columns

design, target_type, scenario

As in oc_results.

pct_correct

Percentage of trials selecting a true MTD or OBD; NA when the scenario has none.

n_pts_correct, pct_patients_correct

Average number of patients treated at the true MTDs or OBDs, and its percentage of all the patients.

pct_overdose_selected

Percentage of trials selecting an overdose.

n_pts_overdose, pct_patients_overdose

Average number of patients treated at overdoses, and its percentage of all the patients.

pct_no_selection

Percentage of trials selecting no dose.

total_n_pts

Average number of patients per trial.

duration

Average trial duration, NA for the designs without time.

with the attribute overdose_cutoff.

See Also

oc_scenarios, oc_results, print.oc_compare, plot.oc_compare

Examples

scen <- list(
  "Scenario 1" = list(p_true = c(0.05, 0.12, 0.27, 0.35, 0.50),
                      p_resp = c(0.20, 0.35, 0.36, 0.37, 0.38)),
  "Scenario 2" = list(p_true = c(0.05, 0.12, 0.27, 0.35, 0.50),
                      p_resp = c(0.01, 0.05, 0.30, 0.60, 0.60))
)
truth <- oc_scenarios(scen, target = 0.35, target_resp = 0.25)
boin12 <- sim_boin12_multi(target = 0.35, target_resp = 0.25,
                           scenarios = scen, n_cohort = 12,
                           cohort_size = 3, n_trials = 200, seed = 1)
boin <- sim_boin_multi(target = 0.35, scenarios = scen, n_cohort = 12,
                       cohort_size = 3, n_trials = 200, seed = 1)
oc_compare(BOIN12 = boin12, BOIN = boin, truth = truth)


Operating Characteristics of Several Designs in One Table

Description

Collect the results of the simulation functions of different designs (and of oc_3p3) into one long data frame, so that the designs can be tabulated and drawn side by side. The result has print() and plot() methods; oc_compare judges the same results against the true doses.

Usage

oc_results(...)

Arguments

...

Design results, named by the design, for example oc_results(BOIN12 = res_a, "BOIN-ET" = res_b). Each is the result of a simulation function for one scenario (such as sim_boin() or sim_boin12()), of its _multi version, of oc_3p3, or a list of such single-scenario results named by the scenarios (the way to give oc_3p3() several scenarios). Unnamed results are named after their design. All results must be for a single agent or all for a drug combination, with the same number of doses.

Details

The values are those of the components sel_percent, n_pts_dose, n_tox_dose, n_resp_dose, percent_no_mtd or percent_no_obd, total_n_pts, total_n_tox, total_n_resp and duration_mean or duration of the results; nothing is simulated again.

Value

A data frame of class c("oc_results", "data.frame") with the columns

design

Factor of the design names, in the order given.

target_type

"MTD" or "OBD", what the design selects.

scenario

Factor of the scenario names. A single-scenario result is named "Scenario 1".

dose

Dose level, or dose_a and dose_b for a combination; NA for the quantities of the whole trial.

metric

Factor: per dose, "sel_percent" (percentage of trials selecting the dose), "n_pts", "n_tox" and "n_resp" (average numbers of patients, DLTs and responses); per trial, "percent_no_selection" (percentage of trials selecting no dose), "total_n_pts", "total_n_tox", "total_n_resp" and "duration" (average trial duration, for the designs with time). Quantities a design does not record are left out.

value

The value.

with the attributes type ("single" or "combination") and dims.

See Also

oc_scenarios, oc_compare, print.oc_results, plot.oc_results

Examples

scen <- list(
  "Scenario 1" = list(p_true = c(0.05, 0.12, 0.27, 0.35, 0.50),
                      p_resp = c(0.20, 0.35, 0.36, 0.37, 0.38))
)
boin12 <- sim_boin12_multi(target = 0.35, target_resp = 0.25,
                           scenarios = scen, n_cohort = 12,
                           cohort_size = 3, n_trials = 200, seed = 1)
boin <- sim_boin_multi(target = 0.35, scenarios = scen, n_cohort = 12,
                       cohort_size = 3, n_trials = 200, seed = 1)
res <- oc_results(BOIN12 = boin12, BOIN = boin)
head(res)
res


True Dose-Toxicity and Dose-Response Scenarios

Description

Tabulate a list of scenarios, as given to the _multi simulation functions, with the true utility of every dose and the doses that are the true maximum tolerated dose (MTD) and the true optimal biological dose (OBD). The result is the truth against which oc_compare judges the designs, and it has print() and plot() methods.

Usage

oc_scenarios(
  scenarios,
  target,
  target_resp = NULL,
  tox_limit = target,
  psi00 = 40,
  psi11 = 60,
  resp_cor = 0,
  resp_cor_type = c("copula", "binary"),
  true_mtd = NULL,
  true_obd = NULL
)

Arguments

scenarios

List of scenarios. For a single agent, each element is a numeric vector of DLT probabilities or a list with the component p_true, and optionally p_resp (response probabilities) and name. For two drugs given together, p_true (and p_resp) are matrices with one row per level of drug A and one column per level of drug B. Either every scenario or none has p_resp. Names of the list are used when name is absent, and "Scenario 1", "Scenario 2", ... otherwise.

target

Numeric scalar. Target DLT probability; the true MTD is the dose whose DLT probability is closest to it.

target_resp

Numeric scalar or NULL. Lowest acceptable response probability, as target_resp of sim_boin12; a dose with a lower response probability cannot be the true OBD. Defaults to NULL, no such limit. The target_resp of sim_boin_et, the target response probability of BOIN-ET, is a different quantity.

tox_limit

Numeric scalar. Highest acceptable DLT probability; a dose with a higher DLT probability cannot be the true OBD. Defaults to target.

psi00, psi11

Numeric scalars. Utilities of a patient with neither a DLT nor a response and with both, on the scale where a response without a DLT scores 100 and a DLT without a response scores 0. Default to 40 and 60, as in sim_boin12.

resp_cor

Numeric scalar. Correlation between the DLT and the response, used for the probabilities of the four outcomes. Defaults to 0, independence.

resp_cor_type

Character scalar. How resp_cor is read, as in sim_boin12: "copula" (the default), the correlation of the latent normal variables, or "binary", the correlation of the two binary outcomes.

true_mtd, true_obd

NULL (the default) or a list with one element per scenario, in the order of scenarios or named by the scenarios, giving the true MTDs or OBDs directly when the definition of an article differs from the one used here: a vector of dose levels for a single agent, a two-column matrix of the levels of drug A and drug B for a combination, or NULL for the computed doses. An empty vector means no such dose.

Details

The utility of a dose is 100 * Pr(response, no DLT) + psi00 * Pr(neither) + psi11 * Pr(both). The true MTDs are all the doses whose DLT probability is closest to target (several when tied). The true OBDs are all the doses with the highest utility among the doses whose DLT probability is at most tox_limit and, when target_resp is given, whose response probability is at least target_resp; a scenario may have none. Ties are decided with a tolerance of 1e-10.

Some articles use other definitions, for example Lin et al. (2020), who count every dose within 3 points of the highest utility as an OBD; give such doses through true_obd.

Value

A data frame of class c("oc_scenarios", "data.frame") with one row per scenario and dose (or combination) and the columns

scenario

Factor of the scenario names, in the order given.

dose

Dose level, or dose_a and dose_b for a combination.

p_true

True DLT probability.

p_resp, utility

True response probability and utility, when the scenarios have response probabilities.

true_mtd

Logical, the dose is a true MTD.

true_obd

Logical, the dose is a true OBD, when the scenarios have response probabilities.

The arguments are kept as attributes, with type ("single" or "combination") and dims (the number of doses, or the numbers of levels of the two drugs).

References

Lin, R., Zhou, Y., Yan, F., Li, D. and Yuan, Y. (2020). BOIN12: Bayesian optimal interval phase I/II trial design for utility-based dose finding in immunotherapy and targeted therapies. JCO Precision Oncology, 4, 1393-1402. doi:10.1200/PO.20.00257

See Also

oc_results, oc_compare, print.oc_scenarios, plot.oc_scenarios

Examples

truth <- oc_scenarios(
  list(
    "Scenario 1" = list(p_true = c(0.05, 0.12, 0.27, 0.35, 0.50),
                        p_resp = c(0.20, 0.35, 0.36, 0.37, 0.38)),
    "Scenario 2" = list(p_true = c(0.05, 0.12, 0.27, 0.35, 0.50),
                        p_resp = c(0.01, 0.05, 0.30, 0.60, 0.60))
  ),
  target = 0.35, target_resp = 0.25
)
truth


Plot a BOIN Decision Table

Description

Draw the decision table produced by boin_decision_table as a grid of colored cells, one per pair of DLT and patient counts, with the decision letter in each cell.

Usage

## S3 method for class 'boin_decision_table'
plot(x, text_size = 1, colors = NULL, ...)

Arguments

x

An object of class boin_decision_table.

text_size

Numeric scalar. Multiplier applied to every text size in the figure. Use a larger value when the figure is exported at high resolution, for example into a report. Defaults to 1.

colors

Named character vector of four colors, with names "E", "S", "D" and "DE". Defaults to a palette whose adjacent categories remain distinguishable under the common forms of color vision deficiency.

...

Further arguments, currently ignored.

Details

Every cell carries its decision letter, so the figure does not rely on color alone to convey the decision and remains readable in grayscale.

Requires the ggplot2 package, which is only suggested by simFastBOIN rather than required.

Value

A ggplot2 object, which can be printed, saved with ggplot2::ggsave() or extended with further layers.

See Also

boin_decision_table, print.boin_decision_table

Examples


decisions <- boin_decision_table(target = 0.30, max_n = 12)

plot(decisions)

# Larger text for a high resolution export
plot(decisions, text_size = 2)

# A palette of your own
plot(decisions, colors = c(E = "#4DAF4A", S = "#377EB8",
                           D = "#FF7F00", DE = "#E41A1C"))


Plot the Next Dose Combination of a BOIN Drug-Combination Trial

Description

Draw the dose matrix of a drug-combination trial with the data observed at every combination, the current combination, the combination chosen for the next cohort and the combinations eliminated, as returned by comb_boin_next.

Usage

## S3 method for class 'comb_boin_next'
plot(x, text_size = 1, colors = NULL, ...)

Arguments

x

An object of class comb_boin_next.

text_size

Numeric scalar. Multiplier applied to every text size in the figure. Use a larger value when the figure is exported at high resolution. Defaults to 1.

colors

Named character vector of five colors, with names "Next", "Current", "Eliminated", "Treated" and "Not treated". Defaults to the palette of plot.boin_decision_table, with gray and white for the combinations that are neither current, next nor eliminated.

...

Further arguments, currently ignored.

Details

Each cell shows the number of patients with a DLT and the number treated, and the status of the current, next and eliminated combinations is also written in the cell, so the figure does not rely on color alone. The candidates of an escalation or a de-escalation also show the posterior probability that their DLT rate lies between lambda_e and lambda_d. The levels of drug A run up the vertical axis and those of drug B along the horizontal axis.

Requires the ggplot2 package, which is only suggested by simFastBOIN rather than required.

Value

A ggplot2 object, which can be printed, saved with ggplot2::ggsave() or extended with further layers.

See Also

comb_boin_next

Examples


n_pts <- matrix(c(6, 6, 0, 0,
                  3, 3, 0, 0,
                  0, 0, 0, 0), nrow = 3, byrow = TRUE)
n_tox <- matrix(c(0, 1, 0, 0,
                  1, 2, 0, 0,
                  0, 0, 0, 0), nrow = 3, byrow = TRUE)

nxt <- comb_boin_next(target = 0.25, n_pts = n_pts, n_tox = n_tox,
                      current = c(2, 2))
plot(nxt)


Plot a 3+3 Decision Table

Description

Draw the decision table produced by decision_table_3p3 as a grid of colored cells, one per pair of patient and DLT counts, with the decision code in each cell. With mtd_rule = "expand" the search for the MTD is drawn in a second panel.

Usage

## S3 method for class 'decision_table_3p3'
plot(x, text_size = 1, colors = NULL, ...)

Arguments

x

An object of class decision_table_3p3.

text_size

Numeric scalar. Multiplier applied to every text size in the figure. Defaults to 1.

colors

Named character vector of colors with the names "E", "S" and "STOP", and also "MTD" and "D" for mtd_rule = "expand". Defaults to the palette of plot.boin_decision_table, with its color for elimination used for "STOP" and a violet for "MTD".

...

Further arguments, currently ignored.

Details

Every cell carries its decision code, so the figure does not rely on color alone. Requires the ggplot2 package, which is only suggested by simFastBOIN rather than required.

Value

A ggplot2 object, which can be printed, saved with ggplot2::ggsave() or extended with further layers.

See Also

decision_table_3p3, print.decision_table_3p3

Examples


plot(decision_table_3p3())

plot(decision_table_3p3(mtd_rule = "expand"))


Plot a Comparison of Designs

Description

Draw the comparison built by oc_compare: one panel per quantity, with a point for every design and scenario, the points of a design joined by a line.

Usage

## S3 method for class 'oc_compare'
plot(
  x,
  metrics = c("pct_correct", "pct_patients_correct", "pct_overdose_selected",
    "n_pts_overdose"),
  text_size = 1,
  ...
)

Arguments

x

An object of class oc_compare.

metrics

Character vector. Columns of x to draw. Defaults to c("pct_correct", "pct_patients_correct", "pct_overdose_selected", "n_pts_overdose").

text_size

Numeric scalar. Multiplier applied to every text size in the figure. Defaults to 1.

...

Further arguments, currently ignored.

Details

Requires the ggplot2 package, which is only suggested by simFastBOIN. Missing values (for example the correct selection in a scenario without a true OBD) are left out.

Value

A ggplot2 object.

See Also

oc_compare, print.oc_compare

Examples


truth <- oc_scenarios(list(c(0.10, 0.25, 0.40, 0.55)), target = 0.30)
boin <- sim_boin(target = 0.30, p_true = c(0.10, 0.25, 0.40, 0.55),
                 n_cohort = 10, cohort_size = 3, n_trials = 200, seed = 1)
plot(oc_compare(BOIN = boin, "3+3" = oc_3p3(c(0.10, 0.25, 0.40, 0.55)),
                truth = truth))


Plot the Operating Characteristics of Several Designs

Description

Draw one per-dose quantity of the table built by oc_results. For a single agent, one panel per scenario shows bars for every dose, colored by design and labeled with their values. For a combination, one panel per design and scenario shows the value of every combination as a tile.

Usage

## S3 method for class 'oc_results'
plot(x, metric = "sel_percent", text_size = 1, ...)

Arguments

x

An object of class oc_results.

metric

Character scalar. The per-dose quantity: "sel_percent" (the default), "n_pts", "n_tox" or "n_resp".

text_size

Numeric scalar. Multiplier applied to every text size in the figure. Defaults to 1.

...

Further arguments, currently ignored.

Details

Requires the ggplot2 package, which is only suggested by simFastBOIN.

Value

A ggplot2 object.

See Also

oc_results, print.oc_results

Examples


boin <- sim_boin(target = 0.30, p_true = c(0.10, 0.25, 0.40, 0.55),
                 n_cohort = 10, cohort_size = 3, n_trials = 200, seed = 1)
res <- oc_results(BOIN = boin, "3+3" = oc_3p3(c(0.10, 0.25, 0.40, 0.55)))
plot(res)
plot(res, metric = "n_pts")


Plot True Scenarios

Description

Draw the scenarios tabulated by oc_scenarios. For a single agent, one panel per scenario shows the DLT probability, the response probability and the utility divided by 100 against the dose, with the true MTDs labeled "MTD" on the DLT curve and the true OBDs labeled "OBD" on the utility curve. For a combination, one panel per scenario shows the DLT probability of every combination as a tile carrying its value, the true MTDs outlined with a solid line and the true OBDs with a dashed line.

Usage

## S3 method for class 'oc_scenarios'
plot(x, text_size = 1, ...)

Arguments

x

An object of class oc_scenarios.

text_size

Numeric scalar. Multiplier applied to every text size in the figure. Defaults to 1.

...

Further arguments, currently ignored.

Details

Requires the ggplot2 package, which is only suggested by simFastBOIN.

Value

A ggplot2 object.

See Also

oc_scenarios, print.oc_scenarios

Examples


truth <- oc_scenarios(
  list(list(p_true = c(0.05, 0.12, 0.27, 0.35, 0.50),
            p_resp = c(0.20, 0.35, 0.36, 0.37, 0.38))),
  target = 0.35, target_resp = 0.25
)
plot(truth)


Plot a TITE-BOIN Decision Table

Description

Draw the decision table produced by tite_boin_decision_table as one panel per number of patients treated. Within a panel, each cell is a pair of pending patients and DLTs, colored by its decision and labeled with the decision code and, where the decision depends on the follow-up of the pending patients, the boundaries on the follow-up statistic.

Usage

## S3 method for class 'tite_boin_decision_table'
plot(
  x,
  n = NULL,
  cohort_size = NULL,
  text_size = 1,
  colors = NULL,
  digits = 2,
  ...
)

Arguments

x

An object of class tite_boin_decision_table.

n

Integer vector or NULL. Numbers of patients treated to draw, one panel each. Defaults to every number in the table.

cohort_size

Integer scalar or NULL. When supplied, only the numbers of patients that are multiples of cohort_size are drawn.

text_size

Numeric scalar. Multiplier applied to every text size in the figure. Defaults to 1.

colors

Named character vector of six colors, with names "E", "S", "D", "DE", "SUS" and "Depends", the last for the states whose decision depends on the follow-up statistic. Defaults to the palette of plot.boin_decision_table extended with gray for suspension and a pale violet for the follow-up dependent states.

digits

Integer scalar. Number of decimal places of the boundaries in the labels. Defaults to 2.

...

Further arguments, currently ignored.

Details

A cell whose decision depends on the follow-up statistic shows its codes over the boundaries, kept short so that they fit in the cell. A label such as "E/S" over ">=2.15" means that the dose is escalated when the statistic is at least 2.15 and kept otherwise, and "S/D" over "<=0.52" that it is de-escalated when the statistic is at most 0.52. The boundary marked ">=" always belongs to the first code, which is "E", or "SUS" when escalation is blocked, and the one marked "<=" to "D". The statistic is STFT for method = "imputation" and ESS for method = "ess".

When the table was built with a positive min_follow_up, the code of a cell whose escalation also requires the shortest follow-up of the pending patients to reach that fraction of the window is marked with an asterisk, as in "E*" or "E/S*", and a caption explains the mark.

Every cell carries its decision code, so the figure does not rely on color alone. With many panels, or many patients per panel, the cells become small; draw fewer panels through n, enlarge the figure, or lower text_size. Requires the ggplot2 package, which is only suggested by simFastBOIN rather than required.

Value

A ggplot2 object, which can be printed, saved with ggplot2::ggsave() or extended with further layers.

See Also

tite_boin_decision_table, print.tite_boin_decision_table

Examples


decisions <- tite_boin_decision_table(target = 0.2, max_n = 15)

plot(decisions, n = c(9, 12, 15))

# Every cohort end, with smaller text
plot(decisions, cohort_size = 3, text_size = 0.8)


Print Operating Characteristics of a BOIN Design with Backfilling

Description

Display the result of sim_bf_boin or sim_be_boin: the design, a table by dose of the true DLT and response rates, the MTD selection, the patients treated and backfilled and the DLTs, then the exposure above the overdose cutoff and the timing.

Usage

## S3 method for class 'backfill_oc'
print(
  x,
  digits = 1,
  percent = FALSE,
  kable = FALSE,
  kable_format = "pipe",
  ...
)

Arguments

x

An object of class backfill_oc.

digits

Integer scalar. Number of decimal places. Defaults to 1.

percent

Logical scalar. Show patients, backfilled patients and DLTs as percentages of their totals rather than as averages per trial. Defaults to FALSE.

kable

Logical scalar. Print only the table, formatted by knitr::kable(). Defaults to FALSE.

kable_format

Character scalar passed to knitr::kable() as format. Defaults to "pipe".

...

Further arguments, currently ignored.

Value

The object x, invisibly.

See Also

sim_bf_boin, sim_be_boin

Examples

oc <- sim_bf_boin(
  target = 0.25,
  p_true = c(0.04, 0.12, 0.25, 0.43, 0.63),
  p_resp = c(0.10, 0.20, 0.30, 0.45, 0.58),
  n_cohort = 10, cohort_size = 3, window = 1, accrual_rate = 3,
  n_trials = 200, seed = 1
)
print(oc)
print(oc, percent = TRUE)


Print Operating Characteristics of a Backfill Design Across Scenarios

Description

Display the result of sim_bf_boin_multi or sim_be_boin_multi as one table with seven rows per scenario.

Usage

## S3 method for class 'backfill_oc_multi'
print(
  x,
  digits = 1,
  percent = FALSE,
  kable = FALSE,
  kable_format = "pipe",
  ...
)

Arguments

x

An object of class backfill_oc_multi.

digits

Integer scalar. Number of decimal places. Defaults to 1.

percent

Logical scalar. Show patients, backfilled patients and DLTs as percentages of their totals. Defaults to FALSE.

kable

Logical scalar. Print only the table, formatted by knitr::kable(). Defaults to FALSE.

kable_format

Character scalar passed to knitr::kable() as format. Defaults to "pipe".

...

Further arguments, currently ignored.

Value

The object x, invisibly.

See Also

sim_bf_boin_multi, sim_be_boin_multi

Examples

scenarios <- list(
  list(name = "Rising", p_true = c(0.04, 0.12, 0.25, 0.43, 0.63),
       p_resp = c(0.10, 0.20, 0.30, 0.45, 0.58)),
  list(name = "Plateau", p_true = c(0.04, 0.12, 0.25, 0.43, 0.63),
       p_resp = c(0.30, 0.32, 0.35, 0.36, 0.36))
)
oc <- sim_bf_boin_multi(
  target = 0.25, scenarios = scenarios, n_cohort = 10, cohort_size = 3,
  window = 1, accrual_rate = 3, n_trials = 100, seed = 1
)
print(oc, percent = TRUE)


Print Simulated Trials of a BOIN Design with Backfilling

Description

Summarize the trials returned by bf_boin_simulate or be_boin_simulate: the design, the average numbers of patients, backfilled patients, DLTs and responses at each dose, the trial duration, the waiting of the dose escalation and the reasons for stopping.

Usage

## S3 method for class 'backfill_trials'
print(x, ...)

Arguments

x

An object of class backfill_trials.

...

Further arguments, currently ignored.

Value

The object x, invisibly.

See Also

bf_boin_simulate, be_boin_simulate

Examples

trials <- bf_boin_simulate(
  target = 0.25,
  p_true = c(0.04, 0.12, 0.25, 0.43, 0.63),
  p_resp = c(0.10, 0.20, 0.30, 0.45, 0.58),
  n_cohort = 10, cohort_size = 3, window = 1, accrual_rate = 3,
  n_trials = 100, seed = 1
)
print(trials)


Print the Operating Characteristics of the BF-BOIN-ET Design

Description

Display the summary produced by sim_bf_boin_et as a table with one column per dose.

Usage

## S3 method for class 'bf_boin_et_oc'
print(
  x,
  digits = 1,
  percent = FALSE,
  kable = FALSE,
  kable_format = "pipe",
  ...
)

Arguments

x

An object of class bf_boin_et_oc.

digits

Integer scalar. Number of decimal places. Defaults to 1.

percent

Logical scalar. Express the average numbers of patients, backfilled patients, DLTs and responses at each dose as percentages of the trial totals. Defaults to FALSE.

kable

Logical scalar. Print the table with knitr::kable(), for use in R Markdown. Defaults to FALSE.

kable_format

Character scalar. Format passed to knitr::kable(). Defaults to "pipe".

...

Further arguments, currently ignored.

Value

The object x, invisibly.

Examples

oc <- sim_bf_boin_et(
  target = 0.30, target_resp = 0.25,
  p_true = c(0.03, 0.05, 0.20, 0.22, 0.45),
  p_resp = c(0.05, 0.10, 0.50, 0.68, 0.70),
  n_cohort = 10, cohort_size = 3, window = 1, accrual_rate = 3,
  n_trials = 200, seed = 1
)
print(oc, digits = 2)
print(oc, percent = TRUE)


Print the Operating Characteristics of BF-BOIN-ET Across Scenarios

Description

Display the table produced by sim_bf_boin_et_multi, with seven rows per scenario.

Usage

## S3 method for class 'bf_boin_et_oc_multi'
print(
  x,
  digits = 1,
  percent = FALSE,
  kable = FALSE,
  kable_format = "pipe",
  ...
)

Arguments

x

An object of class bf_boin_et_oc_multi.

digits

Integer scalar. Number of decimal places. Defaults to 1.

percent

Logical scalar. Express the average numbers of patients, backfilled patients, DLTs and responses at each dose as percentages of the trial totals. Defaults to FALSE.

kable

Logical scalar. Print the table with knitr::kable(), for use in R Markdown. Defaults to FALSE.

kable_format

Character scalar. Format passed to knitr::kable(). Defaults to "pipe".

...

Further arguments, currently ignored.

Value

The object x, invisibly.

Examples

scenarios <- list(
  "Example" = list(p_true = c(0.03, 0.05, 0.20, 0.22, 0.45),
                   p_resp = c(0.05, 0.10, 0.50, 0.68, 0.70)),
  "Plateau" = list(p_true = c(0.05, 0.10, 0.15, 0.30, 0.45),
                   p_resp = c(0.10, 0.30, 0.45, 0.50, 0.52))
)
res <- sim_bf_boin_et_multi(
  target = 0.30, target_resp = 0.25, scenarios = scenarios,
  n_cohort = 10, cohort_size = 3, window = 1, accrual_rate = 3,
  n_trials = 100, seed = 1
)
print(res, digits = 2)


Print the Desirability Score Table of the BOIN12 Design

Description

Display the table of boin12_decision_table with the score of every outcome, "E" marking the outcomes that make the dose inadmissible.

Usage

## S3 method for class 'boin12_decision_table'
print(x, desirability = FALSE, ...)

Arguments

x

An object of class boin12_decision_table.

desirability

Logical scalar. Show the posterior probabilities as well. Defaults to FALSE.

...

Not used.

Value

x, invisibly.

Examples

tab <- boin12_decision_table(target = 0.35, target_resp = 0.25, n = c(0, 3))
print(tab, desirability = TRUE)


Print the Operating Characteristics of the BOIN12 Design

Description

Display the summary produced by sim_boin12 as a table with one column per dose.

Usage

## S3 method for class 'boin12_oc'
print(
  x,
  digits = 1,
  percent = FALSE,
  kable = FALSE,
  kable_format = "pipe",
  ...
)

Arguments

x

An object of class boin12_oc.

digits

Integer scalar. Number of decimal places. Defaults to 1.

percent

Logical scalar. Express the average numbers of patients, DLTs and responses at each dose as percentages of the trial totals. Defaults to FALSE.

kable

Logical scalar. Print the table with knitr::kable(), for use in R Markdown. Defaults to FALSE.

kable_format

Character scalar. Format passed to knitr::kable(). Defaults to "pipe".

...

Not used.

Value

x, invisibly.

Examples

oc <- sim_boin12(
  target = 0.35, target_resp = 0.25,
  p_true = c(0.05, 0.12, 0.27, 0.35, 0.50),
  p_resp = c(0.20, 0.35, 0.36, 0.37, 0.38),
  n_cohort = 12, cohort_size = 3, n_trials = 200, seed = 1
)
print(oc)
print(oc, percent = TRUE)


Print the Operating Characteristics of the BOIN12 Design Across Scenarios

Description

Display the summary produced by sim_boin12_multi as one table with a block of rows per scenario.

Usage

## S3 method for class 'boin12_oc_multi'
print(
  x,
  digits = 1,
  percent = FALSE,
  kable = FALSE,
  kable_format = "pipe",
  ...
)

Arguments

x

An object of class boin12_oc_multi.

digits

Integer scalar. Number of decimal places. Defaults to 1.

percent

Logical scalar. Express the average numbers of patients, DLTs and responses at each dose as percentages of the trial totals. Defaults to FALSE.

kable

Logical scalar. Print the table with knitr::kable(), for use in R Markdown. Defaults to FALSE.

kable_format

Character scalar. Format passed to knitr::kable(). Defaults to "pipe".

...

Not used.

Value

x, invisibly.

Examples

scenarios <- list(
  "Plateau" = list(p_true = c(0.05, 0.12, 0.27, 0.35, 0.50),
                   p_resp = c(0.20, 0.35, 0.36, 0.37, 0.38)),
  "Increasing" = list(p_true = c(0.05, 0.12, 0.27, 0.35, 0.50),
                      p_resp = c(0.01, 0.05, 0.30, 0.60, 0.60))
)
oc <- sim_boin12_multi(
  target = 0.35, target_resp = 0.25, scenarios = scenarios,
  n_cohort = 12, cohort_size = 3, n_trials = 200, seed = 1
)
print(oc, percent = TRUE)


Print Simulated BOIN12 Trials

Description

Display the settings, the average numbers of patients, DLTs and responses at each dose and the stopping reasons of trials simulated by boin12_simulate.

Usage

## S3 method for class 'boin12_trials'
print(x, ...)

Arguments

x

An object of class boin12_trials.

...

Not used.

Value

x, invisibly.

Examples

trials <- boin12_simulate(
  target = 0.35, target_resp = 0.25,
  p_true = c(0.05, 0.12, 0.27, 0.35, 0.50),
  p_resp = c(0.20, 0.35, 0.36, 0.37, 0.38),
  n_cohort = 12, cohort_size = 3, n_trials = 100, seed = 1
)
print(trials)


Print BOIN Decision Boundaries

Description

Display the interval boundaries and the integer decision boundaries produced by boin_boundary.

Usage

## S3 method for class 'boin_boundary'
print(x, cohort_size = NULL, ...)

Arguments

x

An object of class boin_boundary.

cohort_size

Integer scalar or NULL. When supplied, only the sample sizes that are multiples of cohort_size are shown, which is how the boundaries are consulted during a trial with equally sized cohorts.

...

Further arguments, currently ignored.

Value

The object x, invisibly.

Examples

bd <- boin_boundary(target = 0.30, max_n = 18, extrasafe = TRUE)
print(bd, cohort_size = 3)


Print a BOIN Decision Table

Description

Display the decision table produced by boin_decision_table, optionally restricted to the sample sizes reached at the end of a cohort.

Usage

## S3 method for class 'boin_decision_table'
print(x, cohort_size = NULL, ...)

Arguments

x

An object of class boin_decision_table.

cohort_size

Integer scalar or NULL. When supplied, only the sample sizes that are multiples of cohort_size are shown, which is how the table is consulted during a trial with equally sized cohorts.

...

Further arguments, currently ignored.

Value

The object x, invisibly.

See Also

boin_decision_table, plot.boin_decision_table

Examples

decisions <- boin_decision_table(target = 0.30, max_n = 18)

print(decisions, cohort_size = 3)


Print the Boundaries of the BOIN-ET Design

Description

Display the boundaries found by boin_et_boundary together with the design parameters they were found from.

Usage

## S3 method for class 'boin_et_boundary'
print(x, ...)

Arguments

x

An object of class boin_et_boundary.

...

Further arguments, currently ignored.

Value

The object x, invisibly.

See Also

boin_et_boundary

Examples

print(boin_et_boundary(target = 0.30, target_resp = 0.60))


Print a BOIN-ET Decision Table

Description

Display the decision table produced by boin_et_decision_table as one matrix per number of patients, with the DLTs in the rows and the responses in the columns.

Usage

## S3 method for class 'boin_et_decision_table'
print(x, ...)

Arguments

x

An object of class boin_et_decision_table.

...

Further arguments, currently ignored.

Value

The object x, invisibly.

See Also

boin_et_decision_table

Examples

print(boin_et_decision_table(target = 0.30, target_resp = 0.60, n = 3))


Print the Operating Characteristics of the BOIN-ET Design

Description

Display the summary produced by sim_boin_et as a table with one column per dose.

Usage

## S3 method for class 'boin_et_oc'
print(
  x,
  digits = 1,
  percent = FALSE,
  kable = FALSE,
  kable_format = "pipe",
  ...
)

Arguments

x

An object of class boin_et_oc.

digits

Integer scalar. Number of decimal places. Defaults to 1.

percent

Logical scalar. Express the average numbers of patients, DLTs and responses at each dose as percentages of the trial totals. Defaults to FALSE.

kable

Logical scalar. Print the table with knitr::kable(), for use in R Markdown. Defaults to FALSE.

kable_format

Character scalar. Format passed to knitr::kable(). Defaults to "pipe".

...

Further arguments, currently ignored.

Value

The object x, invisibly.

See Also

sim_boin_et

Examples

oc <- sim_boin_et(
  target = 0.30, target_resp = 0.60,
  p_true = c(0.05, 0.15, 0.25, 0.30, 0.35, 0.40),
  p_resp = c(0.05, 0.35, 0.55, 0.65, 0.75, 0.70),
  n_cohort = 12, cohort_size = 3, n_trials = 500, seed = 1
)
print(oc)
print(oc, percent = TRUE)


Print the Operating Characteristics of BOIN-ET Across Scenarios

Description

Display the table produced by sim_boin_et_multi, with six rows per scenario.

Usage

## S3 method for class 'boin_et_oc_multi'
print(
  x,
  digits = 1,
  percent = FALSE,
  kable = FALSE,
  kable_format = "pipe",
  ...
)

Arguments

x

An object of class boin_et_oc_multi.

digits

Integer scalar. Number of decimal places. Defaults to 1.

percent

Logical scalar. Express the average numbers of patients, DLTs and responses at each dose as percentages of the trial totals. Defaults to FALSE.

kable

Logical scalar. Print the table with knitr::kable(), for use in R Markdown. Defaults to FALSE.

kable_format

Character scalar. Format passed to knitr::kable(). Defaults to "pipe".

...

Further arguments, currently ignored.

Value

The object x, invisibly.

See Also

sim_boin_et_multi

Examples

scenarios <- list(
  list(name = "Monotone",
       p_true = c(0.05, 0.10, 0.15, 0.20, 0.25, 0.40),
       p_resp = c(0.05, 0.10, 0.25, 0.40, 0.65, 0.70)),
  list(name = "Peaked",
       p_true = c(0.05, 0.15, 0.25, 0.35, 0.45, 0.55),
       p_resp = c(0.30, 0.70, 0.60, 0.50, 0.40, 0.30))
)
res <- sim_boin_et_multi(
  target = 0.30, target_resp = 0.60, scenarios = scenarios,
  n_cohort = 12, cohort_size = 3, n_trials = 300, seed = 1
)
print(res)
print(res, percent = TRUE)


Print Simulated BOIN-ET Trials

Description

Show a compact summary of the object returned by boin_et_simulate instead of printing the full trial matrices.

Usage

## S3 method for class 'boin_et_trials'
print(x, ...)

Arguments

x

An object of class boin_et_trials.

...

Further arguments, currently ignored.

Value

The object x, invisibly.

See Also

boin_et_simulate

Examples

trials <- boin_et_simulate(
  target = 0.30, target_resp = 0.60,
  p_true = c(0.05, 0.15, 0.25, 0.30, 0.35, 0.40),
  p_resp = c(0.05, 0.35, 0.55, 0.65, 0.75, 0.70),
  n_cohort = 12, cohort_size = 3, n_trials = 100, seed = 1
)
print(trials)


Print the Operating Characteristics of the BOIN-ETC Design

Description

Print the Operating Characteristics of the BOIN-ETC Design

Usage

## S3 method for class 'boin_etc_oc'
print(
  x,
  digits = 1,
  percent = FALSE,
  kable = FALSE,
  kable_format = "pipe",
  ...
)

Arguments

x

An object of class boin_etc_oc from sim_boin_etc.

digits

Integer scalar. Decimal places. Defaults to 1.

percent

Logical scalar. Show the patients, DLTs and responses at each combination as percentages of their totals. Defaults to FALSE.

kable

Logical scalar. Print the table with knitr::kable(). Defaults to FALSE.

kable_format

Character scalar. Format passed to knitr::kable(). Defaults to "pipe".

...

Not used.

Value

x, invisibly.

See Also

sim_boin_etc

Examples

p_true <- matrix(c(0.05, 0.10, 0.10, 0.30, 0.30, 0.50), nrow = 2)
p_resp <- matrix(c(0.10, 0.25, 0.25, 0.60, 0.60, 0.65), nrow = 2)
oc <- sim_boin_etc(target = 0.30, target_resp = 0.60, p_true = p_true,
                   p_resp = p_resp, n_cohort = 8, cohort_size = 3,
                   n_trials = 100, seed = 1)
print(oc)
print(oc, percent = TRUE)


Print the Operating Characteristics of the BOIN-ETC Design Across Scenarios

Description

Print the Operating Characteristics of the BOIN-ETC Design Across Scenarios

Usage

## S3 method for class 'boin_etc_oc_multi'
print(x, digits = 1, kable = FALSE, kable_format = "pipe", ...)

Arguments

x

An object of class boin_etc_oc_multi from sim_boin_etc_multi.

digits

Integer scalar. Decimal places. Defaults to 1.

kable

Logical scalar. Print the table with knitr::kable(). Defaults to FALSE.

kable_format

Character scalar. Format passed to knitr::kable(). Defaults to "pipe".

...

Not used.

Value

x, invisibly.

See Also

sim_boin_etc_multi

Examples

scenarios <- list(
  "Scenario 1" = list(
    p_true = matrix(c(0.05, 0.10, 0.10, 0.30, 0.30, 0.50), nrow = 2),
    p_resp = matrix(c(0.10, 0.25, 0.25, 0.60, 0.60, 0.65), nrow = 2)),
  "Scenario 2" = list(
    p_true = matrix(c(0.05, 0.15, 0.15, 0.35, 0.30, 0.55), nrow = 2),
    p_resp = matrix(c(0.25, 0.60, 0.60, 0.65, 0.65, 0.70), nrow = 2))
)
res <- sim_boin_etc_multi(target = 0.30, target_resp = 0.60,
                          scenarios = scenarios, n_cohort = 8,
                          cohort_size = 3, n_trials = 100)
print(res)


Print Simulated BOIN-ETC Trials

Description

Print Simulated BOIN-ETC Trials

Usage

## S3 method for class 'boin_etc_trials'
print(x, ...)

Arguments

x

An object of class boin_etc_trials from boin_etc_simulate.

...

Not used.

Value

x, invisibly.

See Also

boin_etc_simulate

Examples

p_true <- matrix(c(0.05, 0.10, 0.10, 0.30, 0.30, 0.50), nrow = 2)
p_resp <- matrix(c(0.10, 0.25, 0.25, 0.60, 0.60, 0.65), nrow = 2)
trials <- boin_etc_simulate(target = 0.30, target_resp = 0.60,
                            p_true = p_true, p_resp = p_resp,
                            n_cohort = 8, cohort_size = 3,
                            n_trials = 100, seed = 1)
print(trials)


Print Operating Characteristics of a BOIN Design

Description

Display the summary table produced by sim_boin.

Usage

## S3 method for class 'boin_oc'
print(
  x,
  digits = 1,
  percent = FALSE,
  kable = FALSE,
  kable_format = "pipe",
  ...
)

Arguments

x

An object of class boin_oc.

digits

Integer scalar. Number of decimal places. Defaults to 1.

percent

Logical scalar. Express the average number of patients and DLTs at each dose as a percentage of the trial total instead of a count. Defaults to FALSE.

kable

Logical scalar. Return the table through knitr::kable() rather than printing it directly, which is convenient inside a report. Requires the knitr package. Defaults to FALSE.

kable_format

Character scalar passed to knitr::kable(), for example "pipe", "html" or "latex". Defaults to "pipe".

...

Further arguments, currently ignored.

Value

The object x, invisibly.

Examples

oc <- sim_boin(
  target = 0.30,
  p_true = c(0.05, 0.15, 0.30, 0.45, 0.60),
  n_cohort = 10,
  cohort_size = 3,
  n_trials = 200,
  seed = 123
)

print(oc)
print(oc, percent = TRUE)


Print Operating Characteristics Across Scenarios

Description

Display the combined summary table produced by sim_boin_multi.

Usage

## S3 method for class 'boin_oc_multi'
print(
  x,
  digits = 1,
  percent = FALSE,
  kable = FALSE,
  kable_format = "pipe",
  ...
)

Arguments

x

An object of class boin_oc_multi.

digits

Integer scalar. Number of decimal places. Defaults to 1.

percent

Logical scalar. Express the average number of patients and DLTs at each dose as a percentage of the trial total instead of a count. Defaults to FALSE.

kable

Logical scalar. Return the table through knitr::kable() rather than printing it directly. Requires the knitr package. Defaults to FALSE.

kable_format

Character scalar passed to knitr::kable(), for example "pipe", "html" or "latex". Defaults to "pipe".

...

Further arguments, currently ignored.

Value

The object x, invisibly.

Examples

oc <- sim_boin_multi(
  target = 0.30,
  scenarios = list(
    list(name = "MTD at dose 3", p_true = c(0.05, 0.15, 0.30, 0.45, 0.60)),
    list(name = "All toxic",     p_true = c(0.35, 0.45, 0.55, 0.65, 0.75))
  ),
  n_cohort = 10,
  cohort_size = 3,
  n_trials = 200,
  seed = 123
)

print(oc)
print(oc, percent = TRUE)


Print Simulated BOIN Trials

Description

Show a compact summary of the object returned by boin_simulate instead of printing the full trial matrices.

Usage

## S3 method for class 'boin_trials'
print(x, ...)

Arguments

x

An object of class boin_trials.

...

Further arguments, currently ignored.

Value

The object x, invisibly.

Examples

trials <- boin_simulate(
  target = 0.30,
  p_true = c(0.05, 0.15, 0.30, 0.45, 0.60),
  n_cohort = 10,
  cohort_size = 3,
  n_trials = 100,
  seed = 1
)
print(trials)


Print the Operating Characteristics of the Comb-BOIN12 Design

Description

Print the Operating Characteristics of the Comb-BOIN12 Design

Usage

## S3 method for class 'comb_boin12_oc'
print(
  x,
  digits = 1,
  percent = FALSE,
  kable = FALSE,
  kable_format = "pipe",
  ...
)

Arguments

x

An object of class comb_boin12_oc from sim_comb_boin12.

digits

Integer scalar. Decimal places. Defaults to 1.

percent

Logical scalar. Show the patients, DLTs and responses at each combination as percentages of their totals. Defaults to FALSE.

kable

Logical scalar. Print the table with knitr::kable(). Defaults to FALSE.

kable_format

Character scalar. Format passed to knitr::kable(). Defaults to "pipe".

...

Not used.

Value

x, invisibly.

See Also

sim_comb_boin12

Examples

p_true <- matrix(c(0.05, 0.10, 0.15, 0.15, 0.20, 0.45), nrow = 2)
p_resp <- matrix(c(0.10, 0.20, 0.30, 0.40, 0.50, 0.60), nrow = 2)
oc <- sim_comb_boin12(target = 0.33, target_resp = 0.2, p_true = p_true,
                      p_resp = p_resp, n_cohort = 14, cohort_size = 3,
                      n_trials = 100, est_method = "observed", seed = 1)
print(oc)
print(oc, percent = TRUE)


Print the Operating Characteristics of Comb-BOIN12 Across Scenarios

Description

Print the Operating Characteristics of Comb-BOIN12 Across Scenarios

Usage

## S3 method for class 'comb_boin12_oc_multi'
print(x, digits = 1, kable = FALSE, kable_format = "pipe", ...)

Arguments

x

An object of class comb_boin12_oc_multi from sim_comb_boin12_multi.

digits

Integer scalar. Decimal places. Defaults to 1.

kable

Logical scalar. Print the table with knitr::kable(). Defaults to FALSE.

kable_format

Character scalar. Format passed to knitr::kable(). Defaults to "pipe".

...

Not used.

Details

One row per scenario: the true OBD combinations, the percentage of trials selecting one of them and of the patients treated there, the percentage of trials selecting no OBD combination, the percentages selecting and treating combinations above the DLT limit, and the average numbers of patients, DLTs and responses.

Value

x, invisibly.

See Also

sim_comb_boin12_multi

Examples

scenarios <- list(
  "Scenario 16" = list(
    p_true = matrix(c(0.05, 0.10, 0.15, 0.15, 0.20, 0.45), nrow = 2),
    p_resp = matrix(c(0.10, 0.20, 0.30, 0.40, 0.50, 0.60), nrow = 2)),
  "Scenario 17" = list(
    p_true = matrix(c(0.05, 0.10, 0.15, 0.20, 0.40, 0.50), nrow = 2),
    p_resp = matrix(c(0.10, 0.20, 0.30, 0.40, 0.50, 0.55), nrow = 2))
)
oc <- sim_comb_boin12_multi(target = 0.33, target_resp = 0.2,
                            scenarios = scenarios, n_cohort = 14,
                            cohort_size = 3, n_trials = 100,
                            est_method = "observed", seed = 1)
print(oc)


Print Simulated Comb-BOIN12 Trials

Description

Print Simulated Comb-BOIN12 Trials

Usage

## S3 method for class 'comb_boin12_trials'
print(x, ...)

Arguments

x

An object of class comb_boin12_trials from comb_boin12_simulate.

...

Not used.

Value

x, invisibly.

See Also

comb_boin12_simulate

Examples

p_true <- matrix(c(0.05, 0.10, 0.15, 0.15, 0.20, 0.45), nrow = 2)
p_resp <- matrix(c(0.10, 0.20, 0.30, 0.40, 0.50, 0.60), nrow = 2)
trials <- comb_boin12_simulate(target = 0.33, target_resp = 0.2,
                               p_true = p_true, p_resp = p_resp,
                               n_cohort = 14, cohort_size = 3,
                               n_trials = 100, seed = 1)
print(trials)


Print the Next Dose Combination of a BOIN Drug-Combination Trial

Description

Display the decision returned by comb_boin_next: the data at the current combination, the boundaries that apply to it, the decision, the candidates that were compared and the combinations eliminated so far.

Usage

## S3 method for class 'comb_boin_next'
print(x, ...)

Arguments

x

An object of class comb_boin_next.

...

Further arguments, currently ignored.

Value

The object x, invisibly.

Examples

n_pts <- matrix(c(3, 0, 0,
                  0, 0, 0), nrow = 2, byrow = TRUE)
n_tox <- matrix(0, nrow = 2, ncol = 3)

print(comb_boin_next(target = 0.30, n_pts = n_pts, n_tox = n_tox,
                     current = c(1, 1)))


Print Operating Characteristics of the BOIN Drug-Combination Design

Description

Display the summary produced by sim_comb_boin: the true DLT rates, the selection percentages and the average numbers of patients and DLTs at every dose combination, followed by the selection of the true MTD and the exposure to combinations above the overdose cutoff.

Usage

## S3 method for class 'comb_boin_oc'
print(x, digits = 1, kable = FALSE, kable_format = "pipe", ...)

Arguments

x

An object of class comb_boin_oc.

digits

Integer scalar. Number of decimal places. Defaults to 1.

kable

Logical scalar. Return the table through knitr::kable() rather than printing it directly, which is convenient inside a report. Requires the knitr package. Defaults to FALSE.

kable_format

Character scalar passed to knitr::kable(), for example "pipe", "html" or "latex". Defaults to "pipe".

...

Further arguments, currently ignored.

Value

The object x, invisibly.

Examples

p_true <- matrix(c(0.02, 0.04, 0.08, 0.14,
                   0.08, 0.25, 0.42, 0.48,
                   0.25, 0.45, 0.50, 0.60), nrow = 3, byrow = TRUE)

oc <- sim_comb_boin(
  target = 0.25,
  p_true = p_true,
  n_cohort = 16,
  cohort_size = 3,
  n_trials = 200,
  seed = 123
)

print(oc)
print(oc, digits = 2)


Print Operating Characteristics of the BOIN Drug-Combination Design Across Scenarios

Description

Display the table produced by sim_comb_boin_multi, one row per scenario. The full results of a scenario are printed by printing its element of x$results.

Usage

## S3 method for class 'comb_boin_oc_multi'
print(x, digits = 1, kable = FALSE, kable_format = "pipe", ...)

Arguments

x

An object of class comb_boin_oc_multi.

digits

Integer scalar. Number of decimal places. Defaults to 1.

kable

Logical scalar. Return the table through knitr::kable() rather than printing it directly. Requires the knitr package. Defaults to FALSE.

kable_format

Character scalar passed to knitr::kable(), for example "pipe", "html" or "latex". Defaults to "pipe".

...

Further arguments, currently ignored.

Value

The object x, invisibly.

Examples

oc <- sim_comb_boin_multi(
  target = 0.30,
  scenarios = list(
    "MTD in the middle" = matrix(c(0.10, 0.20, 0.30,
                                   0.20, 0.30, 0.45), 2, byrow = TRUE),
    "All toxic"         = matrix(c(0.40, 0.50, 0.60,
                                   0.50, 0.60, 0.70), 2, byrow = TRUE)
  ),
  n_cohort = 10,
  cohort_size = 3,
  n_trials = 200,
  seed = 123
)

print(oc)


Print Simulated BOIN Drug-Combination Trials

Description

Show a compact summary of the object returned by comb_boin_simulate instead of printing the full trial arrays.

Usage

## S3 method for class 'comb_boin_trials'
print(x, ...)

Arguments

x

An object of class comb_boin_trials.

...

Further arguments, currently ignored.

Value

The object x, invisibly.

Examples

p_true <- matrix(c(0.05, 0.15, 0.30,
                   0.15, 0.30, 0.45), nrow = 2, byrow = TRUE)

trials <- comb_boin_simulate(
  target = 0.30,
  p_true = p_true,
  n_cohort = 10,
  cohort_size = 3,
  n_trials = 100,
  seed = 1
)
print(trials)


Print a 3+3 Decision Table

Description

Display the decision table produced by decision_table_3p3: one row per number of patients and range of DLTs sharing a decision, for dose escalation and, with mtd_rule = "expand", for the search for the MTD, followed by what happens once escalation stops.

Usage

## S3 method for class 'decision_table_3p3'
print(x, ...)

Arguments

x

An object of class decision_table_3p3.

...

Further arguments, currently ignored.

Details

A data frame that no longer has the columns or attributes of a decision table, for example after selecting columns, is printed as a plain data frame.

Value

The object x, invisibly.

See Also

decision_table_3p3, plot.decision_table_3p3

Examples

print(decision_table_3p3())

print(decision_table_3p3(mtd_rule = "expand"))


Print Operating Characteristics of the 3+3 Design

Description

Display the summary table produced by oc_3p3 or sim_3p3. The layout matches print.boin_oc, so a 3+3 table can be read beside a BOIN one.

Usage

## S3 method for class 'oc_3p3'
print(
  x,
  digits = 1,
  percent = FALSE,
  kable = FALSE,
  kable_format = "pipe",
  ...
)

Arguments

x

An object of class oc_3p3.

digits

Integer scalar. Number of decimal places. Defaults to 1.

percent

Logical scalar. Express the average number of patients and DLTs at each dose as a percentage of the trial total instead of a count. Defaults to FALSE.

kable

Logical scalar. Return the table through knitr::kable() rather than printing it directly, which is convenient inside a report. Requires the knitr package. Defaults to FALSE.

kable_format

Character scalar passed to knitr::kable(), for example "pipe", "html" or "latex". Defaults to "pipe".

...

Further arguments, currently ignored.

Value

The object x, invisibly.

See Also

oc_3p3, sim_3p3

Examples

oc <- oc_3p3(p_true = c(0.30, 0.48, 0.67))

print(oc)
print(oc, percent = TRUE)


Print a Comparison of Designs

Description

Print the comparison built by oc_compare: one block per scenario with one row per design.

Usage

## S3 method for class 'oc_compare'
print(x, digits = 1, ...)

Arguments

x

An object of class oc_compare.

digits

Integer scalar. Number of decimals. Defaults to 1.

...

Further arguments, currently ignored.

Value

x, invisibly.

See Also

oc_compare, plot.oc_compare

Examples

truth <- oc_scenarios(list(c(0.10, 0.25, 0.40, 0.55)), target = 0.30)
boin <- sim_boin(target = 0.30, p_true = c(0.10, 0.25, 0.40, 0.55),
                 n_cohort = 10, cohort_size = 3, n_trials = 200, seed = 1)
print(oc_compare(BOIN = boin, "3+3" = oc_3p3(c(0.10, 0.25, 0.40, 0.55)),
                 truth = truth))


Print the Operating Characteristics of Several Designs

Description

Print the table built by oc_results: for every scenario, the chosen per-dose quantities with one row per design and one column per dose (for a combination, one matrix per design with rows for drug A and columns for drug B), followed by the quantities of the whole trial with one row per design.

Usage

## S3 method for class 'oc_results'
print(x, metric = c("sel_percent", "n_pts"), digits = 1, ...)

Arguments

x

An object of class oc_results.

metric

Character vector. Per-dose quantities to print, among "sel_percent", "n_pts", "n_tox" and "n_resp". Defaults to c("sel_percent", "n_pts").

digits

Integer scalar. Number of decimals. Defaults to 1.

...

Further arguments, currently ignored.

Value

x, invisibly.

See Also

oc_results, plot.oc_results

Examples

boin <- sim_boin(target = 0.30, p_true = c(0.10, 0.25, 0.40, 0.55),
                 n_cohort = 10, cohort_size = 3, n_trials = 200, seed = 1)
print(oc_results(BOIN = boin, "3+3" = oc_3p3(c(0.10, 0.25, 0.40, 0.55))))


Print True Scenarios

Description

Print the scenarios tabulated by oc_scenarios: for a single agent, one block per scenario with the DLT and response probabilities and the utility of every dose and marks under the true MTDs and OBDs; for a combination, the same quantities as matrices (rows for drug A, columns for drug B) with the true MTDs and OBDs marked by an asterisk.

Usage

## S3 method for class 'oc_scenarios'
print(x, digits = 2, ...)

Arguments

x

An object of class oc_scenarios.

digits

Integer scalar. Number of decimals of the probabilities; the utility is printed with one decimal. Defaults to 2.

...

Further arguments, currently ignored.

Value

x, invisibly.

See Also

oc_scenarios, plot.oc_scenarios

Examples

truth <- oc_scenarios(
  list(list(p_true = c(0.05, 0.12, 0.27, 0.35, 0.50),
            p_resp = c(0.20, 0.35, 0.36, 0.37, 0.38))),
  target = 0.35, target_resp = 0.25
)
print(truth)


Print a TITE-BOIN Decision Table

Description

Display the decision table produced by tite_boin_decision_table in the layout of the published tables: one row per number of patients treated, number of DLTs and range of pending patients sharing a decision, with the boundaries on the follow-up statistic in the Escalate, Stay and De-escalate columns.

Usage

## S3 method for class 'tite_boin_decision_table'
print(x, cohort_size = NULL, digits = 2, ...)

Arguments

x

An object of class tite_boin_decision_table.

cohort_size

Integer scalar or NULL. When supplied, only the sample sizes that are multiples of cohort_size are shown, which is how the published tables are laid out.

digits

Integer scalar. Number of decimal places of the boundaries. Defaults to 2, as in the published tables.

...

Further arguments, currently ignored.

Details

A boundary shown as ">= 2.15" under Escalate means that the dose is escalated when the follow-up statistic is at least 2.15; the statistic is STFT for method = "imputation" and ESS for method = "ess". "Suspend if >= 4.23" under Escalate marks an escalation blocked by min_completed. When the table was built with a positive min_follow_up, an escalation with pending patients carries the condition on MF, for example ">= 0.22 & MF >= 0.25"; accrual is suspended when the condition on the follow-up statistic holds but the one on MF does not.

A data frame that no longer has the columns or attributes of a decision table, for example after selecting columns, is printed as a plain data frame.

Value

The object x, invisibly.

See Also

tite_boin_decision_table, plot.tite_boin_decision_table

Examples

decisions <- tite_boin_decision_table(target = 0.3, max_n = 15)

# Table S1 of Yuan et al. (2018)
print(decisions, cohort_size = 3)

# Boundaries with three decimal places
print(decisions[decisions$n == 9, ], digits = 3)


Print Operating Characteristics of a TITE-BOIN Design

Description

Display the summary produced by sim_tite_boin: the design, the table of print.boin_oc, the exposure to doses above the overdose cutoff, and the duration of the trials and the suspensions of accrual.

Usage

## S3 method for class 'tite_boin_oc'
print(
  x,
  digits = 1,
  percent = FALSE,
  kable = FALSE,
  kable_format = "pipe",
  ...
)

Arguments

x

An object of class tite_boin_oc.

digits

Integer scalar. Number of decimal places. Defaults to 1.

percent

Logical scalar. Express the average number of patients and DLTs at each dose as a percentage of the trial total instead of a count. Defaults to FALSE.

kable

Logical scalar. Return the table through knitr::kable() rather than printing it directly, which is convenient inside a report. Requires the knitr package. Defaults to FALSE.

kable_format

Character scalar passed to knitr::kable(), for example "pipe", "html" or "latex". Defaults to "pipe".

...

Further arguments, currently ignored.

Value

The object x, invisibly.

Examples

oc <- sim_tite_boin(
  target = 0.30,
  p_true = c(0.05, 0.15, 0.30, 0.45, 0.60),
  n_cohort = 10,
  cohort_size = 3,
  window = 3,
  accrual_rate = 2,
  n_trials = 200,
  seed = 123
)

print(oc)
print(oc, percent = TRUE)


Print Operating Characteristics of a TITE-BOIN Design Across Scenarios

Description

Display the table produced by sim_tite_boin_multi, one block of rows per scenario.

Usage

## S3 method for class 'tite_boin_oc_multi'
print(
  x,
  digits = 1,
  percent = FALSE,
  kable = FALSE,
  kable_format = "pipe",
  ...
)

Arguments

x

An object of class tite_boin_oc_multi.

digits

Integer scalar. Number of decimal places. Defaults to 1.

percent

Logical scalar. Express the average number of patients and DLTs at each dose as a percentage of the trial total instead of a count. Defaults to FALSE.

kable

Logical scalar. Return the table through knitr::kable(). Requires the knitr package. Defaults to FALSE.

kable_format

Character scalar passed to knitr::kable(). Defaults to "pipe".

...

Further arguments, currently ignored.

Value

The object x, invisibly.

Examples

scenarios <- list(
  list(name = "MTD at dose 3", p_true = c(0.05, 0.15, 0.30, 0.45, 0.60)),
  list(name = "All toxic",     p_true = c(0.35, 0.45, 0.55, 0.65, 0.75))
)

oc <- sim_tite_boin_multi(
  target = 0.30,
  scenarios = scenarios,
  n_cohort = 10,
  cohort_size = 3,
  window = 3,
  accrual_rate = 2,
  n_trials = 200,
  seed = 123
)

print(oc)
print(oc, percent = TRUE)


Print Simulated TITE-BOIN Trials

Description

Show a compact summary of the object returned by tite_boin_simulate instead of printing the full trial matrices.

Usage

## S3 method for class 'tite_boin_trials'
print(x, ...)

Arguments

x

An object of class tite_boin_trials.

...

Further arguments, currently ignored.

Value

The object x, invisibly.

Examples

trials <- tite_boin_simulate(
  target = 0.30,
  p_true = c(0.05, 0.15, 0.30, 0.45, 0.60),
  n_cohort = 10,
  cohort_size = 3,
  window = 3,
  accrual_rate = 2,
  n_trials = 100,
  seed = 1
)
print(trials)


Deprecated Functions in simFastBOIN

Description

These functions were renamed in version 2.0.0. They still work but issue a deprecation warning and will be removed in a future release. Their return values are those of the replacement functions, which differ from the return values of version 1.3.2, so calls should be updated rather than left in place.

Usage

get_boin_boundary(...)

get_boin_decision(...)

get_boin_stopping_boundaries(...)

get_pts_and_tox(...)

isotonic_regression(...)

select_mtd(...)

Arguments

...

Arguments passed to the replacement function. Note that the replacements use different argument names and a different argument order, so only calls that name every argument will carry over unchanged.

Value

The value of the corresponding replacement function.

Replacements

get_boin_boundary()

use boin_lambda for the interval boundaries, or boin_boundary for the integer decision boundaries.

get_boin_decision()

use boin_decision_table.

get_boin_stopping_boundaries()

use boin_boundary with extrasafe = TRUE and read the b_stop component.

get_pts_and_tox()

use boin_simulate.

isotonic_regression()

use boin_isotonic.

select_mtd()

use boin_select_mtd, which now takes the patient and DLT counts instead of precomputed isotonic estimates.


Simulate the 3+3 Design

Description

Simulate the traditional 3+3 dose-finding design and summarize the same quantities that oc_3p3 computes exactly. The two are meant to be used together: oc_3p3() gives the answer without Monte Carlo error, and this function confirms it from independent trials.

Usage

sim_3p3(
  p_true,
  n_trials = 10000,
  mtd_rule = c("previous", "expand"),
  start_dose = 1,
  overdose_cutoff = NULL,
  seed = 123
)

Arguments

p_true

Numeric vector. True DLT probability at each dose level, in increasing dose order.

n_trials

Integer scalar. Number of trials to simulate. Defaults to 10000.

mtd_rule

Character scalar, either "previous" or "expand". See oc_3p3. Defaults to "previous".

start_dose

Integer scalar. Dose level for the first cohort. Defaults to 1.

overdose_cutoff

Numeric scalar or NULL. Doses whose true DLT probability exceeds this value count as overdoses in the overdose component of the result. Defaults to NULL, which uses one third.

seed

Integer scalar or NULL. Random seed. The state of the calling session is restored on exit. Defaults to 123.

Details

The design is described under oc_3p3. Since the operating characteristics of the 3+3 design can be written in closed form, this function is a check on that closed form rather than the way to obtain the numbers. Simulation is the only option when a quantity is wanted that the closed form does not provide, such as the distribution of the sample size rather than its mean.

Value

An object of class oc_3p3, with the components described in oc_3p3. The method component is the number of trials rather than "exact".

See Also

oc_3p3, sim_boin

Examples

exact <- oc_3p3(p_true = c(0.30, 0.48, 0.67))
simulated <- sim_3p3(p_true = c(0.30, 0.48, 0.67), n_trials = 2000, seed = 1)

round(exact$sel_percent, 2)
round(simulated$sel_percent, 2)


Operating Characteristics of a BE-BOIN Design

Description

Simulate the BOIN design with backfilling and late-onset toxicity (BE-BOIN) of Chen et al. (2026) many times under one scenario of DLT and response probabilities, and summarize how often each dose is selected as the MTD, how many patients are treated and backfilled at each dose, how many DLTs and responses occur, and how long the trials last.

Usage

sim_be_boin(
  target,
  p_true,
  p_resp,
  n_cohort,
  cohort_size,
  window,
  accrual_rate,
  n_cap = 12,
  backfill_dose = c("highest", "lowest"),
  conflict_dose = c("lowest", "highest"),
  no_slot = c("wait", "leave"),
  accrual = c("exponential", "uniform", "fixed"),
  dlt_time = c("weibull", "uniform"),
  late_fraction = 0.5,
  resp_window = window,
  resp_late_fraction = 0.5,
  resp_cor = 0,
  max_pending_ratio = 0.49,
  min_completed = 0,
  min_follow_up = 0.25,
  n_trials = 10000,
  start_dose = 1,
  n_earlystop = 18,
  p_saf = NULL,
  p_tox = NULL,
  cutoff_eli = 0.95,
  extrasafe = FALSE,
  offset = 0.05,
  bound_mtd = FALSE,
  mtd_max_estimate = NULL,
  min_mtd_sample = 1,
  overdose_cutoff = NULL,
  n_earlystop_rule = c("with_stay", "simple"),
  keep_trials = FALSE,
  verbose = FALSE,
  seed = 123
)

Arguments

target

Numeric scalar. Target DLT probability, for example 0.25.

p_true

Numeric vector. True DLT probability at each dose level, in increasing dose order. The probability of a DLT within the assessment window.

p_resp

Numeric vector of the same length as p_true. True probability of a response within the response window at each dose. A response at or below a dose is what makes the dose eligible for backfilling.

n_cohort

Integer scalar. Number of cohorts in the dose escalation.

cohort_size

Integer scalar or vector. Number of patients per cohort of the dose escalation. A scalar is used for every cohort. A vector shorter than n_cohort is padded with its last element and a longer one is truncated.

window

Numeric scalar. Length of the DLT assessment window.

accrual_rate

Numeric scalar. Average number of patients arriving per unit of time, in the same unit as window.

n_cap

Integer scalar. A dose is no longer backfilled once this many patients, from the dose escalation and from backfilling together, have been treated at it. The dose escalation can still treat patients at the dose. Defaults to 12.

backfill_dose

Character scalar. Which dose receives a backfill patient when several are open: "highest" (the default, as in both articles) or "lowest".

conflict_dose

Character scalar. When the data of several backfilled doses conflict with those of the current dose, which of them anchors the pooled estimate: "lowest" (the default here, following Chen et al., 2026) or "highest" (the default of bf_boin_simulate, following Zhao et al., 2024).

no_slot

Character scalar. What happens to a patient who arrives when neither the dose escalation nor any backfill dose can take a patient: "wait" (the default), the patient waits and is treated as soon as one can, as in tite_boin_simulate; or "leave", the patient is turned away and the trial waits for the next arrival.

accrual

Character scalar. Distribution of the times between arrivals: "exponential" (the default) for a Poisson process, "uniform" for a uniform distribution on (0, 2 / accrual_rate), or "fixed" for arrivals exactly 1 / accrual_rate apart.

dlt_time

Character scalar. Distribution of the time to DLT within the window, and of the time to response within the response window: "weibull" (the default) or "uniform".

late_fraction

Numeric scalar strictly between 0 and 1. Share of the DLTs that occur in the second half of the assessment window under the Weibull distribution. Defaults to 0.5.

resp_window

Numeric scalar. Length of the window within which a response is observed. Defaults to window.

resp_late_fraction

Numeric scalar strictly between 0 and 1. Share of the responses that occur in the second half of the response window under the Weibull distribution. Defaults to 0.5.

resp_cor

Numeric scalar strictly between -1 and 1. Correlation of the Gaussian copula that links the DLT and the response of a patient; a positive value makes a response more likely in a patient with a DLT. Defaults to 0, independence.

max_pending_ratio

Numeric scalar greater than 0 and at most 1. Rule 1 of the design: the escalation is suspended when the proportion of pending patients at the current dose exceeds this value, unless the dose is de-escalated whatever their outcomes. Defaults to 0.49, which suspends when fewer than 51 percent have completed the assessment, as in Chen et al. (2026). See tite_boin_decision_table.

min_completed

Integer scalar. While some patients are pending, escalation requires at least this many patients with a completed assessment. Defaults to 0, which the design does not use. See tite_boin_decision_table.

min_follow_up

Numeric scalar between 0 and 1. Rule 2 of the design: escalation requires every pending patient at the current dose to have been followed for at least this fraction of the window. Defaults to 0.25, as in Chen et al. (2026). See tite_boin_decision_table.

n_trials

Integer scalar. Number of trials to simulate. Defaults to 10000.

start_dose

Integer scalar. Dose level for the first cohort. Defaults to 1.

n_earlystop

Integer scalar. The trial stops once this many patients, backfilled ones included, have been treated at the current dose and the design would stay there. Defaults to 18.

p_saf

Numeric scalar. Highest DLT probability deemed subtherapeutic. Defaults to 0.6 * target.

p_tox

Numeric scalar. Lowest DLT probability deemed overly toxic. Defaults to 1.4 * target.

cutoff_eli

Numeric scalar. Posterior probability cutoff for dose elimination. Defaults to 0.95.

extrasafe

Logical scalar. Apply the stricter safety stopping rule at the lowest dose. Defaults to FALSE.

offset

Numeric scalar between 0 and 0.5. Amount by which cutoff_eli is relaxed for the safety stopping rule. Defaults to 0.05.

bound_mtd

Logical scalar. Require the isotonic estimate at the selected dose to be at or below the de-escalation boundary. Defaults to FALSE.

mtd_max_estimate

Numeric scalar or NULL. Largest isotonic estimate a dose may have and still be selected as the MTD. See sim_boin.

min_mtd_sample

Integer scalar. Smallest number of patients a dose must have received to be eligible as the MTD. Defaults to 1.

overdose_cutoff

Numeric scalar or NULL. Doses whose true DLT probability exceeds this value count as overdoses in the overdose component of the result. Defaults to NULL, which uses target.

n_earlystop_rule

Character scalar, either "with_stay" or "simple". See boin_simulate.

keep_trials

Logical scalar. Keep the full trial by trial data in the result. Defaults to FALSE.

verbose

Logical scalar. Report progress while the simulation runs. Defaults to FALSE.

seed

Integer scalar or NULL. Random seed. When NULL the current state of the random number generator is used. The state of the calling session is restored on exit. Defaults to 123.

Details

The trials are simulated by be_boin_simulate, whose details describe the conduct of a trial. The MTD is selected as in sim_bf_boin.

When no dose is ever opened for backfilling, for example with every p_resp equal to 0, and with no_slot = "wait", every result that the two functions share agrees with that of sim_tite_boin with method = "imputation", the same suspension rules and the same seed.

Only the MTD is selected. The second stage of Chen et al. (2026), which randomizes patients between doses to choose the optimal biological dose, is not part of the simulation.

Value

An object of class c("be_boin_oc", "backfill_oc", "boin_oc"), with the components described in sim_bf_boin.

References

Chen, K., Zhao, Y., Takeda, K. and Yuan, Y. (2026). BE-BOIN: A Dose Optimization Design Accommodating Backfill and Late-Onset Toxicity. Therapeutic Innovation and Regulatory Science. doi:10.1007/s43441-026-00994-0

See Also

be_boin_simulate, sim_be_boin_multi, sim_bf_boin, sim_tite_boin

Examples

# A three month window with two patients a month
oc <- sim_be_boin(
  target = 0.25,
  p_true = c(0.04, 0.12, 0.25, 0.43, 0.63),
  p_resp = c(0.10, 0.20, 0.30, 0.45, 0.58),
  n_cohort = 10,
  cohort_size = 3,
  window = 3,
  accrual_rate = 2,
  n_earlystop = 9,
  n_trials = 500,
  seed = 123
)
oc


Operating Characteristics of a BE-BOIN Design Across Several Scenarios

Description

Run sim_be_boin under a list of scenarios of DLT and response probabilities that share the same design, and collect the results into one table.

Usage

sim_be_boin_multi(
  target,
  scenarios,
  n_cohort,
  cohort_size,
  window,
  accrual_rate,
  n_cap = 12,
  backfill_dose = c("highest", "lowest"),
  conflict_dose = c("lowest", "highest"),
  no_slot = c("wait", "leave"),
  accrual = c("exponential", "uniform", "fixed"),
  dlt_time = c("weibull", "uniform"),
  late_fraction = 0.5,
  resp_window = window,
  resp_late_fraction = 0.5,
  resp_cor = 0,
  max_pending_ratio = 0.49,
  min_completed = 0,
  min_follow_up = 0.25,
  n_trials = 10000,
  start_dose = 1,
  n_earlystop = 18,
  p_saf = NULL,
  p_tox = NULL,
  cutoff_eli = 0.95,
  extrasafe = FALSE,
  offset = 0.05,
  bound_mtd = FALSE,
  mtd_max_estimate = NULL,
  min_mtd_sample = 1,
  overdose_cutoff = NULL,
  n_earlystop_rule = c("with_stay", "simple"),
  keep_trials = FALSE,
  verbose = FALSE,
  seed = 123
)

Arguments

target

Numeric scalar. Target DLT probability, for example 0.25.

scenarios

A list of scenarios. Each element is a list with a p_true vector of true DLT probabilities, a p_resp vector of true response probabilities of the same length and optionally a name; without a name the list names are used, or "Scenario 1", "Scenario 2" and so on. Every scenario must have the same number of doses.

n_cohort

Integer scalar. Number of cohorts in the dose escalation.

cohort_size

Integer scalar or vector. Number of patients per cohort of the dose escalation. A scalar is used for every cohort. A vector shorter than n_cohort is padded with its last element and a longer one is truncated.

window

Numeric scalar. Length of the DLT assessment window.

accrual_rate

Numeric scalar. Average number of patients arriving per unit of time, in the same unit as window.

n_cap

Integer scalar. A dose is no longer backfilled once this many patients, from the dose escalation and from backfilling together, have been treated at it. The dose escalation can still treat patients at the dose. Defaults to 12.

backfill_dose

Character scalar. Which dose receives a backfill patient when several are open: "highest" (the default, as in both articles) or "lowest".

conflict_dose

Character scalar. When the data of several backfilled doses conflict with those of the current dose, which of them anchors the pooled estimate: "lowest" (the default here, following Chen et al., 2026) or "highest" (the default of bf_boin_simulate, following Zhao et al., 2024).

no_slot

Character scalar. What happens to a patient who arrives when neither the dose escalation nor any backfill dose can take a patient: "wait" (the default), the patient waits and is treated as soon as one can, as in tite_boin_simulate; or "leave", the patient is turned away and the trial waits for the next arrival.

accrual

Character scalar. Distribution of the times between arrivals: "exponential" (the default) for a Poisson process, "uniform" for a uniform distribution on (0, 2 / accrual_rate), or "fixed" for arrivals exactly 1 / accrual_rate apart.

dlt_time

Character scalar. Distribution of the time to DLT within the window, and of the time to response within the response window: "weibull" (the default) or "uniform".

late_fraction

Numeric scalar strictly between 0 and 1. Share of the DLTs that occur in the second half of the assessment window under the Weibull distribution. Defaults to 0.5.

resp_window

Numeric scalar. Length of the window within which a response is observed. Defaults to window.

resp_late_fraction

Numeric scalar strictly between 0 and 1. Share of the responses that occur in the second half of the response window under the Weibull distribution. Defaults to 0.5.

resp_cor

Numeric scalar strictly between -1 and 1. Correlation of the Gaussian copula that links the DLT and the response of a patient; a positive value makes a response more likely in a patient with a DLT. Defaults to 0, independence.

max_pending_ratio

Numeric scalar greater than 0 and at most 1. Rule 1 of the design: the escalation is suspended when the proportion of pending patients at the current dose exceeds this value, unless the dose is de-escalated whatever their outcomes. Defaults to 0.49, which suspends when fewer than 51 percent have completed the assessment, as in Chen et al. (2026). See tite_boin_decision_table.

min_completed

Integer scalar. While some patients are pending, escalation requires at least this many patients with a completed assessment. Defaults to 0, which the design does not use. See tite_boin_decision_table.

min_follow_up

Numeric scalar between 0 and 1. Rule 2 of the design: escalation requires every pending patient at the current dose to have been followed for at least this fraction of the window. Defaults to 0.25, as in Chen et al. (2026). See tite_boin_decision_table.

n_trials

Integer scalar. Number of trials to simulate. Defaults to 10000.

start_dose

Integer scalar. Dose level for the first cohort. Defaults to 1.

n_earlystop

Integer scalar. The trial stops once this many patients, backfilled ones included, have been treated at the current dose and the design would stay there. Defaults to 18.

p_saf

Numeric scalar. Highest DLT probability deemed subtherapeutic. Defaults to 0.6 * target.

p_tox

Numeric scalar. Lowest DLT probability deemed overly toxic. Defaults to 1.4 * target.

cutoff_eli

Numeric scalar. Posterior probability cutoff for dose elimination. Defaults to 0.95.

extrasafe

Logical scalar. Apply the stricter safety stopping rule at the lowest dose. Defaults to FALSE.

offset

Numeric scalar between 0 and 0.5. Amount by which cutoff_eli is relaxed for the safety stopping rule. Defaults to 0.05.

bound_mtd

Logical scalar. Require the isotonic estimate at the selected dose to be at or below the de-escalation boundary. Defaults to FALSE.

mtd_max_estimate

Numeric scalar or NULL. Largest isotonic estimate a dose may have and still be selected as the MTD. See sim_boin.

min_mtd_sample

Integer scalar. Smallest number of patients a dose must have received to be eligible as the MTD. Defaults to 1.

overdose_cutoff

Numeric scalar or NULL. Doses whose true DLT probability exceeds this value count as overdoses in the overdose component of the result. Defaults to NULL, which uses target.

n_earlystop_rule

Character scalar, either "with_stay" or "simple". See boin_simulate.

keep_trials

Logical scalar. Keep the full trial by trial data in the result. Defaults to FALSE.

verbose

Logical scalar. Report progress while the simulation runs. Defaults to FALSE.

seed

Integer scalar or NULL. Random seed, applied to every scenario, so that a scenario simulated here matches the same scenario simulated on its own with sim_be_boin. Defaults to 123.

Value

An object of class c("be_boin_oc_multi", "backfill_oc_multi", "boin_oc_multi"), with the components described in sim_bf_boin_multi; results holds be_boin_oc objects.

See Also

sim_be_boin, sim_bf_boin_multi

Examples

scenarios <- list(
  list(name = "MTD at dose 3", p_true = c(0.04, 0.12, 0.25, 0.43, 0.63),
       p_resp = c(0.10, 0.20, 0.30, 0.45, 0.58)),
  list(name = "Plateau", p_true = c(0.04, 0.12, 0.25, 0.43, 0.63),
       p_resp = c(0.30, 0.32, 0.35, 0.36, 0.36))
)

oc <- sim_be_boin_multi(
  target = 0.25,
  scenarios = scenarios,
  n_cohort = 10,
  cohort_size = 3,
  window = 3,
  accrual_rate = 2,
  n_earlystop = 9,
  n_trials = 200,
  seed = 123
)
oc


Operating Characteristics of a BF-BOIN Design

Description

Simulate the BOIN design with backfilling (BF-BOIN) of Zhao et al. (2024) many times under one scenario of DLT and response probabilities, and summarize how often each dose is selected as the MTD, how many patients are treated and backfilled at each dose, how many DLTs and responses occur, and how long the trials last.

Usage

sim_bf_boin(
  target,
  p_true,
  p_resp,
  n_cohort,
  cohort_size,
  window,
  accrual_rate,
  n_cap = 12,
  backfill_dose = c("highest", "lowest"),
  conflict_dose = c("highest", "lowest"),
  no_slot = c("wait", "leave"),
  accrual = c("exponential", "uniform", "fixed"),
  dlt_time = c("weibull", "uniform"),
  late_fraction = 0.5,
  resp_window = window,
  resp_late_fraction = 0.5,
  resp_cor = 0,
  n_trials = 10000,
  start_dose = 1,
  n_earlystop = 18,
  p_saf = NULL,
  p_tox = NULL,
  cutoff_eli = 0.95,
  extrasafe = FALSE,
  offset = 0.05,
  stay_on_1_of_3 = FALSE,
  bound_mtd = FALSE,
  mtd_max_estimate = NULL,
  min_mtd_sample = 1,
  overdose_cutoff = NULL,
  n_earlystop_rule = c("with_stay", "simple"),
  keep_trials = FALSE,
  verbose = FALSE,
  seed = 123
)

Arguments

target

Numeric scalar. Target DLT probability, for example 0.25.

p_true

Numeric vector. True DLT probability at each dose level, in increasing dose order. The probability of a DLT within the assessment window.

p_resp

Numeric vector of the same length as p_true. True probability of a response within the response window at each dose. A response at or below a dose is what makes the dose eligible for backfilling.

n_cohort

Integer scalar. Number of cohorts in the dose escalation.

cohort_size

Integer scalar or vector. Number of patients per cohort of the dose escalation. A scalar is used for every cohort. A vector shorter than n_cohort is padded with its last element and a longer one is truncated.

window

Numeric scalar. Length of the DLT assessment window.

accrual_rate

Numeric scalar. Average number of patients arriving per unit of time, in the same unit as window.

n_cap

Integer scalar. A dose is no longer backfilled once this many patients, from the dose escalation and from backfilling together, have been treated at it. The dose escalation can still treat patients at the dose. Defaults to 12.

backfill_dose

Character scalar. Which dose receives a backfill patient when several are open: "highest" (the default, as in both articles) or "lowest".

conflict_dose

Character scalar. When the data of several backfilled doses conflict with those of the current dose, which of them anchors the pooled estimate: "highest" (the default here, following Zhao et al., 2024) or "lowest" (the default of be_boin_simulate, following Chen et al., 2026). See the details.

no_slot

Character scalar. What happens to a patient who arrives when neither the dose escalation nor any backfill dose can take a patient: "wait" (the default), the patient waits and is treated as soon as one can, as in tite_boin_simulate; or "leave", the patient is turned away and the trial waits for the next arrival.

accrual

Character scalar. Distribution of the times between arrivals: "exponential" (the default) for a Poisson process, "uniform" for a uniform distribution on (0, 2 / accrual_rate), or "fixed" for arrivals exactly 1 / accrual_rate apart.

dlt_time

Character scalar. Distribution of the time to DLT within the window, and of the time to response within the response window: "weibull" (the default) or "uniform".

late_fraction

Numeric scalar strictly between 0 and 1. Share of the DLTs that occur in the second half of the assessment window under the Weibull distribution. Defaults to 0.5.

resp_window

Numeric scalar. Length of the window within which a response is observed. Defaults to window.

resp_late_fraction

Numeric scalar strictly between 0 and 1. Share of the responses that occur in the second half of the response window under the Weibull distribution. Defaults to 0.5.

resp_cor

Numeric scalar strictly between -1 and 1. Correlation of the Gaussian copula that links the DLT and the response of a patient; a positive value makes a response more likely in a patient with a DLT. Defaults to 0, independence.

n_trials

Integer scalar. Number of trials to simulate. Defaults to 10000.

start_dose

Integer scalar. Dose level for the first cohort. Defaults to 1.

n_earlystop

Integer scalar. The trial stops once this many patients, backfilled ones included, have been treated at the current dose and the design would stay there. Defaults to 18.

p_saf

Numeric scalar. Highest DLT probability deemed subtherapeutic. Defaults to 0.6 * target.

p_tox

Numeric scalar. Lowest DLT probability deemed overly toxic. Defaults to 1.4 * target.

cutoff_eli

Numeric scalar. Posterior probability cutoff for dose elimination. Defaults to 0.95.

extrasafe

Logical scalar. Apply the stricter safety stopping rule at the lowest dose. Defaults to FALSE.

offset

Numeric scalar between 0 and 0.5. Amount by which cutoff_eli is relaxed for the safety stopping rule. Defaults to 0.05.

stay_on_1_of_3

Logical scalar. When TRUE, one DLT out of three patients leads to staying rather than de-escalating, in every use of the decision table. Zhao et al. (2024) use this modification in their main simulation. Defaults to FALSE. See boin_boundary.

bound_mtd

Logical scalar. Require the isotonic estimate at the selected dose to be at or below the de-escalation boundary. Defaults to FALSE.

mtd_max_estimate

Numeric scalar or NULL. Largest isotonic estimate a dose may have and still be selected as the MTD. See sim_boin.

min_mtd_sample

Integer scalar. Smallest number of patients a dose must have received to be eligible as the MTD. Defaults to 1.

overdose_cutoff

Numeric scalar or NULL. Doses whose true DLT probability exceeds this value count as overdoses in the overdose component of the result. Defaults to NULL, which uses target.

n_earlystop_rule

Character scalar, either "with_stay" or "simple". See boin_simulate.

keep_trials

Logical scalar. Keep the full trial by trial data in the result. Defaults to FALSE.

verbose

Logical scalar. Report progress while the simulation runs. Defaults to FALSE.

seed

Integer scalar or NULL. Random seed. When NULL the current state of the random number generator is used. The state of the calling session is restored on exit. Defaults to 123.

Details

The trials are simulated by bf_boin_simulate, whose details describe the conduct of a trial. Once every patient has completed the assessment the MTD is selected from the data of all patients, backfilled ones included, exactly as in sim_boin, and a trial stopped for safety selects no dose. The overdose cutoffs of 60 and 80 percent refer to the size of the dose escalation, n_cohort cohorts.

When no dose is ever opened for backfilling, for example with every p_resp equal to 0, the selection and the patient counts agree with those of sim_boin under the same seed.

To reproduce Table 4 of Zhao et al. (2024), use target = 0.25, n_cohort = 10, cohort_size = 3, window = 1, accrual_rate = 3, n_earlystop = 9, stay_on_1_of_3 = TRUE, accrual = "uniform" and no_slot = "leave".

Value

An object of class c("bf_boin_oc", "backfill_oc", "boin_oc"), which has every component of the result of sim_boin, so that code written for sim_boin() also reads it, counting backfilled patients among the patients treated, and in addition

n_bf_dose

Average number of backfilled patients at each dose.

total_n_bf

Average number of backfilled patients per trial.

pct_trials_backfill

Percentage of trials with at least one backfilled patient.

n_resp_dose

Average number of patients with a response at each dose.

total_n_resp

Average number of patients with a response per trial.

duration_mean

Average trial duration, from the first arrival until every enrolled patient has completed the DLT assessment, in the time unit of window and accrual_rate.

duration_sd

Standard deviation of the trial duration.

pct_trials_suspended

Percentage of trials in which the dose escalation had to wait at least once.

avg_n_suspensions

Average number of decisions per trial at which the dose escalation had to wait.

avg_time_suspended

Average total time per trial during which the dose escalation waited.

avg_n_turned_away

Average number of patients turned away per trial, which is zero unless no_slot = "leave".

p_resp

The true response probabilities.

The trials component, when kept, holds the trial by trial data of bf_boin_simulate together with the selected MTD.

References

Zhao, Y., Yuan, Y., Korn, E. L. and Freidlin, B. (2024). Backfilling Patients in Phase I Dose-Escalation Trials Using Bayesian Optimal Interval Design (BOIN). Clinical Cancer Research, 30(4), 673-679.

See Also

bf_boin_simulate, sim_bf_boin_multi, sim_be_boin, sim_boin

Examples

# Scenario 3 of Zhao et al. (2024)
oc <- sim_bf_boin(
  target = 0.25,
  p_true = c(0.04, 0.12, 0.25, 0.43, 0.63),
  p_resp = c(0.10, 0.20, 0.30, 0.45, 0.58),
  n_cohort = 10,
  cohort_size = 3,
  window = 1,
  accrual_rate = 3,
  n_earlystop = 9,
  stay_on_1_of_3 = TRUE,
  accrual = "uniform",
  no_slot = "leave",
  n_trials = 500,
  seed = 123
)
oc


Operating Characteristics of the BF-BOIN-ET Design

Description

Simulate trials of the backfill BOIN-ET (BF-BOIN-ET) design of Takeda, Zhu and Hirakawa (2025) under one scenario of DLT and response probabilities, select the optimal biological dose (OBD) of each trial, and summarize how often each dose is selected, how many patients are treated and backfilled at each dose, and how long the trials last.

Usage

sim_bf_boin_et(
  target,
  target_resp,
  p_true,
  p_resp,
  n_cohort,
  cohort_size,
  window,
  accrual_rate,
  resp_window = window,
  accrual = c("uniform", "exponential", "fixed"),
  event_time = c("weibull", "uniform"),
  late_fraction = 0.5,
  resp_late_fraction = 0.5,
  resp_cor = 0.2,
  n_trials = 10000,
  start_dose = 1,
  n_earlystop = 12,
  n_elimination = 6,
  suspend = 0,
  p_saf = NULL,
  p_tox = NULL,
  p_saf_resp = NULL,
  cutoff_eli = 0.95,
  cutoff_eli_resp = 0.9,
  psi00 = 40,
  psi11 = 60,
  psi_resp_no_dlt = 100,
  psi_dlt_no_resp = 0,
  backfill_extension = 100,
  keep_trials = FALSE,
  verbose = FALSE,
  seed = 123
)

Arguments

target

Numeric scalar. Target DLT probability.

target_resp

Numeric scalar. Lowest response probability of interest. A dose is excluded when its response rate is likely below it, and the backfill doses start from the lowest dose whose response rate reaches the boundary eta1 derived from it.

p_true

Numeric vector. True DLT probability at each dose level, in increasing dose order.

p_resp

Numeric vector of the same length as p_true. True response probability at each dose level.

n_cohort

Integer scalar. Number of cohorts in a trial.

cohort_size

Integer scalar or vector. Number of patients per cohort. A scalar is used for every cohort. A vector shorter than n_cohort is padded with its last element and a longer one is truncated.

window

Numeric scalar. Length of the DLT assessment window.

accrual_rate

Numeric scalar. Average number of patients arriving per unit of time, in the same unit as window. The accrual argument of the 'boinet' package is the average time between arrivals, its inverse.

resp_window

Numeric scalar. Length of the response assessment window. Defaults to window.

accrual

Character scalar. Distribution of the times between arrivals: "uniform" (the default, as in 'boinet') on (0, 2 / accrual_rate), "exponential" for a Poisson process, or "fixed" for arrivals exactly 1 / accrual_rate apart.

event_time

Character scalar. Distribution of the times to DLT and to response: "weibull" (the default), with the share of the events in the second half of the window set by late_fraction and resp_late_fraction, or "uniform" on (0, window / p) for an event of probability p. With "weibull" the probabilities must be below 1.

late_fraction

Numeric scalar strictly between 0 and 1. Share of the DLTs that occur in the second half of the DLT window under the Weibull distribution. Defaults to 0.5.

resp_late_fraction

Numeric scalar strictly between 0 and 1. The same for the responses. Defaults to 0.5.

resp_cor

Numeric scalar strictly between -1 and 1. Correlation of the Gaussian copula that links the time to DLT and the time to response of a patient. Defaults to 0.2, the default of the 'boinet' package.

n_trials

Integer scalar. Number of trials to simulate. Defaults to 10000.

start_dose

Integer scalar. Dose level for the first cohort. Defaults to 1.

n_earlystop

Integer scalar. Number of patients at a dose, dose escalation and backfill together, that closes it to backfilling, and that ends the trial when it is reached at the current dose and the decision would keep the trial there. Defaults to 12, the default of the 'bfboinet' package.

n_elimination

Integer scalar. Number of patients a dose needs before it can be excluded. Defaults to 6.

suspend

Numeric scalar from 0 to 1. Share of the patients at the current dose whose DLT assessment may still be running when the next cohort starts. Defaults to 0, which waits until the DLT outcomes of the cohort are known.

p_saf

Numeric scalar or NULL. Highest DLT probability deemed subtherapeutic, used for the escalation boundary. Defaults to 0.6 * target.

p_tox

Numeric scalar or NULL. Lowest DLT probability deemed overly toxic, used for the de-escalation boundary. Defaults to 1.4 * target.

p_saf_resp

Numeric scalar or NULL. Response probability deemed subtherapeutic, used for the response boundary. Defaults to 0.6 * target_resp.

cutoff_eli

Numeric scalar. A dose with n_elimination patients or more is excluded, together with every higher dose, when the posterior probability that its DLT rate exceeds target is above this cutoff. Defaults to 0.95.

cutoff_eli_resp

Numeric scalar. Such a dose is excluded alone when the posterior probability that its response rate is below target_resp is above this cutoff. Defaults to 0.90.

psi00, psi11

Numeric scalars. Scores of a patient without DLT or response and of a patient with both, which define, with psi_resp_no_dlt and psi_dlt_no_resp, the utility used to choose the backfill dose and the OBD. Default to 40 and 60.

psi_resp_no_dlt, psi_dlt_no_resp

Numeric scalars. Scores of a patient with a response and no DLT and of a patient with a DLT and no response. Default to 100 and 0. The 'bfboinet' package calls them ppsi10 and ppsi01.

backfill_extension

Numeric scalar. Time, in the unit of window, during which backfilling continues after the last cohort has been enrolled. Defaults to 100, the value fixed in the 'bfboinet' package.

keep_trials

Logical scalar. Keep the simulated trials and the selected OBDs in the result. Defaults to FALSE.

verbose

Logical scalar. Report progress with messages. Defaults to FALSE.

seed

Integer scalar or NULL. Random seed. When NULL the current state of the random number generator is used. The state of the calling session is restored on exit. Defaults to 123.

Details

The rules are those of bfboinet::get.oc.backboinet() (version 1.1.0). A cohort is treated at the current dose. The next cohort starts with the first patient who arrives once the DLT outcomes of the cohort are known (or, with suspend, once enough of them are), and after the last cohort backfilling goes on for backfill_extension. The patients who arrive in between are backfilled one by one, when the current dose is not the lowest, to the backfill dose with the highest utility (ties to the higher dose), the DLT rates being made monotone by isotonic regression; doses with n_earlystop patients take no more.

The decision uses the DLT rate at the current dose, which counts a patient still under assessment by the fraction of the window followed, with the boundaries lambda1 and lambda2 of BOIN; after 1 DLT in 3 patients the trial stays. The backfill doses for the next cohort are the admissible doses from the lowest dose whose response rate is at least eta1 up to the current dose (escalation), the dose below it (stay) or two doses below it (de-escalation). Once excluded, a dose stays excluded, and an escalation moves past a dose excluded by its response data only. The OBD is the admissible dose up to the estimated MTD with the highest utility, from the observed rates at the last decision; ties go to the lower dose.

Possible values of stop_reason are "no_admissible_dose" (the only early stop, which selects no OBD when fewer patients than the maximum sample size have been treated), "lowest_dose_excluded", "top_dose_excluded", "no_lower_admissible_dose", "n_earlystop" and "max_cohorts".

The 'bfboinet' package reports the position of the OBD among the doses tried, which is the dose itself when the trial starts at the lowest dose; the dose is reported here in every case.

Value

An object of class bf_boin_et_oc, which is a list with components

design

"BF-BOIN-ET".

target, target_resp, p_true, p_resp

The targets and the scenario.

n_doses, n_trials

Numbers of doses and of simulated trials.

lambda1, lambda2, eta1

The escalation and de-escalation boundaries of the DLT rate and the boundary of the response rate.

sel_percent

Percentage of trials selecting each dose as the OBD.

percent_no_obd

Percentage of trials selecting no OBD.

percent_early_stop

Percentage of trials stopped because every dose was excluded.

n_pts_dose, n_bf_dose

Average numbers of patients treated and of patients backfilled at each dose.

n_tox_dose, n_resp_dose

Average numbers of DLTs and responses at each dose observed at the last decision.

n_tox_bf_dose, n_resp_bf_dose

The same among the backfilled patients.

total_n_pts, total_n_bf, total_n_tox, total_n_resp

Their averages per trial.

duration

Average time until the last patient finishes both assessments.

stop_reason_percent

Percentage of trials ending for each reason, see Details.

settings

List of the design parameters.

call

The matched call.

trials

When keep_trials is TRUE, a list with the matrices n_pts, n_bf, n_tox, n_resp, n_tox_bf and n_resp_bf (one row per trial), and the vectors cohorts_used, stop_reason, early_stop, obd (NA when none) and duration.

References

Takeda, K., Zhu, J. and Hirakawa, A. (2025). BF-BOIN-ET: A backfill Bayesian optimal interval design using efficacy and toxicity outcomes for dose optimization. Pharmaceutical Statistics, 24, e2470. doi:10.1002/pst.2470

See Also

sim_bf_boin_et_multi, sim_tite_boin_et

Examples

# The example of bfboinet::get.oc.backboinet(): windows of one month and
# three patients a month
oc <- sim_bf_boin_et(
  target = 0.30, target_resp = 0.25,
  p_true = c(0.03, 0.05, 0.20, 0.22, 0.45),
  p_resp = c(0.05, 0.10, 0.50, 0.68, 0.70),
  n_cohort = 10, cohort_size = 3, window = 1, accrual_rate = 3,
  n_trials = 300, seed = 123
)
oc


Operating Characteristics of the BF-BOIN-ET Design Across Scenarios

Description

Run sim_bf_boin_et for several scenarios of DLT and response probabilities with the same design and collect the results in one table.

Usage

sim_bf_boin_et_multi(
  target,
  target_resp,
  scenarios,
  n_cohort,
  cohort_size,
  window,
  accrual_rate,
  resp_window = window,
  accrual = c("uniform", "exponential", "fixed"),
  event_time = c("weibull", "uniform"),
  late_fraction = 0.5,
  resp_late_fraction = 0.5,
  resp_cor = 0.2,
  n_trials = 10000,
  start_dose = 1,
  n_earlystop = 12,
  n_elimination = 6,
  suspend = 0,
  p_saf = NULL,
  p_tox = NULL,
  p_saf_resp = NULL,
  cutoff_eli = 0.95,
  cutoff_eli_resp = 0.9,
  psi00 = 40,
  psi11 = 60,
  psi_resp_no_dlt = 100,
  psi_dlt_no_resp = 0,
  backfill_extension = 100,
  keep_trials = FALSE,
  verbose = FALSE,
  seed = 123
)

Arguments

target

Numeric scalar. Target DLT probability.

target_resp

Numeric scalar. Lowest response probability of interest. A dose is excluded when its response rate is likely below it, and the backfill doses start from the lowest dose whose response rate reaches the boundary eta1 derived from it.

scenarios

List of scenarios. Each element is a list with the components p_true and p_resp, and optionally name. Names of the list are used when name is absent. All scenarios must have the same number of doses.

n_cohort

Integer scalar. Number of cohorts in a trial.

cohort_size

Integer scalar or vector. Number of patients per cohort. A scalar is used for every cohort. A vector shorter than n_cohort is padded with its last element and a longer one is truncated.

window

Numeric scalar. Length of the DLT assessment window.

accrual_rate

Numeric scalar. Average number of patients arriving per unit of time, in the same unit as window. The accrual argument of the 'boinet' package is the average time between arrivals, its inverse.

resp_window

Numeric scalar. Length of the response assessment window. Defaults to window.

accrual

Character scalar. Distribution of the times between arrivals: "uniform" (the default, as in 'boinet') on (0, 2 / accrual_rate), "exponential" for a Poisson process, or "fixed" for arrivals exactly 1 / accrual_rate apart.

event_time

Character scalar. Distribution of the times to DLT and to response: "weibull" (the default), with the share of the events in the second half of the window set by late_fraction and resp_late_fraction, or "uniform" on (0, window / p) for an event of probability p. With "weibull" the probabilities must be below 1.

late_fraction

Numeric scalar strictly between 0 and 1. Share of the DLTs that occur in the second half of the DLT window under the Weibull distribution. Defaults to 0.5.

resp_late_fraction

Numeric scalar strictly between 0 and 1. The same for the responses. Defaults to 0.5.

resp_cor

Numeric scalar strictly between -1 and 1. Correlation of the Gaussian copula that links the time to DLT and the time to response of a patient. Defaults to 0.2, the default of the 'boinet' package.

n_trials

Integer scalar. Number of trials to simulate. Defaults to 10000.

start_dose

Integer scalar. Dose level for the first cohort. Defaults to 1.

n_earlystop

Integer scalar. Number of patients at a dose, dose escalation and backfill together, that closes it to backfilling, and that ends the trial when it is reached at the current dose and the decision would keep the trial there. Defaults to 12, the default of the 'bfboinet' package.

n_elimination

Integer scalar. Number of patients a dose needs before it can be excluded. Defaults to 6.

suspend

Numeric scalar from 0 to 1. Share of the patients at the current dose whose DLT assessment may still be running when the next cohort starts. Defaults to 0, which waits until the DLT outcomes of the cohort are known.

p_saf

Numeric scalar or NULL. Highest DLT probability deemed subtherapeutic, used for the escalation boundary. Defaults to 0.6 * target.

p_tox

Numeric scalar or NULL. Lowest DLT probability deemed overly toxic, used for the de-escalation boundary. Defaults to 1.4 * target.

p_saf_resp

Numeric scalar or NULL. Response probability deemed subtherapeutic, used for the response boundary. Defaults to 0.6 * target_resp.

cutoff_eli

Numeric scalar. A dose with n_elimination patients or more is excluded, together with every higher dose, when the posterior probability that its DLT rate exceeds target is above this cutoff. Defaults to 0.95.

cutoff_eli_resp

Numeric scalar. Such a dose is excluded alone when the posterior probability that its response rate is below target_resp is above this cutoff. Defaults to 0.90.

psi00, psi11

Numeric scalars. Scores of a patient without DLT or response and of a patient with both, which define, with psi_resp_no_dlt and psi_dlt_no_resp, the utility used to choose the backfill dose and the OBD. Default to 40 and 60.

psi_resp_no_dlt, psi_dlt_no_resp

Numeric scalars. Scores of a patient with a response and no DLT and of a patient with a DLT and no response. Default to 100 and 0. The 'bfboinet' package calls them ppsi10 and ppsi01.

backfill_extension

Numeric scalar. Time, in the unit of window, during which backfilling continues after the last cohort has been enrolled. Defaults to 100, the value fixed in the 'bfboinet' package.

keep_trials

Logical scalar. Keep the simulated trials and the selected OBDs in the result. Defaults to FALSE.

verbose

Logical scalar. Report progress with messages. Defaults to FALSE.

seed

Integer scalar or NULL. Random seed. When NULL the current state of the random number generator is used. The state of the calling session is restored on exit. Defaults to 123.

Details

Every scenario is simulated with the same seed.

Value

An object of class bf_boin_et_oc_multi, which is a list with components

results

Named list of bf_boin_et_oc objects, one per scenario.

summary_table

Data frame with seven rows per scenario, as shown by print.bf_boin_et_oc_multi.

scenario_names

Character vector of scenario names.

n_doses

Number of doses.

call

The matched call.

See Also

sim_bf_boin_et

Examples

scenarios <- list(
  "Example" = list(p_true = c(0.03, 0.05, 0.20, 0.22, 0.45),
                   p_resp = c(0.05, 0.10, 0.50, 0.68, 0.70)),
  "Plateau" = list(p_true = c(0.05, 0.10, 0.15, 0.30, 0.45),
                   p_resp = c(0.10, 0.30, 0.45, 0.50, 0.52))
)
res <- sim_bf_boin_et_multi(
  target = 0.30, target_resp = 0.25, scenarios = scenarios,
  n_cohort = 10, cohort_size = 3, window = 1, accrual_rate = 3,
  n_trials = 200, seed = 123
)
res


Operating Characteristics of a BF-BOIN Design Across Several Scenarios

Description

Run sim_bf_boin under a list of scenarios of DLT and response probabilities that share the same design, and collect the results into one table.

Usage

sim_bf_boin_multi(
  target,
  scenarios,
  n_cohort,
  cohort_size,
  window,
  accrual_rate,
  n_cap = 12,
  backfill_dose = c("highest", "lowest"),
  conflict_dose = c("highest", "lowest"),
  no_slot = c("wait", "leave"),
  accrual = c("exponential", "uniform", "fixed"),
  dlt_time = c("weibull", "uniform"),
  late_fraction = 0.5,
  resp_window = window,
  resp_late_fraction = 0.5,
  resp_cor = 0,
  n_trials = 10000,
  start_dose = 1,
  n_earlystop = 18,
  p_saf = NULL,
  p_tox = NULL,
  cutoff_eli = 0.95,
  extrasafe = FALSE,
  offset = 0.05,
  stay_on_1_of_3 = FALSE,
  bound_mtd = FALSE,
  mtd_max_estimate = NULL,
  min_mtd_sample = 1,
  overdose_cutoff = NULL,
  n_earlystop_rule = c("with_stay", "simple"),
  keep_trials = FALSE,
  verbose = FALSE,
  seed = 123
)

Arguments

target

Numeric scalar. Target DLT probability, for example 0.25.

scenarios

A list of scenarios. Each element is a list with a p_true vector of true DLT probabilities, a p_resp vector of true response probabilities of the same length and optionally a name; without a name the list names are used, or "Scenario 1", "Scenario 2" and so on. Every scenario must have the same number of doses.

n_cohort

Integer scalar. Number of cohorts in the dose escalation.

cohort_size

Integer scalar or vector. Number of patients per cohort of the dose escalation. A scalar is used for every cohort. A vector shorter than n_cohort is padded with its last element and a longer one is truncated.

window

Numeric scalar. Length of the DLT assessment window.

accrual_rate

Numeric scalar. Average number of patients arriving per unit of time, in the same unit as window.

n_cap

Integer scalar. A dose is no longer backfilled once this many patients, from the dose escalation and from backfilling together, have been treated at it. The dose escalation can still treat patients at the dose. Defaults to 12.

backfill_dose

Character scalar. Which dose receives a backfill patient when several are open: "highest" (the default, as in both articles) or "lowest".

conflict_dose

Character scalar. When the data of several backfilled doses conflict with those of the current dose, which of them anchors the pooled estimate: "highest" (the default here, following Zhao et al., 2024) or "lowest" (the default of be_boin_simulate, following Chen et al., 2026). See the details.

no_slot

Character scalar. What happens to a patient who arrives when neither the dose escalation nor any backfill dose can take a patient: "wait" (the default), the patient waits and is treated as soon as one can, as in tite_boin_simulate; or "leave", the patient is turned away and the trial waits for the next arrival.

accrual

Character scalar. Distribution of the times between arrivals: "exponential" (the default) for a Poisson process, "uniform" for a uniform distribution on (0, 2 / accrual_rate), or "fixed" for arrivals exactly 1 / accrual_rate apart.

dlt_time

Character scalar. Distribution of the time to DLT within the window, and of the time to response within the response window: "weibull" (the default) or "uniform".

late_fraction

Numeric scalar strictly between 0 and 1. Share of the DLTs that occur in the second half of the assessment window under the Weibull distribution. Defaults to 0.5.

resp_window

Numeric scalar. Length of the window within which a response is observed. Defaults to window.

resp_late_fraction

Numeric scalar strictly between 0 and 1. Share of the responses that occur in the second half of the response window under the Weibull distribution. Defaults to 0.5.

resp_cor

Numeric scalar strictly between -1 and 1. Correlation of the Gaussian copula that links the DLT and the response of a patient; a positive value makes a response more likely in a patient with a DLT. Defaults to 0, independence.

n_trials

Integer scalar. Number of trials to simulate. Defaults to 10000.

start_dose

Integer scalar. Dose level for the first cohort. Defaults to 1.

n_earlystop

Integer scalar. The trial stops once this many patients, backfilled ones included, have been treated at the current dose and the design would stay there. Defaults to 18.

p_saf

Numeric scalar. Highest DLT probability deemed subtherapeutic. Defaults to 0.6 * target.

p_tox

Numeric scalar. Lowest DLT probability deemed overly toxic. Defaults to 1.4 * target.

cutoff_eli

Numeric scalar. Posterior probability cutoff for dose elimination. Defaults to 0.95.

extrasafe

Logical scalar. Apply the stricter safety stopping rule at the lowest dose. Defaults to FALSE.

offset

Numeric scalar between 0 and 0.5. Amount by which cutoff_eli is relaxed for the safety stopping rule. Defaults to 0.05.

stay_on_1_of_3

Logical scalar. When TRUE, one DLT out of three patients leads to staying rather than de-escalating, in every use of the decision table. Zhao et al. (2024) use this modification in their main simulation. Defaults to FALSE. See boin_boundary.

bound_mtd

Logical scalar. Require the isotonic estimate at the selected dose to be at or below the de-escalation boundary. Defaults to FALSE.

mtd_max_estimate

Numeric scalar or NULL. Largest isotonic estimate a dose may have and still be selected as the MTD. See sim_boin.

min_mtd_sample

Integer scalar. Smallest number of patients a dose must have received to be eligible as the MTD. Defaults to 1.

overdose_cutoff

Numeric scalar or NULL. Doses whose true DLT probability exceeds this value count as overdoses in the overdose component of the result. Defaults to NULL, which uses target.

n_earlystop_rule

Character scalar, either "with_stay" or "simple". See boin_simulate.

keep_trials

Logical scalar. Keep the trial by trial data of every scenario. Defaults to FALSE.

verbose

Logical scalar. Report progress while the simulations run. Defaults to FALSE.

seed

Integer scalar or NULL. Random seed, applied to every scenario, so that a scenario simulated here matches the same scenario simulated on its own with sim_bf_boin. Defaults to 123.

Value

An object of class c("bf_boin_oc_multi", "backfill_oc_multi", "boin_oc_multi"), which is a list with components

results

Named list of bf_boin_oc objects, one per scenario.

summary_table

Data frame collecting all scenarios, with seven rows per scenario: the true DLT and response rates, the MTD selection, the patients treated, the backfilled patients, the patients with DLT and the average trial duration.

scenario_names

Character vector of scenario names.

n_doses

Number of dose levels.

call

The matched call.

See Also

sim_bf_boin, sim_be_boin_multi

Examples

# Scenarios 2 and 6 of Zhao et al. (2024)
scenarios <- list(
  list(name = "Scenario 2", p_true = c(0.12, 0.25, 0.42, 0.49, 0.55),
       p_resp = c(0.20, 0.30, 0.40, 0.50, 0.60)),
  list(name = "Scenario 6", p_true = c(0.12, 0.25, 0.42, 0.49, 0.55),
       p_resp = c(0.30, 0.35, 0.36, 0.36, 0.36))
)

oc <- sim_bf_boin_multi(
  target = 0.25,
  scenarios = scenarios,
  n_cohort = 10,
  cohort_size = 3,
  window = 1,
  accrual_rate = 3,
  n_earlystop = 9,
  stay_on_1_of_3 = TRUE,
  n_trials = 200,
  seed = 123
)
oc


Operating Characteristics of a BOIN Design

Description

Simulate a BOIN dose-finding trial many times under one dose-toxicity scenario and summarize how often each dose is selected as the MTD, how many patients are treated at each dose and how many DLTs are observed.

Usage

sim_boin(
  target,
  p_true,
  n_cohort,
  cohort_size,
  n_trials = 10000,
  start_dose = 1,
  n_earlystop = 18,
  p_saf = NULL,
  p_tox = NULL,
  cutoff_eli = 0.95,
  extrasafe = FALSE,
  offset = 0.05,
  titration = FALSE,
  stay_on_1_of_3 = FALSE,
  bound_mtd = FALSE,
  mtd_max_estimate = NULL,
  min_mtd_sample = 1,
  overdose_cutoff = NULL,
  n_earlystop_rule = c("with_stay", "simple"),
  keep_trials = FALSE,
  verbose = FALSE,
  seed = 123,
  titration_doses = NULL
)

Arguments

target

Numeric scalar. Target DLT probability, for example 0.30.

p_true

Numeric vector. True DLT probability at each dose level, in increasing dose order.

n_cohort

Integer scalar. Number of cohorts in a trial.

cohort_size

Integer scalar or vector. Number of patients per cohort. A scalar is used for every cohort. A vector shorter than n_cohort is padded with its last element and a longer one is truncated.

n_trials

Integer scalar. Number of trials to simulate. Defaults to 10000.

start_dose

Integer scalar. Dose level for the first cohort. Defaults to 1. It is ignored when titration is TRUE, because the titration phase always begins at the lowest dose.

n_earlystop

Integer scalar. The trial stops once this many patients have been treated at the current dose and the design would stay there. Defaults to 18. Set it to a value above the maximum sample size to switch this rule off.

p_saf

Numeric scalar. Highest DLT probability deemed subtherapeutic. Defaults to 0.6 * target.

p_tox

Numeric scalar. Lowest DLT probability deemed overly toxic. Defaults to 1.4 * target.

cutoff_eli

Numeric scalar. Posterior probability cutoff for dose elimination. Defaults to 0.95.

extrasafe

Logical scalar. Apply the stricter safety stopping rule at the lowest dose. Defaults to FALSE.

offset

Numeric scalar between 0 and 0.5. Amount by which cutoff_eli is relaxed for the safety stopping rule. Defaults to 0.05.

titration

Logical scalar. Start with single patient cohorts until the first DLT is seen. Ignored when the first cohort size is one. Defaults to FALSE.

stay_on_1_of_3

Logical scalar. When TRUE, one DLT out of three patients leads to staying at the current dose rather than de-escalating. Defaults to FALSE. See boin_boundary.

bound_mtd

Logical scalar. Require the isotonic estimate at the selected dose to be at or below the de-escalation boundary. Defaults to FALSE.

mtd_max_estimate

Numeric scalar or NULL. Largest isotonic estimate a dose may have and still be selected as the MTD. Supplying it bounds the selection whatever bound_mtd says, and unlike bound_mtd it can be set at or below the target rate. It changes only the selection, never the dose-finding itself. Defaults to NULL.

min_mtd_sample

Integer scalar. Smallest number of patients a dose must have received to be eligible as the MTD. Defaults to 1.

overdose_cutoff

Numeric scalar or NULL. Doses whose true DLT probability exceeds this value count as overdoses in the overdose component of the result. Defaults to NULL, which uses target.

n_earlystop_rule

Character scalar, either "with_stay" or "simple". See boin_simulate.

keep_trials

Logical scalar. Keep the full trial by trial data in the result. Defaults to FALSE.

verbose

Logical scalar. Report progress while the simulation runs. Defaults to FALSE.

seed

Integer scalar or NULL. Random seed. The state of the calling session is restored on exit. Defaults to 123.

titration_doses

Integer scalar or NULL. Highest dose level of the titration, see boin_simulate. Set it with n_earlystop = 6 for the accelerated BOIN design of Kojima et al. (2024). Defaults to NULL, every dose.

Details

The engine draws one uniform variate per patient, in enrollment order, and applies the decision rules in the order used by BOIN::get.oc(). See boin_simulate for the two places where a variate is drawn but not used. With the same seed and matching arguments the two implementations agree trial by trial, not merely on average.

Note that n_earlystop defaults to 18 here, whereas the reference implementation defaults to 100, which in practice switches the rule off.

Value

An object of class boin_oc, which is a list with components

sel_percent

Percentage of trials selecting each dose as the MTD.

percent_no_mtd

Percentage of trials ending without an MTD.

n_pts_dose

Average number of patients treated at each dose.

n_tox_dose

Average number of DLTs observed at each dose.

total_n_pts

Average total number of patients per trial.

total_n_tox

Average total number of DLTs per trial.

overdose

List describing the design's relationship with doses above overdose_cutoff. Two questions are answered separately. How far were patients exposed during the trial: pct_patients (the percentage of all simulated patients treated at such a dose, that is the probability that a patient is dosed above the cutoff), pct_patients_by_trial (the same percentage computed within each trial and then averaged), avg_n_patients, pct_trials_any, pct_trials_over_60 and pct_trials_over_80. And how often did the design end up recommending such a dose: pct_trials_mtd_above (the percentage of all trials whose selected MTD is above the cutoff) and pct_mtd_above_when_selected (the same among the trials that selected an MTD at all). The cutoff and the dose levels doses that exceed it are also returned.

stop_reason_percent

Percentage of trials by reason for stopping.

trials

Trial level data when keep_trials is TRUE, otherwise NULL.

together with the design parameters and the call.

References

Liu S. and Yuan, Y. (2015). Bayesian Optimal Interval Designs for Phase I Clinical Trials. Journal of the Royal Statistical Society: Series C, 64, 507-523.

Kojima, M., Wende, W. and Zhao, H. (2024). Tips for Accelerating BOIN Design. Therapeutic Innovation and Regulatory Science, 58, 1129-1137. doi:10.1007/s43441-024-00692-9

See Also

sim_boin_multi, boin_simulate

Examples

oc <- sim_boin(
  target = 0.30,
  p_true = c(0.05, 0.15, 0.30, 0.45, 0.60),
  n_cohort = 10,
  cohort_size = 3,
  n_trials = 500,
  seed = 123
)
oc


# A larger run with the safety options switched on
oc_safe <- sim_boin(
  target = 0.30,
  p_true = c(0.30, 0.40, 0.50, 0.60, 0.70),
  n_cohort = 20,
  cohort_size = 3,
  n_trials = 10000,
  extrasafe = TRUE,
  bound_mtd = TRUE,
  titration = TRUE,
  seed = 123
)
oc_safe

# How often are patients dosed above a true DLT rate of 0.33?
oc_cut <- sim_boin(
  target = 0.30,
  p_true = c(0.10, 0.20, 0.30, 0.42, 0.55),
  n_cohort = 20,
  cohort_size = 3,
  n_trials = 10000,
  overdose_cutoff = 0.33,
  seed = 123
)
oc_cut$overdose$pct_patients            # patients dosed above 0.33
oc_cut$overdose$pct_trials_mtd_above     # trials recommending a dose above 0.33



Operating Characteristics of the BOIN12 Design

Description

Simulate trials of the BOIN12 design of Lin et al. (2020) under one scenario of DLT and response probabilities, select the optimal biological dose (OBD) of each trial, and summarize how often each dose is selected and how many patients, DLTs and responses occur at each dose.

Usage

sim_boin12(
  target,
  target_resp,
  p_true,
  p_resp,
  n_cohort,
  cohort_size,
  n_trials = 10000,
  start_dose = 1,
  n_earlystop = NULL,
  n_earlystop_rule = c("with_stay", "simple"),
  p_saf = NULL,
  p_tox = NULL,
  cutoff_eli = 0.95,
  cutoff_eli_resp = 0.9,
  psi00 = 40,
  psi11 = 60,
  benchmark_weight = 0.5,
  utility_prior = c(1, 1),
  n_star = 6,
  n_explore = 9,
  tie_break = c("higher", "random"),
  no_candidate = c("nearest", "stop"),
  explore_from = c("any", "admissible"),
  resp_cor = 0,
  resp_cor_type = c("copula", "binary"),
  est_method = c("posterior_mean", "observed", "tail_probability"),
  keep_trials = FALSE,
  verbose = FALSE,
  seed = 123
)

Arguments

target

Numeric scalar. Highest acceptable DLT probability, called phi_T by Lin et al. (2020). It is the target of the BOIN boundaries lambda_e and lambda_d, of the admissibility of a dose and of the MTD that bounds the OBD. Lin et al. recommend a value slightly above the target of a design that only considers toxicity, for example 0.35 instead of 0.30.

target_resp

Numeric scalar. Lowest acceptable response probability, phi_E. Note that this is a lower limit, as in sim_bf_boin_et, whereas the target_resp of sim_boin_et is a target.

p_true

Numeric vector. True DLT probability at each dose.

p_resp

Numeric vector. True response probability at each dose.

n_cohort

Integer scalar. Number of cohorts in a trial.

cohort_size

Integer scalar or vector. Number of patients per cohort. A scalar is used for every cohort; a shorter vector is padded with its last element.

n_trials

Integer scalar. Number of trials to simulate. Defaults to 10000.

start_dose

Integer scalar. Dose level of the first cohort. Defaults to 1.

n_earlystop

Integer scalar or NULL. Number of patients at the current dose that ends the trial when the next cohort would stay there (see n_earlystop_rule). Defaults to NULL, which runs every trial to the maximum sample size, as in Lin et al. (2020).

n_earlystop_rule

Character scalar. "with_stay" (the default) ends the trial at n_earlystop only when the next cohort would stay at the current dose, as in the example of Zhou et al. (2022); "simple" ends it in any case.

p_saf, p_tox

Numeric scalars or NULL. Highest DLT probability deemed subtherapeutic and lowest deemed overly toxic, which give the BOIN boundaries. Default to 0.6 * target and 1.4 * target.

cutoff_eli

Numeric scalar. A dose is inadmissible, together with every higher dose, when the posterior probability that its DLT rate exceeds target is at least this cutoff. Defaults to 0.95.

cutoff_eli_resp

Numeric scalar. A dose is inadmissible when the posterior probability that its response rate is below target_resp is at least this cutoff. Defaults to 0.90.

psi00, psi11

Numeric scalars from 0 to 100. Utility of a patient without DLT and without response, and with both. The utility of a response without DLT is 100 and that of a DLT without response is 0. Default to 40 and 60, the example of Lin et al. (2020).

benchmark_weight

Numeric scalar above 0 and at most 1. The utility benchmark is benchmark_weight * u_low + (1 - benchmark_weight) * 100, where u_low is the expected utility of a dose whose DLT and response probabilities are target and target_resp, the two outcomes being independent. Defaults to 0.5, the benchmark of Lin et al. (2020); Lu et al. (2025) use 0.6.

utility_prior

Numeric vector of two positive numbers. Beta prior of the utility of a dose divided by 100. Defaults to c(1, 1).

n_star

Integer scalar. With at least this many patients at the current dose and a DLT rate between lambda_e and lambda_d, the next dose is chosen from the current dose and the dose below. Defaults to 6.

n_explore

Integer scalar. With at least this many patients at the current dose, a DLT rate below lambda_d and an untried admissible dose above, the next cohort goes to that dose. Defaults to 9.

tie_break

Character scalar. Choice among the doses of equal desirability: "higher" (the default) takes the highest of them, the rule of the BOIN12 software according to the 'escalation' package; "random" takes one of them at random, as stated in Table S2 of the Supplement of Lin et al. (2020). See Details.

no_candidate

Character scalar. What happens when none of the doses allowed for the next cohort is admissible: "nearest" (the default) goes to the admissible dose nearest to the current one; "stop" ends the trial without an OBD. See Details.

explore_from

Character scalar. Doses from which the exploration rule (see n_explore) escalates: "any" (the default) from any dose, as in the 'escalation' package; "admissible" only from an admissible dose, as the results published by Lin et al. (2020) indicate. See Details.

resp_cor

Numeric scalar between -1 and 1. Correlation between the DLT and the response of a patient, see resp_cor_type. Defaults to 0.

resp_cor_type

Character scalar. "copula" (the default) links the two outcomes by a Gaussian copula with correlation resp_cor, the bivariate normal model of Lin et al. (2020); "binary" sets the correlation of the two binary outcomes, as in boin_et_simulate.

est_method

Character scalar. Estimate of the utility of a dose: "posterior_mean" (the default), the posterior mean of the quasi-binomial model given in Section 4 of the Supplement of Lin et al. (2020); "observed", the observed mean utility, which the example of Section 6 of that Supplement reports; or "tail_probability", the desirability used during the trial, which the 'escalation' package uses.

keep_trials

Logical scalar. Keep the simulated trials and the selected OBDs in the result. Defaults to FALSE.

verbose

Logical scalar. Report progress with messages. Defaults to FALSE.

seed

Integer scalar or NULL. Random seed. The state of the calling session is restored on exit. Defaults to 123.

Details

The trials are simulated by boin12_simulate and the OBD is selected by boin12_select_obd; see there for the rules.

Value

An object of class boin12_oc, which is a list with components

design

"BOIN12".

target, target_resp, p_true, p_resp

The limits and the scenario.

n_doses, n_trials

Numbers of doses and of simulated trials.

lambda_e, lambda_d, u_benchmark

The BOIN boundaries and the utility benchmark.

sel_percent

Percentage of trials selecting each dose as the OBD.

percent_no_obd

Percentage of trials selecting no OBD.

percent_early_stop

Percentage of trials stopped because no dose was admissible or, with no_candidate = "stop", because no dose allowed for the next cohort was admissible.

n_pts_dose, n_tox_dose, n_resp_dose

Average numbers of patients, DLTs and responses at each dose.

total_n_pts, total_n_tox, total_n_resp

Their averages per trial.

stop_reason_percent

Percentage of trials ending for each reason, see boin12_simulate.

est_method

The estimate of the utility used to select the OBD.

settings

List of the design parameters.

call

The matched call.

trials, obd

The simulated trials and the selected OBDs, when keep_trials is TRUE.

References

Lin, R., Zhou, Y., Yan, F., Li, D. and Yuan, Y. (2020). BOIN12: Bayesian optimal interval phase I/II trial design for utility-based dose finding in immunotherapy and targeted therapies. JCO Precision Oncology, 4, 1393-1402. doi:10.1200/PO.20.00257

See Also

sim_boin12_multi, boin12_simulate, boin12_select_obd

Examples

# Scenario 1 of Lin et al. (2020), 36 patients in cohorts of 3
oc <- sim_boin12(
  target = 0.35, target_resp = 0.25,
  p_true = c(0.05, 0.12, 0.27, 0.35, 0.50),
  p_resp = c(0.20, 0.35, 0.36, 0.37, 0.38),
  n_cohort = 12, cohort_size = 3, n_trials = 1000, seed = 123
)
oc


Operating Characteristics of the BOIN12 Design Across Scenarios

Description

Run sim_boin12 for several scenarios of DLT and response probabilities with the same design and collect the results in one table.

Usage

sim_boin12_multi(
  target,
  target_resp,
  scenarios,
  n_cohort,
  cohort_size,
  n_trials = 10000,
  start_dose = 1,
  n_earlystop = NULL,
  n_earlystop_rule = c("with_stay", "simple"),
  p_saf = NULL,
  p_tox = NULL,
  cutoff_eli = 0.95,
  cutoff_eli_resp = 0.9,
  psi00 = 40,
  psi11 = 60,
  benchmark_weight = 0.5,
  utility_prior = c(1, 1),
  n_star = 6,
  n_explore = 9,
  tie_break = c("higher", "random"),
  no_candidate = c("nearest", "stop"),
  explore_from = c("any", "admissible"),
  resp_cor = 0,
  resp_cor_type = c("copula", "binary"),
  est_method = c("posterior_mean", "observed", "tail_probability"),
  keep_trials = FALSE,
  verbose = FALSE,
  seed = 123
)

Arguments

target

Numeric scalar. Highest acceptable DLT probability, called phi_T by Lin et al. (2020). It is the target of the BOIN boundaries lambda_e and lambda_d, of the admissibility of a dose and of the MTD that bounds the OBD. Lin et al. recommend a value slightly above the target of a design that only considers toxicity, for example 0.35 instead of 0.30.

target_resp

Numeric scalar. Lowest acceptable response probability, phi_E. Note that this is a lower limit, as in sim_bf_boin_et, whereas the target_resp of sim_boin_et is a target.

scenarios

List of scenarios. Each element is a list with the components p_true and p_resp, and optionally name. Names of the list are used when name is absent. All scenarios must have the same number of doses.

n_cohort

Integer scalar. Number of cohorts in a trial.

cohort_size

Integer scalar or vector. Number of patients per cohort. A scalar is used for every cohort; a shorter vector is padded with its last element.

n_trials

Integer scalar. Number of trials to simulate. Defaults to 10000.

start_dose

Integer scalar. Dose level of the first cohort. Defaults to 1.

n_earlystop

Integer scalar or NULL. Number of patients at the current dose that ends the trial when the next cohort would stay there (see n_earlystop_rule). Defaults to NULL, which runs every trial to the maximum sample size, as in Lin et al. (2020).

n_earlystop_rule

Character scalar. "with_stay" (the default) ends the trial at n_earlystop only when the next cohort would stay at the current dose, as in the example of Zhou et al. (2022); "simple" ends it in any case.

p_saf, p_tox

Numeric scalars or NULL. Highest DLT probability deemed subtherapeutic and lowest deemed overly toxic, which give the BOIN boundaries. Default to 0.6 * target and 1.4 * target.

cutoff_eli

Numeric scalar. A dose is inadmissible, together with every higher dose, when the posterior probability that its DLT rate exceeds target is at least this cutoff. Defaults to 0.95.

cutoff_eli_resp

Numeric scalar. A dose is inadmissible when the posterior probability that its response rate is below target_resp is at least this cutoff. Defaults to 0.90.

psi00, psi11

Numeric scalars from 0 to 100. Utility of a patient without DLT and without response, and with both. The utility of a response without DLT is 100 and that of a DLT without response is 0. Default to 40 and 60, the example of Lin et al. (2020).

benchmark_weight

Numeric scalar above 0 and at most 1. The utility benchmark is benchmark_weight * u_low + (1 - benchmark_weight) * 100, where u_low is the expected utility of a dose whose DLT and response probabilities are target and target_resp, the two outcomes being independent. Defaults to 0.5, the benchmark of Lin et al. (2020); Lu et al. (2025) use 0.6.

utility_prior

Numeric vector of two positive numbers. Beta prior of the utility of a dose divided by 100. Defaults to c(1, 1).

n_star

Integer scalar. With at least this many patients at the current dose and a DLT rate between lambda_e and lambda_d, the next dose is chosen from the current dose and the dose below. Defaults to 6.

n_explore

Integer scalar. With at least this many patients at the current dose, a DLT rate below lambda_d and an untried admissible dose above, the next cohort goes to that dose. Defaults to 9.

tie_break

Character scalar. Choice among the doses of equal desirability: "higher" (the default) takes the highest of them, the rule of the BOIN12 software according to the 'escalation' package; "random" takes one of them at random, as stated in Table S2 of the Supplement of Lin et al. (2020). See Details.

no_candidate

Character scalar. What happens when none of the doses allowed for the next cohort is admissible: "nearest" (the default) goes to the admissible dose nearest to the current one; "stop" ends the trial without an OBD. See Details.

explore_from

Character scalar. Doses from which the exploration rule (see n_explore) escalates: "any" (the default) from any dose, as in the 'escalation' package; "admissible" only from an admissible dose, as the results published by Lin et al. (2020) indicate. See Details.

resp_cor

Numeric scalar between -1 and 1. Correlation between the DLT and the response of a patient, see resp_cor_type. Defaults to 0.

resp_cor_type

Character scalar. "copula" (the default) links the two outcomes by a Gaussian copula with correlation resp_cor, the bivariate normal model of Lin et al. (2020); "binary" sets the correlation of the two binary outcomes, as in boin_et_simulate.

est_method

Character scalar. Estimate of the utility of a dose: "posterior_mean" (the default), the posterior mean of the quasi-binomial model given in Section 4 of the Supplement of Lin et al. (2020); "observed", the observed mean utility, which the example of Section 6 of that Supplement reports; or "tail_probability", the desirability used during the trial, which the 'escalation' package uses.

keep_trials

Logical scalar. Keep the simulated trials and the selected OBDs in the result. Defaults to FALSE.

verbose

Logical scalar. Report progress with messages. Defaults to FALSE.

seed

Integer scalar or NULL. Random seed. The state of the calling session is restored on exit. Defaults to 123.

Details

Every scenario is simulated with the same seed, so that a scenario simulated here matches the same scenario simulated on its own with sim_boin12.

Value

An object of class boin12_oc_multi, which is a list with components

results

Named list of boin12_oc objects, one per scenario.

summary_table

Data frame with six rows per scenario, as shown by print.boin12_oc_multi.

scenario_names

Character vector of scenario names.

n_doses

Number of doses.

call

The matched call.

See Also

sim_boin12

Examples

scenarios <- list(
  "Plateau" = list(p_true = c(0.05, 0.12, 0.27, 0.35, 0.50),
                   p_resp = c(0.20, 0.35, 0.36, 0.37, 0.38)),
  "Increasing" = list(p_true = c(0.05, 0.12, 0.27, 0.35, 0.50),
                      p_resp = c(0.01, 0.05, 0.30, 0.60, 0.60))
)
oc <- sim_boin12_multi(
  target = 0.35, target_resp = 0.25, scenarios = scenarios,
  n_cohort = 12, cohort_size = 3, n_trials = 200, seed = 1
)
oc


Operating Characteristics of the BOIN-ET Design

Description

Simulate trials of the BOIN-ET design of Takeda, Taguri and Morita (2018) under one scenario of DLT and response probabilities, select the optimal biological dose (OBD) of each trial, and summarize how often each dose is selected and how many patients, DLTs and responses occur at each dose.

Usage

sim_boin_et(
  target,
  target_resp,
  p_true,
  p_resp,
  n_cohort,
  cohort_size,
  n_trials = 10000,
  start_dose = 1,
  n_earlystop = NULL,
  p_saf = NULL,
  p_tox = NULL,
  p_saf_resp = NULL,
  cutoff_eli = 0.95,
  cutoff_eli_resp = 0.99,
  p_eli = NULL,
  p_eli_resp = NULL,
  resp_cor = 0.2,
  resp_cor_type = c("copula", "binary"),
  boinet_compatible = FALSE,
  prior = rep(1/6, 6),
  est_method = c("observed", "multi_iso", "fp_logistic"),
  obd_method = c("max_resp", "utility_weighted", "utility_truncated_linear",
    "utility_scoring"),
  w1 = 0.33,
  w2 = 1.09,
  t_low = NULL,
  t_upp = NULL,
  e_low = NULL,
  e_upp = NULL,
  psi00 = 40,
  psi11 = 60,
  keep_trials = FALSE,
  verbose = FALSE,
  seed = 123
)

Arguments

target

Numeric scalar. Target DLT probability, for example 0.30.

target_resp

Numeric scalar. Target response probability, for example 0.60.

p_true

Numeric vector. True DLT probability at each dose level, in increasing dose order.

p_resp

Numeric vector of the same length as p_true. True response probability at each dose level.

n_cohort

Integer scalar. Number of cohorts in a trial.

cohort_size

Integer scalar or vector. Number of patients per cohort. A scalar is used for every cohort. A vector shorter than n_cohort is padded with its last element and a longer one is truncated.

n_trials

Integer scalar. Number of trials to simulate. Defaults to 10000.

start_dose

Integer scalar. Dose level for the first cohort. Defaults to 1.

n_earlystop

Integer scalar or NULL. The trial stops once this many patients have been treated at any dose. Defaults to NULL, the maximum sample size, which is the default of the 'boinet' package.

p_saf

Numeric scalar. Highest DLT probability deemed subtherapeutic. Defaults to 0.1 * target, the value recommended by Takeda et al. (2018), which is far below the 0.6 * target of the BOIN design.

p_tox

Numeric scalar. Lowest DLT probability deemed overly toxic. Defaults to 1.4 * target.

p_saf_resp

Numeric scalar. Highest response probability deemed subtherapeutic. Defaults to 0.6 * target_resp.

cutoff_eli

Numeric scalar. A dose is no longer admissible when the posterior probability that its DLT rate is below p_eli falls below 1 - cutoff_eli. Defaults to 0.95.

cutoff_eli_resp

Numeric scalar. A dose is no longer admissible when the posterior probability that its response rate is above p_eli_resp falls below 1 - cutoff_eli_resp. Defaults to 0.99.

p_eli

Numeric scalar or NULL. DLT probability of the rule above. Defaults to NULL, which uses target as the 'boinet' package does. Takeda et al. (2018) used 0.40 with a cutoff of 0.90.

p_eli_resp

Numeric scalar or NULL. Response probability of the rule above. Defaults to NULL, which uses p_saf_resp as the 'boinet' package does. Takeda et al. (2018) used 0.20 with a cutoff of 0.90.

resp_cor

Numeric scalar strictly between -1 and 1. Correlation between the DLT and the response of a patient. Defaults to 0.2, the default of the 'boinet' package.

resp_cor_type

Character scalar. How resp_cor links the two outcomes: "copula" (the default) uses it as the correlation of a Gaussian copula, which is how the 'boinet' package generates its data; "binary" uses it as the correlation of the two binary outcomes, as in the simulations of Takeda et al. (2018).

boinet_compatible

Logical scalar. Apply the rules of the 'boinet' package (version 1.6.0) exactly. Defaults to FALSE, which keeps to Takeda et al. (2018), who do not allow dose skipping during escalation; see Details.

prior

Numeric vector of length 6. Prior probabilities of the six hypotheses. Defaults to rep(1 / 6, 6), the noninformative choice of the article. The third hypothesis, under which every decision is correct, does not enter the criterion.

est_method

Character scalar. Estimator of the response rates: "observed" (the default) for the observed rates, "multi_iso" for the model-averaged unimodal isotonic regression of Lin and Yin (2017), or "fp_logistic" for the fractional polynomial logistic regression of Takeda et al. (2018), which needs the 'mfp' package.

obd_method

Character scalar. Selection rule: "max_resp" (the default) for the admissible dose with the highest estimated response rate up to the estimated MTD, or the dose that maximizes the utility "utility_weighted", "utility_truncated_linear" or "utility_scoring" among the admissible doses.

w1, w2

Numeric scalars. Weights of the weighted utility q - w1 * p - w2 * p * (p > p_tox), where p and q are the estimated DLT and response rates. Default to 0.33 and 1.09.

t_low, t_upp

Numeric scalars or NULL. DLT rates between which the truncated linear utility falls from one to zero. Default to p_saf and p_tox.

e_low, e_upp

Numeric scalars or NULL. Response rates between which the truncated linear utility rises from zero to one. Default to p_saf_resp / 2 and target_resp.

psi00, psi11

Numeric scalars. Scores of the scoring utility for a patient with neither DLT nor response and for a patient with both, the scores of a response without DLT and of a DLT without response being 100 and 0. Default to 40 and 60.

keep_trials

Logical scalar. Keep the simulated trials and the selected OBDs in the result. Defaults to FALSE.

verbose

Logical scalar. Report progress with messages. Defaults to FALSE.

seed

Integer scalar or NULL. Random seed. When NULL the current state of the random number generator is used. The state of the calling session is restored on exit. Defaults to 123.

Details

The trials are simulated by boin_et_simulate and the OBD is selected by boin_et_select_obd; see there for the rules, and for how they differ from those of 'boinet' unless boinet_compatible is TRUE. The defaults of the OBD selection are those of boinet::boinet(): observed response rates, and the admissible dose with the highest response rate up to the estimated MTD.

Value

An object of class boin_et_oc, which is a list with components

design

"BOIN-ET".

target, target_resp, p_true, p_resp

The targets and the scenario.

n_doses, n_trials

Numbers of doses and of simulated trials.

lambda1, lambda2, eta1

The boundaries, see boin_et_boundary.

sel_percent

Percentage of trials selecting each dose as the OBD.

percent_no_obd

Percentage of trials selecting no OBD.

percent_early_stop

Percentage of trials stopped early.

n_pts_dose, n_tox_dose, n_resp_dose

Average numbers of patients, DLTs and responses at each dose.

total_n_pts, total_n_tox, total_n_resp

Their averages per trial.

stop_reason_percent

Percentage of trials ending for each reason, see boin_et_simulate.

est_method, obd_method

The OBD selection used.

settings

List of the design parameters.

call

The matched call.

trials, obd

The simulated trials and the selected OBDs, when keep_trials is TRUE.

References

Takeda, K., Taguri, M. and Morita, S. (2018). BOIN-ET: Bayesian optimal interval design for dose finding based on both efficacy and toxicity outcomes. Pharmaceutical Statistics, 17(4), 383-395. doi:10.1002/pst.1864

Yamaguchi, Y., Takeda, K. and Maruo, K. (2025). boinet: An R Package for Bayesian Optimal Interval Design for Dose Finding Based on Both Efficacy and Toxicity Outcomes. The R Journal, 17(2), 15-34. doi:10.32614/RJ-2025-012

See Also

sim_boin_et_multi, boin_et_simulate, boin_et_select_obd

Examples

# Scenario 1 of Takeda et al. (2018)
oc <- sim_boin_et(
  target = 0.30, target_resp = 0.60,
  p_true = c(0.05, 0.15, 0.25, 0.30, 0.35, 0.40),
  p_resp = c(0.05, 0.35, 0.55, 0.65, 0.75, 0.70),
  n_cohort = 12, cohort_size = 3, n_trials = 1000, seed = 123
)
oc

# The same trials under the scoring utility
sim_boin_et(
  target = 0.30, target_resp = 0.60,
  p_true = c(0.05, 0.15, 0.25, 0.30, 0.35, 0.40),
  p_resp = c(0.05, 0.35, 0.55, 0.65, 0.75, 0.70),
  n_cohort = 12, cohort_size = 3, n_trials = 1000,
  obd_method = "utility_scoring", seed = 123
)$sel_percent


Operating Characteristics of the BOIN-ET Design Across Scenarios

Description

Run sim_boin_et for several scenarios of DLT and response probabilities with the same design and collect the results in one table.

Usage

sim_boin_et_multi(
  target,
  target_resp,
  scenarios,
  n_cohort,
  cohort_size,
  n_trials = 10000,
  start_dose = 1,
  n_earlystop = NULL,
  p_saf = NULL,
  p_tox = NULL,
  p_saf_resp = NULL,
  cutoff_eli = 0.95,
  cutoff_eli_resp = 0.99,
  p_eli = NULL,
  p_eli_resp = NULL,
  resp_cor = 0.2,
  resp_cor_type = c("copula", "binary"),
  boinet_compatible = FALSE,
  prior = rep(1/6, 6),
  est_method = c("observed", "multi_iso", "fp_logistic"),
  obd_method = c("max_resp", "utility_weighted", "utility_truncated_linear",
    "utility_scoring"),
  w1 = 0.33,
  w2 = 1.09,
  t_low = NULL,
  t_upp = NULL,
  e_low = NULL,
  e_upp = NULL,
  psi00 = 40,
  psi11 = 60,
  keep_trials = FALSE,
  verbose = FALSE,
  seed = 123
)

Arguments

target

Numeric scalar. Target DLT probability, for example 0.30.

target_resp

Numeric scalar. Target response probability, for example 0.60.

scenarios

List of scenarios. Each element is a list with the components p_true and p_resp, and optionally name. Names of the list are used when name is absent. All scenarios must have the same number of doses.

n_cohort

Integer scalar. Number of cohorts in a trial.

cohort_size

Integer scalar or vector. Number of patients per cohort. A scalar is used for every cohort. A vector shorter than n_cohort is padded with its last element and a longer one is truncated.

n_trials

Integer scalar. Number of trials to simulate. Defaults to 10000.

start_dose

Integer scalar. Dose level for the first cohort. Defaults to 1.

n_earlystop

Integer scalar or NULL. The trial stops once this many patients have been treated at any dose. Defaults to NULL, the maximum sample size, which is the default of the 'boinet' package.

p_saf

Numeric scalar. Highest DLT probability deemed subtherapeutic. Defaults to 0.1 * target, the value recommended by Takeda et al. (2018), which is far below the 0.6 * target of the BOIN design.

p_tox

Numeric scalar. Lowest DLT probability deemed overly toxic. Defaults to 1.4 * target.

p_saf_resp

Numeric scalar. Highest response probability deemed subtherapeutic. Defaults to 0.6 * target_resp.

cutoff_eli

Numeric scalar. A dose is no longer admissible when the posterior probability that its DLT rate is below p_eli falls below 1 - cutoff_eli. Defaults to 0.95.

cutoff_eli_resp

Numeric scalar. A dose is no longer admissible when the posterior probability that its response rate is above p_eli_resp falls below 1 - cutoff_eli_resp. Defaults to 0.99.

p_eli

Numeric scalar or NULL. DLT probability of the rule above. Defaults to NULL, which uses target as the 'boinet' package does. Takeda et al. (2018) used 0.40 with a cutoff of 0.90.

p_eli_resp

Numeric scalar or NULL. Response probability of the rule above. Defaults to NULL, which uses p_saf_resp as the 'boinet' package does. Takeda et al. (2018) used 0.20 with a cutoff of 0.90.

resp_cor

Numeric scalar strictly between -1 and 1. Correlation between the DLT and the response of a patient. Defaults to 0.2, the default of the 'boinet' package.

resp_cor_type

Character scalar. How resp_cor links the two outcomes: "copula" (the default) uses it as the correlation of a Gaussian copula, which is how the 'boinet' package generates its data; "binary" uses it as the correlation of the two binary outcomes, as in the simulations of Takeda et al. (2018).

boinet_compatible

Logical scalar. Apply the rules of the 'boinet' package (version 1.6.0) exactly. Defaults to FALSE, which keeps to Takeda et al. (2018), who do not allow dose skipping during escalation; see Details.

prior

Numeric vector of length 6. Prior probabilities of the six hypotheses. Defaults to rep(1 / 6, 6), the noninformative choice of the article. The third hypothesis, under which every decision is correct, does not enter the criterion.

est_method

Character scalar. Estimator of the response rates: "observed" (the default) for the observed rates, "multi_iso" for the model-averaged unimodal isotonic regression of Lin and Yin (2017), or "fp_logistic" for the fractional polynomial logistic regression of Takeda et al. (2018), which needs the 'mfp' package.

obd_method

Character scalar. Selection rule: "max_resp" (the default) for the admissible dose with the highest estimated response rate up to the estimated MTD, or the dose that maximizes the utility "utility_weighted", "utility_truncated_linear" or "utility_scoring" among the admissible doses.

w1, w2

Numeric scalars. Weights of the weighted utility q - w1 * p - w2 * p * (p > p_tox), where p and q are the estimated DLT and response rates. Default to 0.33 and 1.09.

t_low, t_upp

Numeric scalars or NULL. DLT rates between which the truncated linear utility falls from one to zero. Default to p_saf and p_tox.

e_low, e_upp

Numeric scalars or NULL. Response rates between which the truncated linear utility rises from zero to one. Default to p_saf_resp / 2 and target_resp.

psi00, psi11

Numeric scalars. Scores of the scoring utility for a patient with neither DLT nor response and for a patient with both, the scores of a response without DLT and of a DLT without response being 100 and 0. Default to 40 and 60.

keep_trials

Logical scalar. Keep the simulated trials and the selected OBDs in the result. Defaults to FALSE.

verbose

Logical scalar. Report progress with messages. Defaults to FALSE.

seed

Integer scalar or NULL. Random seed. When NULL the current state of the random number generator is used. The state of the calling session is restored on exit. Defaults to 123.

Details

Every scenario is simulated with the same seed.

Value

An object of class boin_et_oc_multi, which is a list with components

results

Named list of boin_et_oc objects, one per scenario.

summary_table

Data frame with six rows per scenario, as shown by print.boin_et_oc_multi.

scenario_names

Character vector of scenario names.

n_doses

Number of doses.

call

The matched call.

See Also

sim_boin_et

Examples

scenarios <- list(
  list(name = "Monotone",
       p_true = c(0.05, 0.10, 0.15, 0.20, 0.25, 0.40),
       p_resp = c(0.05, 0.10, 0.25, 0.40, 0.65, 0.70)),
  list(name = "Peaked",
       p_true = c(0.05, 0.15, 0.25, 0.35, 0.45, 0.55),
       p_resp = c(0.30, 0.70, 0.60, 0.50, 0.40, 0.30))
)
sim_boin_et_multi(
  target = 0.30, target_resp = 0.60, scenarios = scenarios,
  n_cohort = 12, cohort_size = 3, n_trials = 500, seed = 123
)


Operating Characteristics of the BOIN-ETC Design

Description

Simulate trials of the BOIN-ETC design of Kakizume et al. (2024) for two drugs given together with boin_etc_simulate, select the optimal dose combination (ODC) of every trial with boin_etc_select_obd, and summarize the selection percentages and the numbers of patients, DLTs and responses at every combination.

Usage

sim_boin_etc(
  target,
  target_resp,
  p_true,
  p_resp,
  n_cohort,
  cohort_size,
  n_trials = 10000,
  subtrials = c("etc1", "etc2", "etc3"),
  n_earlystop = 6,
  etc1_start = c("diagonal", "below"),
  rule4 = c("paper", "authors_code"),
  p_saf = NULL,
  p_tox = NULL,
  p_saf_resp = NULL,
  prior = rep(1/6, 6),
  cutoff_eli = 0.95,
  p_eli = NULL,
  resp_cor = 0,
  resp_cor_type = c("copula", "binary"),
  psi00 = 40,
  psi11 = 60,
  utility_prior = c(1, 1),
  odc_tie = c("lowest", "all"),
  keep_trials = FALSE,
  verbose = FALSE,
  seed = 123
)

Arguments

target

Numeric scalar. Target DLT probability, phi.

target_resp

Numeric scalar. Target response probability, delta, as in sim_boin_et.

p_true

Numeric matrix. True DLT probability of every combination, with one row per level of drug A and one column per level of drug B. At least two levels of each drug.

p_resp

Numeric matrix of the same size. True response probability of every combination.

n_cohort

Integer scalar. Number of cohorts in a trial; with cohort_size it gives the maximum sample size.

cohort_size

Integer scalar or vector. Number of patients per cohort. A scalar is used for every cohort; a shorter vector is padded with its last element.

n_trials

Integer scalar. Number of trials to simulate. Defaults to 10000.

subtrials

Character scalar. The division of the dose matrix into subtrials and their starting combinations: "etc1" (the default), "etc2" or "etc3", BOIN-ETC1, 2 and 3 of the figures and tables of Kakizume et al. (2024). See Details.

n_earlystop

Integer scalar. A subtrial ends when the combination chosen for the next cohort has this many patients (n_stop of Kakizume et al., 2024). Defaults to 6.

etc1_start

Character scalar. Starting combination of a row subtrial of "etc1": "diagonal" (the default) one level of drug B below the candidate of the previous subtrial, as the text and the figures of Kakizume et al. (2024) state; "below" the same level of drug B, the rule of the code of the authors that produced their published results. See Details.

rule4

Character scalar. Choice among the neighboring combinations when the DLT rate is between lambda1 and lambda2 and the response rate at most eta1: "paper" (the default) the rule of the text; "authors_code" the rule of the code of the authors, needed to reproduce their results for BOIN-ETC1. See Details.

p_saf, p_tox, p_saf_resp, prior

Design parameters of the BOIN-ET boundaries, as in boin_et_boundary. The defaults give (lambda1, lambda2, eta1) = (0.14, 0.35, 0.48) for a target DLT probability of 0.30 and a target response probability of 0.60.

cutoff_eli

Numeric scalar. A combination is excluded, with the higher combinations of its subtrial, when the posterior probability that its DLT rate exceeds p_eli is above this cutoff. Defaults to 0.95.

p_eli

Numeric scalar or NULL. DLT probability of the exclusion rule. Defaults to NULL, target.

resp_cor

Numeric scalar between -1 and 1. Correlation between the DLT and the response of a patient, see resp_cor_type. Defaults to 0, as in the simulations of Kakizume et al. (2024); the BOIN-ET functions default to 0.2.

resp_cor_type

Character scalar. "copula" (the default) or "binary", as in sim_boin_et.

psi00, psi11

Numeric scalars from 0 to 100. Utilities of a patient with neither a DLT nor a response and with both; a response without DLT scores 100 and a DLT without response 0. Default to 40 and 60, the utilities (100, 40, 60, 0) of Kakizume et al. (2024).

utility_prior

Numeric vector of two positive numbers. Beta prior of the utility of a combination divided by 100. Defaults to c(1, 1).

odc_tie

Character scalar. "lowest" (the default) counts one ODC per trial, the tied candidate with the lowest sum of the levels; "all" counts every tied candidate as selected, the definition of the published percentages of Kakizume et al. (2024), so that sel_percent can add up to more than 100.

keep_trials

Logical scalar. Keep the simulated trials (trials) and the selection (obd, tied) in the result. Defaults to FALSE.

verbose

Logical scalar. Print progress messages. Defaults to FALSE.

seed

Integer scalar or NULL. Random seed. The state of the calling session is restored on exit. Defaults to 123.

Details

The percentages of patients are those of the average numbers of patients. Kakizume et al. (2024) report the average over trials of the percentage of the patients of a trial treated at the optimal combinations ( from trials, as in inst/reproduce/reproduce_Kakizume2024.R. Their optimal combinations (bold in their Table 2) are not always those with the highest true utility; oc_compare accepts them through its argument truth.

Value

An object of class boin_etc_oc, which is a list with components

design

"BOIN-ETC1", "BOIN-ETC2" or "BOIN-ETC3".

target, target_resp, p_true, p_resp

The targets and the true probabilities.

n_rows, n_cols, n_trials

Numbers of levels of drug A and drug B, and of trials.

lambda1, lambda2, eta1

The BOIN-ET boundaries.

sel_percent

Matrix of the percentage of trials selecting each combination as the ODC.

percent_no_obd, percent_early_stop

Percentages of trials selecting no ODC and stopped early.

n_pts_dose, n_tox_dose, n_resp_dose

Matrices of the average numbers of patients, DLTs and responses at each combination.

total_n_pts, total_n_tox, total_n_resp

Their totals.

mean_subtrials

Average number of subtrials run.

true_obd

Two-column matrix of the true optimal combinations: the combinations with the highest true utility among those with a DLT probability at most target.

pct_true_obd_selected, pct_patients_true_obd

Percentage of trials selecting a true optimal combination (with odc_tie = "all", the sum of sel_percent over them) and percentage of the patients treated there.

overdose

List with the cutoff (target), the combinations above it, and the percentages of trials selecting one of them (pct_selected) and of patients treated there (pct_patients).

stop_reason_percent

Percentage of trials by stopping reason.

odc_tie, settings, call

The settings used.

trials, obd, tied

With keep_trials = TRUE, the boin_etc_trials object, a two-column matrix of the selected combinations and the logical array of the tied candidates.

References

Kakizume, T., Takeda, K., Taguri, M. and Morita, S. (2024). BOIN-ETC: A Bayesian optimal interval design considering efficacy and toxicity to identify the optimal dose combinations. Statistical Methods in Medical Research, 33(4), 716-727. doi:10.1177/09622802241236936

See Also

sim_boin_etc_multi, boin_etc_simulate, boin_etc_select_obd, print.boin_etc_oc

Examples

# Scenario 1 of Kakizume et al. (2024), BOIN-ETC1 with n_stop = 6
p_true <- matrix(c(0.05, 0.10, 0.10, 0.30, 0.30, 0.50), nrow = 2)
p_resp <- matrix(c(0.10, 0.25, 0.25, 0.60, 0.60, 0.65), nrow = 2)
oc <- sim_boin_etc(
  target = 0.30, target_resp = 0.60, p_true = p_true, p_resp = p_resp,
  n_cohort = 8, cohort_size = 3, n_trials = 200, seed = 123
)
oc


Operating Characteristics of the BOIN-ETC Design Across Scenarios

Description

Run sim_boin_etc for several scenarios of DLT and response probabilities with the same design and collect the results in one table.

Usage

sim_boin_etc_multi(
  target,
  target_resp,
  scenarios,
  n_cohort,
  cohort_size,
  n_trials = 10000,
  subtrials = c("etc1", "etc2", "etc3"),
  n_earlystop = 6,
  etc1_start = c("diagonal", "below"),
  rule4 = c("paper", "authors_code"),
  p_saf = NULL,
  p_tox = NULL,
  p_saf_resp = NULL,
  prior = rep(1/6, 6),
  cutoff_eli = 0.95,
  p_eli = NULL,
  resp_cor = 0,
  resp_cor_type = c("copula", "binary"),
  psi00 = 40,
  psi11 = 60,
  utility_prior = c(1, 1),
  odc_tie = c("lowest", "all"),
  keep_trials = FALSE,
  verbose = FALSE,
  seed = 123
)

Arguments

target

Numeric scalar. Target DLT probability, phi.

target_resp

Numeric scalar. Target response probability, delta, as in sim_boin_et.

scenarios

List of scenarios. Each element is a list with the matrices p_true and p_resp (one row per level of drug A, one column per level of drug B), and optionally name. Names of the list are used when name is absent. All scenarios must have the same numbers of levels.

n_cohort

Integer scalar. Number of cohorts in a trial; with cohort_size it gives the maximum sample size.

cohort_size

Integer scalar or vector. Number of patients per cohort. A scalar is used for every cohort; a shorter vector is padded with its last element.

n_trials

Integer scalar. Number of trials to simulate. Defaults to 10000.

subtrials

Character scalar. The division of the dose matrix into subtrials and their starting combinations: "etc1" (the default), "etc2" or "etc3", BOIN-ETC1, 2 and 3 of the figures and tables of Kakizume et al. (2024). See Details.

n_earlystop

Integer scalar. A subtrial ends when the combination chosen for the next cohort has this many patients (n_stop of Kakizume et al., 2024). Defaults to 6.

etc1_start

Character scalar. Starting combination of a row subtrial of "etc1": "diagonal" (the default) one level of drug B below the candidate of the previous subtrial, as the text and the figures of Kakizume et al. (2024) state; "below" the same level of drug B, the rule of the code of the authors that produced their published results. See Details.

rule4

Character scalar. Choice among the neighboring combinations when the DLT rate is between lambda1 and lambda2 and the response rate at most eta1: "paper" (the default) the rule of the text; "authors_code" the rule of the code of the authors, needed to reproduce their results for BOIN-ETC1. See Details.

p_saf, p_tox, p_saf_resp, prior

Design parameters of the BOIN-ET boundaries, as in boin_et_boundary. The defaults give (lambda1, lambda2, eta1) = (0.14, 0.35, 0.48) for a target DLT probability of 0.30 and a target response probability of 0.60.

cutoff_eli

Numeric scalar. A combination is excluded, with the higher combinations of its subtrial, when the posterior probability that its DLT rate exceeds p_eli is above this cutoff. Defaults to 0.95.

p_eli

Numeric scalar or NULL. DLT probability of the exclusion rule. Defaults to NULL, target.

resp_cor

Numeric scalar between -1 and 1. Correlation between the DLT and the response of a patient, see resp_cor_type. Defaults to 0, as in the simulations of Kakizume et al. (2024); the BOIN-ET functions default to 0.2.

resp_cor_type

Character scalar. "copula" (the default) or "binary", as in sim_boin_et.

psi00, psi11

Numeric scalars from 0 to 100. Utilities of a patient with neither a DLT nor a response and with both; a response without DLT scores 100 and a DLT without response 0. Default to 40 and 60, the utilities (100, 40, 60, 0) of Kakizume et al. (2024).

utility_prior

Numeric vector of two positive numbers. Beta prior of the utility of a combination divided by 100. Defaults to c(1, 1).

odc_tie

Character scalar. "lowest" (the default) counts one ODC per trial, the tied candidate with the lowest sum of the levels; "all" counts every tied candidate as selected, the definition of the published percentages of Kakizume et al. (2024), so that sel_percent can add up to more than 100.

keep_trials

Logical scalar. Keep the simulated trials (trials) and the selection (obd, tied) in the result. Defaults to FALSE.

verbose

Logical scalar. Print progress messages. Defaults to FALSE.

seed

Integer scalar or NULL. Random seed. The state of the calling session is restored on exit. Defaults to 123.

Details

Every scenario is simulated with the same seed, so that a scenario simulated here matches the same scenario simulated on its own with sim_boin_etc.

Value

An object of class boin_etc_oc_multi, which is a list with components

results

Named list of boin_etc_oc objects, one per scenario.

summary_table

Data frame with one row per scenario, as shown by print.boin_etc_oc_multi.

scenario_names

Character vector of scenario names.

n_rows, n_cols

Numbers of levels of drug A and drug B.

call

The matched call.

See Also

sim_boin_etc, print.boin_etc_oc_multi

Examples

# Scenarios 1 and 2 of Kakizume et al. (2024)
scenarios <- list(
  "Scenario 1" = list(
    p_true = matrix(c(0.05, 0.10, 0.10, 0.30, 0.30, 0.50), nrow = 2),
    p_resp = matrix(c(0.10, 0.25, 0.25, 0.60, 0.60, 0.65), nrow = 2)),
  "Scenario 2" = list(
    p_true = matrix(c(0.05, 0.15, 0.15, 0.35, 0.30, 0.55), nrow = 2),
    p_resp = matrix(c(0.25, 0.60, 0.60, 0.65, 0.65, 0.70), nrow = 2))
)
res <- sim_boin_etc_multi(target = 0.30, target_resp = 0.60,
                          scenarios = scenarios, n_cohort = 8,
                          cohort_size = 3, n_trials = 200)
res


Operating Characteristics Across Several Scenarios

Description

Run sim_boin under a list of dose-toxicity scenarios that share the same design, and collect the results into one table.

Usage

sim_boin_multi(
  target,
  scenarios,
  n_cohort,
  cohort_size,
  n_trials = 10000,
  start_dose = 1,
  n_earlystop = 18,
  p_saf = NULL,
  p_tox = NULL,
  cutoff_eli = 0.95,
  extrasafe = FALSE,
  offset = 0.05,
  titration = FALSE,
  stay_on_1_of_3 = FALSE,
  bound_mtd = FALSE,
  mtd_max_estimate = NULL,
  min_mtd_sample = 1,
  overdose_cutoff = NULL,
  n_earlystop_rule = c("with_stay", "simple"),
  keep_trials = FALSE,
  verbose = FALSE,
  seed = 123,
  titration_doses = NULL
)

Arguments

target

Numeric scalar. Target DLT probability.

scenarios

A list of scenarios. Each element is a list with a name and a p_true vector, or a plain numeric vector of true DLT probabilities in which case the list names are used as scenario names. Every scenario must have the same number of doses.

n_cohort

Integer scalar. Number of cohorts in a trial.

cohort_size

Integer scalar or vector. Number of patients per cohort.

n_trials

Integer scalar. Number of trials per scenario. Defaults to 10000.

start_dose

Integer scalar. Dose level for the first cohort. Defaults to 1. It is ignored when titration is TRUE.

n_earlystop

Integer scalar. Early stopping sample size at the current dose. Defaults to 18.

p_saf

Numeric scalar. Highest DLT probability deemed subtherapeutic. Defaults to 0.6 * target.

p_tox

Numeric scalar. Lowest DLT probability deemed overly toxic. Defaults to 1.4 * target.

cutoff_eli

Numeric scalar. Posterior probability cutoff for dose elimination. Defaults to 0.95.

extrasafe

Logical scalar. Apply the stricter safety stopping rule at the lowest dose.

offset

Numeric scalar between 0 and 0.5. Relaxation of cutoff_eli for the safety stopping rule. Defaults to 0.05.

titration

Logical scalar. Start with single patient cohorts until the first DLT.

stay_on_1_of_3

Logical scalar. Make one DLT out of three patients a stay rather than a de-escalation. See boin_boundary.

bound_mtd

Logical scalar. Bound the isotonic estimate at the selected MTD by the de-escalation boundary.

mtd_max_estimate

Numeric scalar or NULL. Largest isotonic estimate a dose may have and still be selected as the MTD. See sim_boin.

min_mtd_sample

Integer scalar. Smallest number of patients for a dose to be eligible.

overdose_cutoff

Numeric scalar or NULL. Doses whose true DLT probability exceeds this value count as overdoses. Defaults to NULL, which uses target.

n_earlystop_rule

Character scalar, either "with_stay" or "simple".

keep_trials

Logical scalar. Keep the trial by trial data of every scenario.

verbose

Logical scalar. Report progress while the simulations run.

seed

Integer scalar or NULL. Random seed, applied to every scenario, so that a scenario simulated here matches the same scenario simulated on its own with sim_boin.

titration_doses

Integer scalar or NULL. Highest dose level of the titration, see boin_simulate. Set it with n_earlystop = 6 for the accelerated BOIN design of Kojima et al. (2024). Defaults to NULL, every dose.

Value

An object of class boin_oc_multi, which is a list with components

results

Named list of boin_oc objects, one per scenario.

summary_table

Data frame collecting all scenarios.

scenario_names

Character vector of scenario names.

n_doses

Number of dose levels.

call

The matched call.

See Also

sim_boin

Examples

scenarios <- list(
  list(name = "MTD at dose 3", p_true = c(0.05, 0.15, 0.30, 0.45, 0.60)),
  list(name = "All toxic",     p_true = c(0.35, 0.45, 0.55, 0.65, 0.75))
)

oc <- sim_boin_multi(
  target = 0.30,
  scenarios = scenarios,
  n_cohort = 10,
  cohort_size = 3,
  n_trials = 200,
  seed = 123
)
oc


Operating Characteristics of the BOIN Drug-Combination Design

Description

Simulate a trial of two drugs given together, run with the BOIN drug-combination design of Lin and Yin (2017), many times under one matrix of true DLT probabilities, and summarize how often each dose combination is selected as the MTD, how many patients are treated at each combination and how many DLTs are observed.

Usage

sim_comb_boin(
  target,
  p_true,
  n_cohort,
  cohort_size,
  n_trials = 10000,
  start_dose = c(1, 1),
  n_earlystop = 18,
  p_saf = NULL,
  p_tox = NULL,
  cutoff_eli = 0.95,
  extrasafe = FALSE,
  offset = 0.05,
  titration = FALSE,
  bound_mtd = FALSE,
  overdose_cutoff = NULL,
  keep_trials = FALSE,
  verbose = FALSE,
  seed = 123
)

Arguments

target

Numeric scalar. Target DLT probability, for example 0.30.

p_true

Numeric matrix. True DLT probability of each dose combination, with one row per dose level of drug A and one column per dose level of drug B, both in increasing dose order.

n_cohort

Integer scalar. Number of cohorts in a trial.

cohort_size

Integer scalar or vector. Number of patients per cohort. A scalar is used for every cohort. A vector shorter than n_cohort is padded with its last element and a longer one is truncated.

n_trials

Integer scalar. Number of trials to simulate. Defaults to 10000.

start_dose

Integer vector of length two. Dose levels of drug A and drug B for the first cohort. Defaults to c(1, 1).

n_earlystop

Integer scalar. The trial stops once this many patients have been treated at the current combination and the design would neither escalate nor de-escalate, or cannot. Defaults to 18. Set it to a value above the maximum sample size to switch this rule off.

p_saf

Numeric scalar. Highest DLT probability deemed subtherapeutic. Defaults to 0.6 * target.

p_tox

Numeric scalar. Lowest DLT probability deemed overly toxic. Defaults to 1.4 * target.

cutoff_eli

Numeric scalar. Posterior probability cutoff for eliminating a combination. Defaults to 0.95.

extrasafe

Logical scalar. Apply the stricter safety stopping rule at the lowest combination. Defaults to FALSE.

offset

Numeric scalar between 0 and 0.5. Amount by which cutoff_eli is relaxed for the safety stopping rule. Defaults to 0.05.

titration

Logical scalar. Treat one patient per combination, moving up one level of either drug, until the first DLT. Ignored when the first cohort size is one. Defaults to FALSE.

bound_mtd

Logical scalar. Require the isotonic estimate at the selected combination to be below the de-escalation boundary. Defaults to FALSE.

overdose_cutoff

Numeric scalar or NULL. Combinations whose true DLT probability exceeds this value count as overdoses in the overdose component of the result. Defaults to NULL, which uses target.

keep_trials

Logical scalar. Keep the full trial by trial data in the result. Defaults to FALSE.

verbose

Logical scalar. Report progress while the simulation runs. Defaults to FALSE.

seed

Integer scalar or NULL. Random seed. The state of the calling session is restored on exit. Defaults to 123.

Details

The trials are simulated with comb_boin_simulate and the MTD is selected with comb_boin_select_mtd. A trial stopped for safety at the lowest combination selects none. Both follow BOIN::get.oc.comb() with mtd.contour = FALSE: with the same seed and matching arguments the two implementations agree trial by trial. pct_true_mtd_selected and pct_patients_true_mtd are the quantities that the reference implementation reports as the selection percentage of the MTD and the percentage of patients treated at the MTD.

Note that n_earlystop defaults to 18 here, whereas the reference implementation defaults to 100, which in practice switches the rule off.

Only the design that searches for a single MTD combination is provided; the waterfall design of Zhang and Yuan (2016), which searches for the MTD contour, is not.

Value

An object of class comb_boin_oc, which is a list with components

sel_percent

Matrix of the percentage of trials selecting each combination as the MTD.

percent_no_mtd

Percentage of trials ending without an MTD.

n_pts_dose

Matrix of the average number of patients treated at each combination.

n_tox_dose

Matrix of the average number of DLTs observed at each combination.

total_n_pts

Average total number of patients per trial.

total_n_tox

Average total number of DLTs per trial.

true_mtd

Two-column matrix of the dose levels of drug A and drug B of the combinations whose true DLT probability is closest to target.

pct_true_mtd_selected

Percentage of trials selecting one of these combinations.

pct_patients_true_mtd

Percentage of all patients treated at one of them.

overdose

List describing the exposure to combinations above overdose_cutoff, with the components of the same list returned by sim_boin; combinations gives the dose levels of the combinations above the cutoff.

stop_reason_percent

Percentage of trials by reason for stopping.

trials

Trial level data when keep_trials is TRUE, otherwise NULL.

together with the design parameters and the call.

References

Lin, R. and Yin, G. (2017). Bayesian Optimal Interval Design for Dose Finding in Drug-Combination Trials. Statistical Methods in Medical Research, 26(5), 2155-2167.

Yan, F., Zhang, L., Zhou, Y., Pan, H., Liu, S. and Yuan, Y. (2020). BOIN: An R Package for Designing Single-Agent and Drug-Combination Dose-Finding Trials Using Bayesian Optimal Interval Designs. Journal of Statistical Software, 94(13), 1-32.

Zhang, L. and Yuan, Y. (2016). A Practical Bayesian Design to Identify the Maximum Tolerated Dose Contour for Drug Combination Trials. Statistics in Medicine, 35(27), 4924-4936.

See Also

sim_comb_boin_multi, comb_boin_simulate, comb_boin_select_mtd

Examples

# The example of Yan and colleagues (2020): three levels of drug A, four of
# drug B and a target DLT rate of 0.25
p_true <- matrix(c(0.02, 0.04, 0.08, 0.14,
                   0.08, 0.25, 0.42, 0.48,
                   0.25, 0.45, 0.50, 0.60), nrow = 3, byrow = TRUE)

oc <- sim_comb_boin(
  target = 0.25,
  p_true = p_true,
  n_cohort = 16,
  cohort_size = 3,
  n_trials = 500,
  seed = 123
)
oc


# The settings of the article, which turn early stopping off
oc_jss <- sim_comb_boin(
  target = 0.25,
  p_true = p_true,
  n_cohort = 16,
  cohort_size = 3,
  n_earlystop = 100,
  n_trials = 1000,
  seed = 6
)
oc_jss$pct_true_mtd_selected



Operating Characteristics of the Comb-BOIN12 Design

Description

Simulate trials of the Comb-BOIN12 design of Lu et al. (2025) for two drugs given together with comb_boin12_simulate, select the optimal biological dose combination (OBDC) of every trial with comb_boin12_select_obd, and summarize the selection percentages and the numbers of patients, DLTs and responses at every combination.

Usage

sim_comb_boin12(
  target,
  target_resp,
  p_true,
  p_resp,
  n_cohort,
  cohort_size,
  n_trials = 10000,
  start_dose = c(1, 1),
  n_earlystop = NULL,
  n_earlystop_rule = c("with_stay", "simple"),
  p_saf = NULL,
  p_tox = NULL,
  cutoff_eli = 0.95,
  cutoff_eli_resp = 0.9,
  extrasafe = FALSE,
  offset = 0.05,
  psi00 = 40,
  psi11 = 60,
  benchmark_weight = 0.5,
  utility_prior = c(1, 1),
  n_star = 6,
  tie_break = c("higher", "random"),
  no_candidate = c("nearest", "stop"),
  resp_cor = 0,
  resp_cor_type = c("copula", "binary"),
  est_method = c("logistic", "observed"),
  obd_bound = c("rectangle", "contour"),
  dose_a = NULL,
  dose_b = NULL,
  logistic_scale = c(2.5, 2.5),
  n_draws = 4000,
  keep_trials = FALSE,
  verbose = FALSE,
  seed = 123
)

Arguments

target

Numeric scalar. Highest acceptable DLT probability, phi_T. It is the target of the BOIN boundaries lambda_e and lambda_d, of the admissibility of a combination and of the MTD combination that bounds the OBD combination.

target_resp

Numeric scalar. Lowest acceptable response probability, phi_E, as in sim_boin12.

p_true

Numeric matrix. True DLT probability of every combination, with one row per level of drug A and one column per level of drug B.

p_resp

Numeric matrix of the same size. True response probability of every combination.

n_cohort

Integer scalar. Number of cohorts in a trial.

cohort_size

Integer scalar or vector. Number of patients per cohort. A scalar is used for every cohort; a shorter vector is padded with its last element.

n_trials

Integer scalar. Number of trials to simulate. Defaults to 10000.

start_dose

Integer vector of length 2. Levels of drug A and drug B of the first cohort. Defaults to c(1, 1).

n_earlystop

Integer scalar or NULL. Number of patients at the current combination that ends the trial when the next cohort would stay there (see n_earlystop_rule). Defaults to NULL, which runs every trial to the maximum sample size, as in Lu et al. (2025).

n_earlystop_rule

Character scalar. "with_stay" (the default) ends the trial at n_earlystop only when the next cohort would stay at the current combination; "simple" ends it in any case.

p_saf, p_tox

Numeric scalars or NULL. Highest DLT probability deemed subtherapeutic and lowest deemed overly toxic, which give the BOIN boundaries. Default to 0.6 * target and 1.4 * target.

cutoff_eli

Numeric scalar. A combination is inadmissible, together with every combination with at least the same levels of both drugs, when the posterior probability that its DLT rate exceeds target is at least this cutoff. Defaults to 0.95.

cutoff_eli_resp

Numeric scalar. A combination is inadmissible when the posterior probability that its response rate is below target_resp is at least this cutoff. Defaults to 0.90.

extrasafe

Logical scalar. Apply the cutoff cutoff_eli - offset to the lowest combination, as Lu et al. (2025) do with 0.85. Defaults to FALSE.

offset

Numeric scalar. Amount by which cutoff_eli is lowered at the lowest combination when extrasafe is TRUE. Defaults to 0.05, as in sim_comb_boin; Lu et al. (2025) use 0.10.

psi00, psi11

Numeric scalars from 0 to 100. Utility of a patient without DLT and without response, and with both, as in sim_boin12. Default to 40 and 60. The utility pE - wT * pT of Lu et al. (2025) is psi00 = 100 * wT / (1 + wT) and psi11 = 100 / (1 + wT); their wT = 0.11 is psi00 = 9.90991 and psi11 = 90.09009.

benchmark_weight

Numeric scalar above 0 and at most 1. Weight of the lowest acceptable utility in the utility benchmark, as in sim_boin12; it is the weight w_u of Lu et al. (2025), who use 0.6. Defaults to 0.5.

utility_prior

Numeric vector of two positive numbers. Beta prior of the utility of a combination divided by 100. Defaults to c(1, 1).

n_star

Integer scalar. With at least this many patients at the current combination and a DLT rate between lambda_e and lambda_d, the next combination is chosen from the current one and the two below it. Defaults to 6.

tie_break

Character scalar. Choice among the combinations of equal desirability: "higher" (the default) keeps those with the highest sum of the two levels and draws one of them at random when several remain; "random" draws one of all the tied combinations. See Details.

no_candidate

Character scalar. What happens when none of the combinations allowed for the next cohort is admissible: "nearest" (the default) goes to the admissible combination nearest to the current one; "stop" ends the trial without an OBD combination. See Details.

resp_cor

Numeric scalar between -1 and 1. Correlation between the DLT and the response of a patient, see resp_cor_type. Defaults to 0.

resp_cor_type

Character scalar. "copula" (the default) or "binary", as in sim_boin12.

est_method

Character scalar. Estimate of the response probability: "logistic" (the default) the posterior mean under the logistic model of Lu et al. (2025), see Details; "observed" the observed response rate.

obd_bound

Character scalar. Combinations from which the OBDC is chosen: "rectangle" (the default) those with both levels at most those of the MTDC, as Lu et al. (2025) write; "contour" those, in every column (level of drug B), at most the combination of that column whose isotonic DLT rate is closest to target, the rule that reproduces the results published by Lu et al. (2025). See Details.

dose_a, dose_b

Numeric vectors or NULL. Dose values of the levels of drug A and of drug B in the logistic model. Default to NULL, the level numbers. Each is standardized to mean 0 and standard deviation 0.5.

logistic_scale

Numeric vector of two positive numbers. Scales of the Cauchy priors of the intercept and of the other coefficients of the logistic model. Defaults to c(2.5, 2.5), as in Lu et al. (2025).

n_draws

Integer scalar. Number of points of the importance sampling of the logistic model. Defaults to 4000.

keep_trials

Logical scalar. Keep the simulated trials (trials) and the selected combinations (obd) in the result. Defaults to FALSE.

verbose

Logical scalar. Print progress messages. Defaults to FALSE.

seed

Integer scalar or NULL. Random seed. The state of the calling session is restored on exit. Defaults to 123.

Details

The percentages of patients are those of the average numbers of patients. Lu et al. (2025) report the average over trials of the number of patients as a percentage of the maximum sample size; with keep_trials = TRUE it can be computed from trials, as in inst/reproduce/reproduce_Lu2025.R.

With the logistic estimate, each trial takes a few milliseconds to select; est_method = "observed" is much faster.

Value

An object of class comb_boin12_oc, which is a list with components

design

"Comb-BOIN12".

target, target_resp, p_true, p_resp

The limits and the true probabilities.

n_rows, n_cols, n_trials

Numbers of levels of drug A and drug B, and of trials.

lambda_e, lambda_d, u_benchmark

The BOIN boundaries and the utility benchmark (scale 0 to 100).

sel_percent

Matrix of the percentage of trials selecting each combination as the OBDC.

percent_no_obd, percent_early_stop

Percentages of trials selecting no OBDC and stopped early.

n_pts_dose, n_tox_dose, n_resp_dose

Matrices of the average numbers of patients, DLTs and responses at each combination.

total_n_pts, total_n_tox, total_n_resp

Their totals.

true_obd

Two-column matrix of the true OBDCs: the combinations with the highest true utility among those with a DLT probability at most target.

pct_true_obd_selected, pct_patients_true_obd

Percentage of trials selecting a true OBDC and percentage of the patients treated there.

overdose

List with the cutoff (target), the combinations above it, and the percentages of trials selecting one of them (pct_selected) and of patients treated there (pct_patients).

stop_reason_percent

Percentage of trials by stopping reason.

est_method, obd_bound, settings, call

The settings used.

trials, obd

With keep_trials = TRUE, the comb_boin12_trials object and a two-column matrix of the selected combinations.

References

Lu, M., Zhang, J., Yuan, Y. and Lin, R. (2025). Comb-BOIN12: A utility-based Bayesian optimal interval design for dose optimization in cancer drug-combination trials. Statistics in Biopharmaceutical Research, 17(2), 266-276. doi:10.1080/19466315.2024.2370403

See Also

sim_comb_boin12_multi, comb_boin12_simulate, comb_boin12_select_obd, print.comb_boin12_oc

Examples

# Scenario 16 of Lu et al. (2025), with their design settings
p_true <- matrix(c(0.05, 0.10, 0.15, 0.15, 0.20, 0.45), nrow = 2)
p_resp <- matrix(c(0.10, 0.20, 0.30, 0.40, 0.50, 0.60), nrow = 2)
oc <- sim_comb_boin12(
  target = 0.33, target_resp = 0.2, p_true = p_true, p_resp = p_resp,
  n_cohort = 14, cohort_size = 3, n_trials = 200,
  psi00 = 100 * 0.11 / 1.11, psi11 = 100 / 1.11, benchmark_weight = 0.6,
  extrasafe = TRUE, offset = 0.10, dose_a = c(100, 200),
  dose_b = c(50, 100, 200), seed = 123
)
oc


Operating Characteristics of the Comb-BOIN12 Design Across Scenarios

Description

Run sim_comb_boin12 for several scenarios of DLT and response probabilities with the same design and collect the results in one table.

Usage

sim_comb_boin12_multi(
  target,
  target_resp,
  scenarios,
  n_cohort,
  cohort_size,
  n_trials = 10000,
  start_dose = c(1, 1),
  n_earlystop = NULL,
  n_earlystop_rule = c("with_stay", "simple"),
  p_saf = NULL,
  p_tox = NULL,
  cutoff_eli = 0.95,
  cutoff_eli_resp = 0.9,
  extrasafe = FALSE,
  offset = 0.05,
  psi00 = 40,
  psi11 = 60,
  benchmark_weight = 0.5,
  utility_prior = c(1, 1),
  n_star = 6,
  tie_break = c("higher", "random"),
  no_candidate = c("nearest", "stop"),
  resp_cor = 0,
  resp_cor_type = c("copula", "binary"),
  est_method = c("logistic", "observed"),
  obd_bound = c("rectangle", "contour"),
  dose_a = NULL,
  dose_b = NULL,
  logistic_scale = c(2.5, 2.5),
  n_draws = 4000,
  keep_trials = FALSE,
  verbose = FALSE,
  seed = 123
)

Arguments

target

Numeric scalar. Highest acceptable DLT probability, phi_T. It is the target of the BOIN boundaries lambda_e and lambda_d, of the admissibility of a combination and of the MTD combination that bounds the OBD combination.

target_resp

Numeric scalar. Lowest acceptable response probability, phi_E, as in sim_boin12.

scenarios

List of scenarios. Each element is a list with the matrices p_true and p_resp (one row per level of drug A, one column per level of drug B), and optionally name. Names of the list are used when name is absent. All scenarios must have the same numbers of levels.

n_cohort

Integer scalar. Number of cohorts in a trial.

cohort_size

Integer scalar or vector. Number of patients per cohort. A scalar is used for every cohort; a shorter vector is padded with its last element.

n_trials

Integer scalar. Number of trials to simulate. Defaults to 10000.

start_dose

Integer vector of length 2. Levels of drug A and drug B of the first cohort. Defaults to c(1, 1).

n_earlystop

Integer scalar or NULL. Number of patients at the current combination that ends the trial when the next cohort would stay there (see n_earlystop_rule). Defaults to NULL, which runs every trial to the maximum sample size, as in Lu et al. (2025).

n_earlystop_rule

Character scalar. "with_stay" (the default) ends the trial at n_earlystop only when the next cohort would stay at the current combination; "simple" ends it in any case.

p_saf, p_tox

Numeric scalars or NULL. Highest DLT probability deemed subtherapeutic and lowest deemed overly toxic, which give the BOIN boundaries. Default to 0.6 * target and 1.4 * target.

cutoff_eli

Numeric scalar. A combination is inadmissible, together with every combination with at least the same levels of both drugs, when the posterior probability that its DLT rate exceeds target is at least this cutoff. Defaults to 0.95.

cutoff_eli_resp

Numeric scalar. A combination is inadmissible when the posterior probability that its response rate is below target_resp is at least this cutoff. Defaults to 0.90.

extrasafe

Logical scalar. Apply the cutoff cutoff_eli - offset to the lowest combination, as Lu et al. (2025) do with 0.85. Defaults to FALSE.

offset

Numeric scalar. Amount by which cutoff_eli is lowered at the lowest combination when extrasafe is TRUE. Defaults to 0.05, as in sim_comb_boin; Lu et al. (2025) use 0.10.

psi00, psi11

Numeric scalars from 0 to 100. Utility of a patient without DLT and without response, and with both, as in sim_boin12. Default to 40 and 60. The utility pE - wT * pT of Lu et al. (2025) is psi00 = 100 * wT / (1 + wT) and psi11 = 100 / (1 + wT); their wT = 0.11 is psi00 = 9.90991 and psi11 = 90.09009.

benchmark_weight

Numeric scalar above 0 and at most 1. Weight of the lowest acceptable utility in the utility benchmark, as in sim_boin12; it is the weight w_u of Lu et al. (2025), who use 0.6. Defaults to 0.5.

utility_prior

Numeric vector of two positive numbers. Beta prior of the utility of a combination divided by 100. Defaults to c(1, 1).

n_star

Integer scalar. With at least this many patients at the current combination and a DLT rate between lambda_e and lambda_d, the next combination is chosen from the current one and the two below it. Defaults to 6.

tie_break

Character scalar. Choice among the combinations of equal desirability: "higher" (the default) keeps those with the highest sum of the two levels and draws one of them at random when several remain; "random" draws one of all the tied combinations. See Details.

no_candidate

Character scalar. What happens when none of the combinations allowed for the next cohort is admissible: "nearest" (the default) goes to the admissible combination nearest to the current one; "stop" ends the trial without an OBD combination. See Details.

resp_cor

Numeric scalar between -1 and 1. Correlation between the DLT and the response of a patient, see resp_cor_type. Defaults to 0.

resp_cor_type

Character scalar. "copula" (the default) or "binary", as in sim_boin12.

est_method

Character scalar. Estimate of the response probability: "logistic" (the default) the posterior mean under the logistic model of Lu et al. (2025), see Details; "observed" the observed response rate.

obd_bound

Character scalar. Combinations from which the OBDC is chosen: "rectangle" (the default) those with both levels at most those of the MTDC, as Lu et al. (2025) write; "contour" those, in every column (level of drug B), at most the combination of that column whose isotonic DLT rate is closest to target, the rule that reproduces the results published by Lu et al. (2025). See Details.

dose_a, dose_b

Numeric vectors or NULL. Dose values of the levels of drug A and of drug B in the logistic model. Default to NULL, the level numbers. Each is standardized to mean 0 and standard deviation 0.5.

logistic_scale

Numeric vector of two positive numbers. Scales of the Cauchy priors of the intercept and of the other coefficients of the logistic model. Defaults to c(2.5, 2.5), as in Lu et al. (2025).

n_draws

Integer scalar. Number of points of the importance sampling of the logistic model. Defaults to 4000.

keep_trials

Logical scalar. Keep the simulated trials (trials) and the selected combinations (obd) in the result. Defaults to FALSE.

verbose

Logical scalar. Print progress messages. Defaults to FALSE.

seed

Integer scalar or NULL. Random seed. The state of the calling session is restored on exit. Defaults to 123.

Details

Every scenario is simulated with the same seed, so that a scenario simulated here matches the same scenario simulated on its own with sim_comb_boin12.

Value

An object of class comb_boin12_oc_multi, which is a list with components

results

Named list of comb_boin12_oc objects, one per scenario.

summary_table

Data frame with one row per scenario, as shown by print.comb_boin12_oc_multi.

scenario_names

Character vector of scenario names.

n_rows, n_cols

Numbers of levels of drug A and drug B.

call

The matched call.

See Also

sim_comb_boin12

Examples

# Scenarios 16 and 17 of Lu et al. (2025)
scenarios <- list(
  "Scenario 16" = list(
    p_true = matrix(c(0.05, 0.10, 0.15, 0.15, 0.20, 0.45), nrow = 2),
    p_resp = matrix(c(0.10, 0.20, 0.30, 0.40, 0.50, 0.60), nrow = 2)),
  "Scenario 17" = list(
    p_true = matrix(c(0.05, 0.10, 0.15, 0.20, 0.40, 0.50), nrow = 2),
    p_resp = matrix(c(0.10, 0.20, 0.30, 0.40, 0.50, 0.55), nrow = 2))
)
oc <- sim_comb_boin12_multi(
  target = 0.33, target_resp = 0.2, scenarios = scenarios,
  n_cohort = 14, cohort_size = 3, n_trials = 100,
  psi00 = 100 * 0.11 / 1.11, psi11 = 100 / 1.11, benchmark_weight = 0.6,
  extrasafe = TRUE, offset = 0.10, seed = 1
)
oc


Operating Characteristics of the BOIN Drug-Combination Design Across Scenarios

Description

Run sim_comb_boin under a list of matrices of true DLT probabilities that share the same design, and collect the main results into one table.

Usage

sim_comb_boin_multi(
  target,
  scenarios,
  n_cohort,
  cohort_size,
  n_trials = 10000,
  start_dose = c(1, 1),
  n_earlystop = 18,
  p_saf = NULL,
  p_tox = NULL,
  cutoff_eli = 0.95,
  extrasafe = FALSE,
  offset = 0.05,
  titration = FALSE,
  bound_mtd = FALSE,
  overdose_cutoff = NULL,
  keep_trials = FALSE,
  verbose = FALSE,
  seed = 123
)

Arguments

target

Numeric scalar. Target DLT probability.

scenarios

A list of scenarios. Each element is a list with a name and a p_true matrix, or a plain matrix of true DLT probabilities in which case the list names are used as scenario names. Every matrix must have the same numbers of rows (levels of drug A) and columns (levels of drug B).

n_cohort

Integer scalar. Number of cohorts in a trial.

cohort_size

Integer scalar or vector. Number of patients per cohort.

n_trials

Integer scalar. Number of trials per scenario. Defaults to 10000.

start_dose

Integer vector of length two. Dose levels of drug A and drug B for the first cohort. Defaults to c(1, 1).

n_earlystop

Integer scalar. Early stopping sample size at the current combination. Defaults to 18.

p_saf

Numeric scalar. Highest DLT probability deemed subtherapeutic. Defaults to 0.6 * target.

p_tox

Numeric scalar. Lowest DLT probability deemed overly toxic. Defaults to 1.4 * target.

cutoff_eli

Numeric scalar. Posterior probability cutoff for eliminating a combination. Defaults to 0.95.

extrasafe

Logical scalar. Apply the stricter safety stopping rule at the lowest combination.

offset

Numeric scalar between 0 and 0.5. Relaxation of cutoff_eli for the safety stopping rule. Defaults to 0.05.

titration

Logical scalar. Treat one patient per combination until the first DLT.

bound_mtd

Logical scalar. Require the isotonic estimate at the selected combination to be below the de-escalation boundary.

overdose_cutoff

Numeric scalar or NULL. Combinations whose true DLT probability exceeds this value count as overdoses. Defaults to NULL, which uses target.

keep_trials

Logical scalar. Keep the trial by trial data of every scenario.

verbose

Logical scalar. Report progress while the simulations run.

seed

Integer scalar or NULL. Random seed, applied to every scenario, so that a scenario simulated here matches the same scenario simulated on its own with sim_comb_boin.

Value

An object of class comb_boin_oc_multi, which is a list with components

results

Named list of comb_boin_oc objects, one per scenario.

summary_table

Data frame with one row per scenario: the true MTD combinations (those closest to target), the percentage of trials selecting one of them, the percentage of patients treated at them, the percentage of trials without an MTD, the percentage of trials selecting a combination above overdose_cutoff, the percentage of patients treated above it, and the average numbers of patients and DLTs.

scenario_names

Character vector of scenario names.

n_rows

Number of dose levels of drug A.

n_cols

Number of dose levels of drug B.

call

The matched call.

See Also

sim_comb_boin

Examples

scenarios <- list(
  "Two MTD combinations" = matrix(c(0.05, 0.10, 0.20,
                                    0.10, 0.20, 0.30,
                                    0.20, 0.30, 0.45), 3, byrow = TRUE),
  "All toxic" = matrix(c(0.40, 0.50, 0.60,
                         0.50, 0.60, 0.70,
                         0.60, 0.70, 0.80), 3, byrow = TRUE)
)

oc <- sim_comb_boin_multi(
  target = 0.30,
  scenarios = scenarios,
  n_cohort = 12,
  cohort_size = 3,
  n_trials = 200,
  seed = 123
)
oc

# The full results of one scenario
oc$results[["All toxic"]]


Operating Characteristics of a TITE-BOIN Design

Description

Simulate a time-to-event BOIN (TITE-BOIN) trial many times under one dose-toxicity scenario and summarize how often each dose is selected as the MTD, how many patients are treated and how many DLTs are observed at each dose, how long the trials last and how often accrual is suspended.

Usage

sim_tite_boin(
  target,
  p_true,
  n_cohort,
  cohort_size,
  window,
  accrual_rate,
  method = c("imputation", "ess"),
  accrual = c("exponential", "uniform", "fixed"),
  dlt_time = c("weibull", "uniform"),
  late_fraction = 0.5,
  prior_weights = c(1, 1, 1)/3,
  max_pending_ratio = NULL,
  min_completed = NULL,
  min_follow_up = 0,
  n_trials = 10000,
  start_dose = 1,
  n_earlystop = 18,
  p_saf = NULL,
  p_tox = NULL,
  cutoff_eli = 0.95,
  extrasafe = FALSE,
  offset = 0.05,
  bound_mtd = FALSE,
  mtd_max_estimate = NULL,
  min_mtd_sample = 1,
  overdose_cutoff = NULL,
  n_earlystop_rule = c("with_stay", "simple"),
  keep_trials = FALSE,
  verbose = FALSE,
  seed = 123
)

Arguments

target

Numeric scalar. Target DLT probability, for example 0.30.

p_true

Numeric vector. True DLT probability at each dose level, in increasing dose order. The probability of a DLT within the assessment window.

n_cohort

Integer scalar. Number of cohorts in a trial.

cohort_size

Integer scalar or vector. Number of patients per cohort. A scalar is used for every cohort. A vector shorter than n_cohort is padded with its last element and a longer one is truncated.

window

Numeric scalar. Length of the DLT assessment window.

accrual_rate

Numeric scalar. Average number of patients arriving per unit of time, in the same unit as window.

method

Character scalar, "imputation" (the default) or "ess". How the pending patients enter the estimate of the DLT probability. See tite_boin_decision_table.

accrual

Character scalar. Distribution of the times between arrivals: "exponential" (the default) for a Poisson process, "uniform" for a uniform distribution on (0, 2 / accrual_rate), as in the code of Lin and Yuan (2020), or "fixed" for arrivals exactly 1 / accrual_rate apart.

dlt_time

Character scalar. Distribution of the time to DLT within the window: "weibull" (the default), with the share of DLTs in the second half of the window set by late_fraction, or "uniform".

late_fraction

Numeric scalar strictly between 0 and 1. Share of the DLTs that occur in the second half of the assessment window under the Weibull distribution. Defaults to 0.5, the setting of Yuan et al. (2018) and Lin and Yuan (2020).

prior_weights

Numeric vector of three non-negative values. Prior probabilities that a DLT occurs in the first, second and last third of the assessment window, used to weight the follow-up of the pending patients in STFT (Yuan et al., 2018, Supplementary Appendix D) and ESS (Lin and Yuan, 2020, Supplementary S1). They are rescaled to sum to one. Defaults to equal weights, which give the unweighted STFT. The decision table does not change with the weights; only the value compared with its boundaries does. This describes the design and is separate from dlt_time and late_fraction, which describe how the simulated DLTs actually occur.

max_pending_ratio

Numeric scalar or NULL. Suspension rule on the proportion of pending patients. See tite_boin_decision_table.

min_completed

Integer scalar or NULL. Number of completed assessments required for escalation. See tite_boin_decision_table.

min_follow_up

Numeric scalar between 0 and 1. Shortest follow-up, as a fraction of window, that every pending patient at the current dose must have reached before the dose is escalated; accrual is suspended until then. Defaults to 0, which never suspends on this ground. See tite_boin_decision_table.

n_trials

Integer scalar. Number of trials to simulate. Defaults to 10000.

start_dose

Integer scalar. Dose level for the first cohort. Defaults to 1.

n_earlystop

Integer scalar. The trial stops once this many patients have been treated at the current dose and the design would stay there. Defaults to 18.

p_saf

Numeric scalar. Highest DLT probability deemed subtherapeutic. Defaults to 0.6 * target.

p_tox

Numeric scalar. Lowest DLT probability deemed overly toxic. Defaults to 1.4 * target.

cutoff_eli

Numeric scalar. Posterior probability cutoff for dose elimination. Defaults to 0.95.

extrasafe

Logical scalar. Apply the stricter safety stopping rule at the lowest dose. Defaults to FALSE.

offset

Numeric scalar between 0 and 0.5. Amount by which cutoff_eli is relaxed for the safety stopping rule. Defaults to 0.05.

bound_mtd

Logical scalar. Require the isotonic estimate at the selected dose to be at or below the de-escalation boundary. Defaults to FALSE.

mtd_max_estimate

Numeric scalar or NULL. Largest isotonic estimate a dose may have and still be selected as the MTD. See sim_boin.

min_mtd_sample

Integer scalar. Smallest number of patients a dose must have received to be eligible as the MTD. Defaults to 1.

overdose_cutoff

Numeric scalar or NULL. Doses whose true DLT probability exceeds this value count as overdoses in the overdose component of the result. Defaults to NULL, which uses target.

n_earlystop_rule

Character scalar, either "with_stay" or "simple". See boin_simulate.

keep_trials

Logical scalar. Keep the full trial by trial data in the result. Defaults to FALSE.

verbose

Logical scalar. Report progress while the simulation runs. Defaults to FALSE.

seed

Integer scalar or NULL. Random seed. When NULL the current state of the random number generator is used. The state of the calling session is restored on exit. Defaults to 123.

Details

The trials are simulated by tite_boin_simulate, whose details describe the conduct of a trial. Once every patient has completed the assessment the MTD is selected from the final data exactly as in sim_boin, with boin_select_mtd, and a trial stopped for safety selects no dose.

When no patient is ever pending at a decision, for example with accrual = "fixed" and window shorter than 1 / accrual_rate, every result agrees with that of sim_boin under the same seed.

Value

An object of class c("tite_boin_oc", "boin_oc"), which has every component of the result of sim_boin, so that code written for sim_boin() also reads it, and in addition

duration_mean

Average trial duration, from the first arrival until every enrolled patient has completed the assessment, in the time unit of window and accrual_rate.

duration_sd

Standard deviation of the trial duration.

pct_trials_suspended

Percentage of trials in which accrual was suspended at least once.

avg_n_suspensions

Average number of suspensions per trial.

avg_time_suspended

Average total time with accrual suspended per trial.

The trials component, when kept, also holds duration, n_suspensions and time_suspended for every trial.

References

Yuan, Y., Lin, R., Li, D., Nie, L. and Warren, K. E. (2018). Time-to-Event Bayesian Optimal Interval Design to Accelerate Phase I Trials. Clinical Cancer Research, 24(20), 4921-4930.

Lin, R. and Yuan, Y. (2020). Time-to-Event Model-Assisted Designs for Dose-Finding Trials with Delayed Toxicity. Biostatistics, 21(4), 807-824.

See Also

tite_boin_simulate, sim_tite_boin_multi, sim_boin

Examples

# A three month window with two patients a month
oc <- sim_tite_boin(
  target = 0.30,
  p_true = c(0.05, 0.15, 0.30, 0.45, 0.60),
  n_cohort = 10,
  cohort_size = 3,
  window = 3,
  accrual_rate = 2,
  n_trials = 500,
  seed = 123
)
oc


# The effective sample size of Lin and Yuan (2020)
oc_ess <- sim_tite_boin(
  target = 0.30,
  p_true = c(0.05, 0.15, 0.30, 0.45, 0.60),
  n_cohort = 12,
  cohort_size = 3,
  window = 3,
  accrual_rate = 2,
  method = "ess",
  n_trials = 10000,
  seed = 123
)
oc_ess



Operating Characteristics of the TITE-BOIN12 Design

Description

Simulate trials of the TITE-BOIN12 design of Zhou et al. (2022), in which the DLT and the response may be observed late, under one scenario of DLT and response probabilities, select the optimal biological dose (OBD) of each trial, and summarize how often each dose is selected, how many patients, DLTs and responses occur at each dose and how long the trials last.

Usage

sim_tite_boin12(
  target,
  target_resp,
  p_true,
  p_resp,
  n_cohort,
  cohort_size,
  window,
  accrual_rate,
  resp_window = window,
  accrual = c("uniform", "exponential", "fixed"),
  event_time = c("weibull", "uniform"),
  late_fraction = 0.5,
  resp_late_fraction = 0.5,
  min_completed_share = 0.5,
  pending_estimate = c("conditional", "marginal"),
  n_trials = 10000,
  start_dose = 1,
  n_earlystop = NULL,
  n_earlystop_rule = c("with_stay", "simple"),
  p_saf = NULL,
  p_tox = NULL,
  cutoff_eli = 0.95,
  cutoff_eli_resp = 0.9,
  psi00 = 40,
  psi11 = 60,
  benchmark_weight = 0.5,
  utility_prior = c(1, 1),
  n_star = 6,
  n_explore = 9,
  tie_break = c("higher", "random"),
  no_candidate = c("nearest", "stop"),
  explore_from = c("any", "admissible"),
  resp_cor = 0,
  resp_cor_type = c("copula", "binary"),
  est_method = c("posterior_mean", "observed", "tail_probability"),
  keep_trials = FALSE,
  verbose = FALSE,
  seed = 123
)

Arguments

target

Numeric scalar. Highest acceptable DLT probability, called phi_T by Lin et al. (2020). It is the target of the BOIN boundaries lambda_e and lambda_d, of the admissibility of a dose and of the MTD that bounds the OBD. Lin et al. recommend a value slightly above the target of a design that only considers toxicity, for example 0.35 instead of 0.30.

target_resp

Numeric scalar. Lowest acceptable response probability, phi_E. Note that this is a lower limit, as in sim_bf_boin_et, whereas the target_resp of sim_boin_et is a target.

p_true

Numeric vector. True DLT probability at each dose.

p_resp

Numeric vector. True response probability at each dose.

n_cohort

Integer scalar. Number of cohorts in a trial.

cohort_size

Integer scalar or vector. Number of patients per cohort. A scalar is used for every cohort; a shorter vector is padded with its last element.

window

Numeric scalar. Length of the DLT assessment window.

accrual_rate

Numeric scalar. Average number of patients arriving per unit of time, in the same unit as window.

resp_window

Numeric scalar. Length of the response assessment window. Defaults to window.

accrual

Character scalar. Distribution of the times between arrivals: "uniform" (the default) on (0, 2 / accrual_rate), "exponential" for a Poisson process, or "fixed" for arrivals exactly 1 / accrual_rate apart.

event_time

Character scalar. Distribution of the times to DLT and to response: "weibull" (the default), with the share of the events in the second half of the window set by late_fraction and resp_late_fraction, or "uniform" over the window. With "weibull" the probabilities must be below 1.

late_fraction

Numeric scalar strictly between 0 and 1. Share of the DLTs that occur in the second half of the DLT window under the Weibull distribution. Defaults to 0.5.

resp_late_fraction

Numeric scalar strictly between 0 and 1. The same for the responses. Defaults to 0.5.

min_completed_share

Numeric scalar from 0 to 1. Share of the patients at the current dose who must have finished both assessments before the next decision; the decision, and the accrual, wait until then. Defaults to 0.5, the rule of Zhou et al. (2022), who suspend the accrual when more than half of the patients at the current dose have a pending outcome. With 1 every decision waits for all the outcomes, as in BOIN12.

pending_estimate

Character scalar. Value that replaces a pending outcome Y in the quasi-binomial likelihood: "conditional" (the default), the probability of the event given that it has not occurred during the time followed, pi_hat * (1 - w) / (1 - pi_hat * w), with w the fraction of the window followed, as in Equation (11) of Zhou et al. (2022); or "marginal", the estimate pi_hat itself, which reproduces the desirabilities of Table S.3 of their Supplement. See Details.

n_trials

Integer scalar. Number of trials to simulate. Defaults to 10000.

start_dose

Integer scalar. Dose level of the first cohort. Defaults to 1.

n_earlystop

Integer scalar or NULL. Number of patients at the current dose that ends the trial when the next cohort would stay there (see n_earlystop_rule). Defaults to NULL, which runs every trial to the maximum sample size, as in Lin et al. (2020).

n_earlystop_rule

Character scalar. "with_stay" (the default) ends the trial at n_earlystop only when the next cohort would stay at the current dose, as in the example of Zhou et al. (2022); "simple" ends it in any case.

p_saf, p_tox

Numeric scalars or NULL. Highest DLT probability deemed subtherapeutic and lowest deemed overly toxic, which give the BOIN boundaries. Default to 0.6 * target and 1.4 * target.

cutoff_eli

Numeric scalar. A dose is inadmissible, together with every higher dose, when the posterior probability that its DLT rate exceeds target is at least this cutoff. Defaults to 0.95.

cutoff_eli_resp

Numeric scalar. A dose is inadmissible when the posterior probability that its response rate is below target_resp is at least this cutoff. Defaults to 0.90.

psi00, psi11

Numeric scalars from 0 to 100. Utility of a patient without DLT and without response, and with both. The utility of a response without DLT is 100 and that of a DLT without response is 0. Default to 40 and 60, the example of Lin et al. (2020).

benchmark_weight

Numeric scalar above 0 and at most 1. The utility benchmark is benchmark_weight * u_low + (1 - benchmark_weight) * 100, where u_low is the expected utility of a dose whose DLT and response probabilities are target and target_resp, the two outcomes being independent. Defaults to 0.5, the benchmark of Lin et al. (2020); Lu et al. (2025) use 0.6.

utility_prior

Numeric vector of two positive numbers. Beta prior of the utility of a dose divided by 100. Defaults to c(1, 1).

n_star

Integer scalar. With at least this many patients at the current dose and a DLT rate between lambda_e and lambda_d, the next dose is chosen from the current dose and the dose below. Defaults to 6.

n_explore

Integer scalar. With at least this many patients at the current dose, a DLT rate below lambda_d and an untried admissible dose above, the next cohort goes to that dose. Defaults to 9.

tie_break

Character scalar. Choice among the doses of equal desirability: "higher" (the default) takes the highest of them, the rule of the BOIN12 software according to the 'escalation' package; "random" takes one of them at random, as stated in Table S2 of the Supplement of Lin et al. (2020). See Details.

no_candidate

Character scalar. What happens when none of the doses allowed for the next cohort is admissible: "nearest" (the default) goes to the admissible dose nearest to the current one; "stop" ends the trial without an OBD. See Details.

explore_from

Character scalar. Doses from which the exploration rule (see n_explore) escalates: "any" (the default) from any dose, as in the 'escalation' package; "admissible" only from an admissible dose, as the results published by Lin et al. (2020) indicate. See Details.

resp_cor

Numeric scalar between -1 and 1. Correlation between the DLT and the response of a patient, see resp_cor_type; with "copula" it also links the time to DLT and the time to response. Defaults to 0.

resp_cor_type

Character scalar. "copula" (the default) links the two outcomes by a Gaussian copula with correlation resp_cor, the bivariate normal model of Lin et al. (2020); "binary" sets the correlation of the two binary outcomes, as in boin_et_simulate.

est_method

Character scalar. Estimate of the utility of a dose: "posterior_mean" (the default), the posterior mean of the quasi-binomial model given in Section 4 of the Supplement of Lin et al. (2020); "observed", the observed mean utility, which the example of Section 6 of that Supplement reports; or "tail_probability", the desirability used during the trial, which the 'escalation' package uses.

keep_trials

Logical scalar. Keep the simulated trials and the selected OBDs in the result. Defaults to FALSE.

verbose

Logical scalar. Report progress with messages. Defaults to FALSE.

seed

Integer scalar or NULL. Random seed. The state of the calling session is restored on exit. Defaults to 123.

Details

The trials are simulated by tite_boin12_simulate, and the OBD of each trial is selected by boin12_select_obd from the complete data, after every patient has finished both assessments; see there for the rules.

Value

An object of class boin12_oc, as returned by sim_boin12, with design set to "TITE-BOIN12" and one more component

duration

Average trial duration, in the unit of window.

References

Zhou, Y., Lin, R., Lee, J. J., Li, D., Wang, L., Li, R. and Yuan, Y. (2022). TITE-BOIN12: A Bayesian phase I/II trial design to find the optimal biological dose with late-onset toxicity and efficacy. Statistics in Medicine, 41(11), 1918-1931. doi:10.1002/sim.9337

See Also

sim_tite_boin12_multi, tite_boin12_simulate, sim_boin12

Examples

# Scenario 1 of Zhou et al. (2022): windows of 45 and 60 days, three
# patients a month, 36 patients in cohorts of 3
oc <- sim_tite_boin12(
  target = 0.35, target_resp = 0.25,
  p_true = c(0.05, 0.12, 0.27, 0.35, 0.50),
  p_resp = c(0.20, 0.35, 0.36, 0.37, 0.38),
  n_cohort = 12, cohort_size = 3, window = 45, resp_window = 60,
  accrual_rate = 3 / 30, n_trials = 500, seed = 123
)
oc


Operating Characteristics of the TITE-BOIN12 Design Across Scenarios

Description

Run sim_tite_boin12 for several scenarios of DLT and response probabilities with the same design and collect the results in one table.

Usage

sim_tite_boin12_multi(
  target,
  target_resp,
  scenarios,
  n_cohort,
  cohort_size,
  window,
  accrual_rate,
  resp_window = window,
  accrual = c("uniform", "exponential", "fixed"),
  event_time = c("weibull", "uniform"),
  late_fraction = 0.5,
  resp_late_fraction = 0.5,
  min_completed_share = 0.5,
  pending_estimate = c("conditional", "marginal"),
  n_trials = 10000,
  start_dose = 1,
  n_earlystop = NULL,
  n_earlystop_rule = c("with_stay", "simple"),
  p_saf = NULL,
  p_tox = NULL,
  cutoff_eli = 0.95,
  cutoff_eli_resp = 0.9,
  psi00 = 40,
  psi11 = 60,
  benchmark_weight = 0.5,
  utility_prior = c(1, 1),
  n_star = 6,
  n_explore = 9,
  tie_break = c("higher", "random"),
  no_candidate = c("nearest", "stop"),
  explore_from = c("any", "admissible"),
  resp_cor = 0,
  resp_cor_type = c("copula", "binary"),
  est_method = c("posterior_mean", "observed", "tail_probability"),
  keep_trials = FALSE,
  verbose = FALSE,
  seed = 123
)

Arguments

target

Numeric scalar. Highest acceptable DLT probability, called phi_T by Lin et al. (2020). It is the target of the BOIN boundaries lambda_e and lambda_d, of the admissibility of a dose and of the MTD that bounds the OBD. Lin et al. recommend a value slightly above the target of a design that only considers toxicity, for example 0.35 instead of 0.30.

target_resp

Numeric scalar. Lowest acceptable response probability, phi_E. Note that this is a lower limit, as in sim_bf_boin_et, whereas the target_resp of sim_boin_et is a target.

scenarios

List of scenarios. Each element is a list with the components p_true and p_resp, and optionally name. Names of the list are used when name is absent. All scenarios must have the same number of doses.

n_cohort

Integer scalar. Number of cohorts in a trial.

cohort_size

Integer scalar or vector. Number of patients per cohort. A scalar is used for every cohort; a shorter vector is padded with its last element.

window

Numeric scalar. Length of the DLT assessment window.

accrual_rate

Numeric scalar. Average number of patients arriving per unit of time, in the same unit as window.

resp_window

Numeric scalar. Length of the response assessment window. Defaults to window.

accrual

Character scalar. Distribution of the times between arrivals: "uniform" (the default) on (0, 2 / accrual_rate), "exponential" for a Poisson process, or "fixed" for arrivals exactly 1 / accrual_rate apart.

event_time

Character scalar. Distribution of the times to DLT and to response: "weibull" (the default), with the share of the events in the second half of the window set by late_fraction and resp_late_fraction, or "uniform" over the window. With "weibull" the probabilities must be below 1.

late_fraction

Numeric scalar strictly between 0 and 1. Share of the DLTs that occur in the second half of the DLT window under the Weibull distribution. Defaults to 0.5.

resp_late_fraction

Numeric scalar strictly between 0 and 1. The same for the responses. Defaults to 0.5.

min_completed_share

Numeric scalar from 0 to 1. Share of the patients at the current dose who must have finished both assessments before the next decision; the decision, and the accrual, wait until then. Defaults to 0.5, the rule of Zhou et al. (2022), who suspend the accrual when more than half of the patients at the current dose have a pending outcome. With 1 every decision waits for all the outcomes, as in BOIN12.

pending_estimate

Character scalar. Value that replaces a pending outcome Y in the quasi-binomial likelihood: "conditional" (the default), the probability of the event given that it has not occurred during the time followed, pi_hat * (1 - w) / (1 - pi_hat * w), with w the fraction of the window followed, as in Equation (11) of Zhou et al. (2022); or "marginal", the estimate pi_hat itself, which reproduces the desirabilities of Table S.3 of their Supplement. See Details.

n_trials

Integer scalar. Number of trials to simulate. Defaults to 10000.

start_dose

Integer scalar. Dose level of the first cohort. Defaults to 1.

n_earlystop

Integer scalar or NULL. Number of patients at the current dose that ends the trial when the next cohort would stay there (see n_earlystop_rule). Defaults to NULL, which runs every trial to the maximum sample size, as in Lin et al. (2020).

n_earlystop_rule

Character scalar. "with_stay" (the default) ends the trial at n_earlystop only when the next cohort would stay at the current dose, as in the example of Zhou et al. (2022); "simple" ends it in any case.

p_saf, p_tox

Numeric scalars or NULL. Highest DLT probability deemed subtherapeutic and lowest deemed overly toxic, which give the BOIN boundaries. Default to 0.6 * target and 1.4 * target.

cutoff_eli

Numeric scalar. A dose is inadmissible, together with every higher dose, when the posterior probability that its DLT rate exceeds target is at least this cutoff. Defaults to 0.95.

cutoff_eli_resp

Numeric scalar. A dose is inadmissible when the posterior probability that its response rate is below target_resp is at least this cutoff. Defaults to 0.90.

psi00, psi11

Numeric scalars from 0 to 100. Utility of a patient without DLT and without response, and with both. The utility of a response without DLT is 100 and that of a DLT without response is 0. Default to 40 and 60, the example of Lin et al. (2020).

benchmark_weight

Numeric scalar above 0 and at most 1. The utility benchmark is benchmark_weight * u_low + (1 - benchmark_weight) * 100, where u_low is the expected utility of a dose whose DLT and response probabilities are target and target_resp, the two outcomes being independent. Defaults to 0.5, the benchmark of Lin et al. (2020); Lu et al. (2025) use 0.6.

utility_prior

Numeric vector of two positive numbers. Beta prior of the utility of a dose divided by 100. Defaults to c(1, 1).

n_star

Integer scalar. With at least this many patients at the current dose and a DLT rate between lambda_e and lambda_d, the next dose is chosen from the current dose and the dose below. Defaults to 6.

n_explore

Integer scalar. With at least this many patients at the current dose, a DLT rate below lambda_d and an untried admissible dose above, the next cohort goes to that dose. Defaults to 9.

tie_break

Character scalar. Choice among the doses of equal desirability: "higher" (the default) takes the highest of them, the rule of the BOIN12 software according to the 'escalation' package; "random" takes one of them at random, as stated in Table S2 of the Supplement of Lin et al. (2020). See Details.

no_candidate

Character scalar. What happens when none of the doses allowed for the next cohort is admissible: "nearest" (the default) goes to the admissible dose nearest to the current one; "stop" ends the trial without an OBD. See Details.

explore_from

Character scalar. Doses from which the exploration rule (see n_explore) escalates: "any" (the default) from any dose, as in the 'escalation' package; "admissible" only from an admissible dose, as the results published by Lin et al. (2020) indicate. See Details.

resp_cor

Numeric scalar between -1 and 1. Correlation between the DLT and the response of a patient, see resp_cor_type; with "copula" it also links the time to DLT and the time to response. Defaults to 0.

resp_cor_type

Character scalar. "copula" (the default) links the two outcomes by a Gaussian copula with correlation resp_cor, the bivariate normal model of Lin et al. (2020); "binary" sets the correlation of the two binary outcomes, as in boin_et_simulate.

est_method

Character scalar. Estimate of the utility of a dose: "posterior_mean" (the default), the posterior mean of the quasi-binomial model given in Section 4 of the Supplement of Lin et al. (2020); "observed", the observed mean utility, which the example of Section 6 of that Supplement reports; or "tail_probability", the desirability used during the trial, which the 'escalation' package uses.

keep_trials

Logical scalar. Keep the simulated trials and the selected OBDs in the result. Defaults to FALSE.

verbose

Logical scalar. Report progress with messages. Defaults to FALSE.

seed

Integer scalar or NULL. Random seed. The state of the calling session is restored on exit. Defaults to 123.

Details

Every scenario is simulated with the same seed, so that a scenario simulated here matches the same scenario simulated on its own with sim_tite_boin12.

Value

An object of class boin12_oc_multi, as returned by sim_boin12_multi. The average trial duration of each scenario is the component duration of its element of results.

See Also

sim_tite_boin12, sim_boin12_multi

Examples

# Scenarios 1 and 2 of Zhou et al. (2022)
scenarios <- list(
  "Scenario 1" = list(p_true = c(0.05, 0.12, 0.27, 0.35, 0.50),
                      p_resp = c(0.20, 0.35, 0.36, 0.37, 0.38)),
  "Scenario 2" = list(p_true = c(0.05, 0.12, 0.27, 0.35, 0.50),
                      p_resp = c(0.01, 0.05, 0.30, 0.60, 0.60))
)
oc <- sim_tite_boin12_multi(
  target = 0.35, target_resp = 0.25, scenarios = scenarios,
  n_cohort = 12, cohort_size = 3, window = 45, resp_window = 60,
  accrual_rate = 3 / 30, n_trials = 200, seed = 1
)
oc
sapply(oc$results, function(r) r$duration)


Operating Characteristics of the TITE-BOIN-ET Design

Description

Simulate trials of the TITE-BOIN-ET design of Takeda, Morita and Taguri (2020) under one scenario of DLT and response probabilities, select the optimal biological dose (OBD) of each trial, and summarize how often each dose is selected, how many patients, DLTs and responses occur at each dose, and how long the trials last.

Usage

sim_tite_boin_et(
  target,
  target_resp,
  p_true,
  p_resp,
  n_cohort,
  cohort_size,
  window,
  accrual_rate,
  resp_window = window,
  accrual = c("uniform", "exponential", "fixed"),
  event_time = c("weibull", "uniform"),
  late_fraction = 0.5,
  resp_late_fraction = 0.5,
  resp_cor = 0.2,
  min_completed_share = 0.5,
  n_trials = 10000,
  start_dose = 1,
  n_earlystop = NULL,
  p_saf = NULL,
  p_tox = NULL,
  p_saf_resp = NULL,
  cutoff_eli = 0.95,
  cutoff_eli_resp = 0.99,
  p_eli = NULL,
  p_eli_resp = NULL,
  boinet_compatible = FALSE,
  prior = rep(1/6, 6),
  est_method = c("observed", "multi_iso", "fp_logistic"),
  obd_method = c("max_resp", "utility_weighted", "utility_truncated_linear",
    "utility_scoring"),
  w1 = 0.33,
  w2 = 1.09,
  t_low = NULL,
  t_upp = NULL,
  e_low = NULL,
  e_upp = NULL,
  psi00 = 40,
  psi11 = 60,
  keep_trials = FALSE,
  verbose = FALSE,
  seed = 123
)

Arguments

target

Numeric scalar. Target DLT probability, for example 0.30.

target_resp

Numeric scalar. Target response probability, for example 0.60.

p_true

Numeric vector. True DLT probability at each dose level, in increasing dose order.

p_resp

Numeric vector of the same length as p_true. True response probability at each dose level.

n_cohort

Integer scalar. Number of cohorts in a trial.

cohort_size

Integer scalar or vector. Number of patients per cohort. A scalar is used for every cohort. A vector shorter than n_cohort is padded with its last element and a longer one is truncated.

window

Numeric scalar. Length of the DLT assessment window.

accrual_rate

Numeric scalar. Average number of patients arriving per unit of time, in the same unit as window. The accrual argument of the 'boinet' package is the average time between arrivals, its inverse.

resp_window

Numeric scalar. Length of the response assessment window. Defaults to window.

accrual

Character scalar. Distribution of the times between arrivals: "uniform" (the default, as in 'boinet') on (0, 2 / accrual_rate), "exponential" for a Poisson process, or "fixed" for arrivals exactly 1 / accrual_rate apart.

event_time

Character scalar. Distribution of the times to DLT and to response: "weibull" (the default), with the share of the events in the second half of the window set by late_fraction and resp_late_fraction, or "uniform" on (0, window / p) for an event of probability p. With "weibull" the probabilities must be below 1.

late_fraction

Numeric scalar strictly between 0 and 1. Share of the DLTs that occur in the second half of the DLT window under the Weibull distribution. Defaults to 0.5.

resp_late_fraction

Numeric scalar strictly between 0 and 1. The same for the responses. Defaults to 0.5.

resp_cor

Numeric scalar strictly between -1 and 1. Correlation of the Gaussian copula that links the time to DLT and the time to response of a patient. Defaults to 0.2, the default of the 'boinet' package.

min_completed_share

Numeric scalar from 0 to 1. Share of the patients at the current dose who must have finished both assessments before the next decision; the decision waits until then. Defaults to 0.5, the rule of the 'boinet' package. Takeda et al. (2020) did not wait in their simulations, which is min_completed_share = 0, and recommended such a rule when the accrual is fast.

n_trials

Integer scalar. Number of trials to simulate. Defaults to 10000.

start_dose

Integer scalar. Dose level for the first cohort. Defaults to 1.

n_earlystop

Integer scalar or NULL. The trial stops once this many patients have been treated at any dose. Defaults to NULL, the maximum sample size, which is the default of the 'boinet' package.

p_saf

Numeric scalar. Highest DLT probability deemed subtherapeutic. Defaults to 0.1 * target, the value recommended by Takeda et al. (2018), which is far below the 0.6 * target of the BOIN design.

p_tox

Numeric scalar. Lowest DLT probability deemed overly toxic. Defaults to 1.4 * target.

p_saf_resp

Numeric scalar. Highest response probability deemed subtherapeutic. Defaults to 0.6 * target_resp.

cutoff_eli

Numeric scalar. A dose is no longer admissible when the posterior probability that its DLT rate is below p_eli falls below 1 - cutoff_eli. Defaults to 0.95.

cutoff_eli_resp

Numeric scalar. A dose is no longer admissible when the posterior probability that its response rate is above p_eli_resp falls below 1 - cutoff_eli_resp. Defaults to 0.99.

p_eli

Numeric scalar or NULL. DLT probability of the rule above. Defaults to NULL, which uses target as the 'boinet' package does. Takeda et al. (2018) used 0.40 with a cutoff of 0.90.

p_eli_resp

Numeric scalar or NULL. Response probability of the rule above. Defaults to NULL, which uses p_saf_resp as the 'boinet' package does. Takeda et al. (2018) used 0.20 with a cutoff of 0.90.

boinet_compatible

Logical scalar. Apply the rules of the 'boinet' package (version 1.6.0) exactly. Defaults to FALSE, which keeps to Takeda et al. (2018), who do not allow dose skipping during escalation; see Details.

prior

Numeric vector of length 6. Prior probabilities of the six hypotheses. Defaults to rep(1 / 6, 6), the noninformative choice of the article. The third hypothesis, under which every decision is correct, does not enter the criterion.

est_method

Character scalar. Estimator of the response rates: "observed" (the default) for the observed rates, "multi_iso" for the model-averaged unimodal isotonic regression of Lin and Yin (2017), or "fp_logistic" for the fractional polynomial logistic regression of Takeda et al. (2018), which needs the 'mfp' package.

obd_method

Character scalar. Selection rule: "max_resp" (the default) for the admissible dose with the highest estimated response rate up to the estimated MTD, or the dose that maximizes the utility "utility_weighted", "utility_truncated_linear" or "utility_scoring" among the admissible doses.

w1, w2

Numeric scalars. Weights of the weighted utility q - w1 * p - w2 * p * (p > p_tox), where p and q are the estimated DLT and response rates. Default to 0.33 and 1.09.

t_low, t_upp

Numeric scalars or NULL. DLT rates between which the truncated linear utility falls from one to zero. Default to p_saf and p_tox.

e_low, e_upp

Numeric scalars or NULL. Response rates between which the truncated linear utility rises from zero to one. Default to p_saf_resp / 2 and target_resp.

psi00, psi11

Numeric scalars. Scores of the scoring utility for a patient with neither DLT nor response and for a patient with both, the scores of a response without DLT and of a DLT without response being 100 and 0. Default to 40 and 60.

keep_trials

Logical scalar. Keep the simulated trials and the selected OBDs in the result. Defaults to FALSE.

verbose

Logical scalar. Report progress with messages. Defaults to FALSE.

seed

Integer scalar or NULL. Random seed. When NULL the current state of the random number generator is used. The state of the calling session is restored on exit. Defaults to 123.

Details

The trials are simulated by tite_boin_et_simulate and the OBD is selected by boin_et_select_obd from the data at the last decision, as in boinet::tite.boinet().

Value

An object of class boin_et_oc, as returned by sim_boin_et, with design set to "TITE-BOIN-ET" and one more component

duration

Average trial duration, in the unit of window.

References

Takeda, K., Morita, S. and Taguri, M. (2020). TITE-BOIN-ET: Time-to-event Bayesian optimal interval design to accelerate dose-finding based on both efficacy and toxicity outcomes. Pharmaceutical Statistics, 19, 335-349. doi:10.1002/pst.1995

See Also

tite_boin_et_simulate, sim_tite_boin_et_multi, sim_boin_et

Examples

# Scenario 1 of Takeda et al. (2018) with a 30-day DLT window, a 45-day
# response window and one patient every 10 days on average
oc <- sim_tite_boin_et(
  target = 0.30, target_resp = 0.60,
  p_true = c(0.05, 0.15, 0.25, 0.30, 0.35, 0.40),
  p_resp = c(0.05, 0.35, 0.55, 0.65, 0.75, 0.70),
  n_cohort = 12, cohort_size = 3, window = 30, resp_window = 45,
  accrual_rate = 1 / 10, n_trials = 500, seed = 123
)
oc


Operating Characteristics of the TITE-BOIN-ET Design Across Scenarios

Description

Run sim_tite_boin_et for several scenarios of DLT and response probabilities with the same design and collect the results in one table.

Usage

sim_tite_boin_et_multi(
  target,
  target_resp,
  scenarios,
  n_cohort,
  cohort_size,
  window,
  accrual_rate,
  resp_window = window,
  accrual = c("uniform", "exponential", "fixed"),
  event_time = c("weibull", "uniform"),
  late_fraction = 0.5,
  resp_late_fraction = 0.5,
  resp_cor = 0.2,
  min_completed_share = 0.5,
  n_trials = 10000,
  start_dose = 1,
  n_earlystop = NULL,
  p_saf = NULL,
  p_tox = NULL,
  p_saf_resp = NULL,
  cutoff_eli = 0.95,
  cutoff_eli_resp = 0.99,
  p_eli = NULL,
  p_eli_resp = NULL,
  boinet_compatible = FALSE,
  prior = rep(1/6, 6),
  est_method = c("observed", "multi_iso", "fp_logistic"),
  obd_method = c("max_resp", "utility_weighted", "utility_truncated_linear",
    "utility_scoring"),
  w1 = 0.33,
  w2 = 1.09,
  t_low = NULL,
  t_upp = NULL,
  e_low = NULL,
  e_upp = NULL,
  psi00 = 40,
  psi11 = 60,
  keep_trials = FALSE,
  verbose = FALSE,
  seed = 123
)

Arguments

target

Numeric scalar. Target DLT probability, for example 0.30.

target_resp

Numeric scalar. Target response probability, for example 0.60.

scenarios

List of scenarios. Each element is a list with the components p_true and p_resp, and optionally name. Names of the list are used when name is absent. All scenarios must have the same number of doses.

n_cohort

Integer scalar. Number of cohorts in a trial.

cohort_size

Integer scalar or vector. Number of patients per cohort. A scalar is used for every cohort. A vector shorter than n_cohort is padded with its last element and a longer one is truncated.

window

Numeric scalar. Length of the DLT assessment window.

accrual_rate

Numeric scalar. Average number of patients arriving per unit of time, in the same unit as window. The accrual argument of the 'boinet' package is the average time between arrivals, its inverse.

resp_window

Numeric scalar. Length of the response assessment window. Defaults to window.

accrual

Character scalar. Distribution of the times between arrivals: "uniform" (the default, as in 'boinet') on (0, 2 / accrual_rate), "exponential" for a Poisson process, or "fixed" for arrivals exactly 1 / accrual_rate apart.

event_time

Character scalar. Distribution of the times to DLT and to response: "weibull" (the default), with the share of the events in the second half of the window set by late_fraction and resp_late_fraction, or "uniform" on (0, window / p) for an event of probability p. With "weibull" the probabilities must be below 1.

late_fraction

Numeric scalar strictly between 0 and 1. Share of the DLTs that occur in the second half of the DLT window under the Weibull distribution. Defaults to 0.5.

resp_late_fraction

Numeric scalar strictly between 0 and 1. The same for the responses. Defaults to 0.5.

resp_cor

Numeric scalar strictly between -1 and 1. Correlation of the Gaussian copula that links the time to DLT and the time to response of a patient. Defaults to 0.2, the default of the 'boinet' package.

min_completed_share

Numeric scalar from 0 to 1. Share of the patients at the current dose who must have finished both assessments before the next decision; the decision waits until then. Defaults to 0.5, the rule of the 'boinet' package. Takeda et al. (2020) did not wait in their simulations, which is min_completed_share = 0, and recommended such a rule when the accrual is fast.

n_trials

Integer scalar. Number of trials to simulate. Defaults to 10000.

start_dose

Integer scalar. Dose level for the first cohort. Defaults to 1.

n_earlystop

Integer scalar or NULL. The trial stops once this many patients have been treated at any dose. Defaults to NULL, the maximum sample size, which is the default of the 'boinet' package.

p_saf

Numeric scalar. Highest DLT probability deemed subtherapeutic. Defaults to 0.1 * target, the value recommended by Takeda et al. (2018), which is far below the 0.6 * target of the BOIN design.

p_tox

Numeric scalar. Lowest DLT probability deemed overly toxic. Defaults to 1.4 * target.

p_saf_resp

Numeric scalar. Highest response probability deemed subtherapeutic. Defaults to 0.6 * target_resp.

cutoff_eli

Numeric scalar. A dose is no longer admissible when the posterior probability that its DLT rate is below p_eli falls below 1 - cutoff_eli. Defaults to 0.95.

cutoff_eli_resp

Numeric scalar. A dose is no longer admissible when the posterior probability that its response rate is above p_eli_resp falls below 1 - cutoff_eli_resp. Defaults to 0.99.

p_eli

Numeric scalar or NULL. DLT probability of the rule above. Defaults to NULL, which uses target as the 'boinet' package does. Takeda et al. (2018) used 0.40 with a cutoff of 0.90.

p_eli_resp

Numeric scalar or NULL. Response probability of the rule above. Defaults to NULL, which uses p_saf_resp as the 'boinet' package does. Takeda et al. (2018) used 0.20 with a cutoff of 0.90.

boinet_compatible

Logical scalar. Apply the rules of the 'boinet' package (version 1.6.0) exactly. Defaults to FALSE, which keeps to Takeda et al. (2018), who do not allow dose skipping during escalation; see Details.

prior

Numeric vector of length 6. Prior probabilities of the six hypotheses. Defaults to rep(1 / 6, 6), the noninformative choice of the article. The third hypothesis, under which every decision is correct, does not enter the criterion.

est_method

Character scalar. Estimator of the response rates: "observed" (the default) for the observed rates, "multi_iso" for the model-averaged unimodal isotonic regression of Lin and Yin (2017), or "fp_logistic" for the fractional polynomial logistic regression of Takeda et al. (2018), which needs the 'mfp' package.

obd_method

Character scalar. Selection rule: "max_resp" (the default) for the admissible dose with the highest estimated response rate up to the estimated MTD, or the dose that maximizes the utility "utility_weighted", "utility_truncated_linear" or "utility_scoring" among the admissible doses.

w1, w2

Numeric scalars. Weights of the weighted utility q - w1 * p - w2 * p * (p > p_tox), where p and q are the estimated DLT and response rates. Default to 0.33 and 1.09.

t_low, t_upp

Numeric scalars or NULL. DLT rates between which the truncated linear utility falls from one to zero. Default to p_saf and p_tox.

e_low, e_upp

Numeric scalars or NULL. Response rates between which the truncated linear utility rises from zero to one. Default to p_saf_resp / 2 and target_resp.

psi00, psi11

Numeric scalars. Scores of the scoring utility for a patient with neither DLT nor response and for a patient with both, the scores of a response without DLT and of a DLT without response being 100 and 0. Default to 40 and 60.

keep_trials

Logical scalar. Keep the simulated trials and the selected OBDs in the result. Defaults to FALSE.

verbose

Logical scalar. Report progress with messages. Defaults to FALSE.

seed

Integer scalar or NULL. Random seed. When NULL the current state of the random number generator is used. The state of the calling session is restored on exit. Defaults to 123.

Details

Every scenario is simulated with the same seed.

Value

An object of class boin_et_oc_multi, as returned by sim_boin_et_multi, whose results are the boin_et_oc objects of sim_tite_boin_et.

See Also

sim_tite_boin_et

Examples

scenarios <- list(
  "Scenario 1" = list(p_true = c(0.05, 0.15, 0.25, 0.30, 0.35, 0.40),
                      p_resp = c(0.05, 0.35, 0.55, 0.65, 0.75, 0.70)),
  "Scenario 7" = list(p_true = c(0.05, 0.15, 0.25, 0.35, 0.45, 0.55),
                      p_resp = c(0.30, 0.70, 0.60, 0.50, 0.40, 0.30))
)
res <- sim_tite_boin_et_multi(
  target = 0.30, target_resp = 0.60, scenarios = scenarios,
  n_cohort = 12, cohort_size = 3, window = 30, resp_window = 45,
  accrual_rate = 1 / 10, n_trials = 300, seed = 123
)
res


Operating Characteristics of a TITE-BOIN Design Across Several Scenarios

Description

Run sim_tite_boin under a list of dose-toxicity scenarios that share the same design, and collect the results into one table.

Usage

sim_tite_boin_multi(
  target,
  scenarios,
  n_cohort,
  cohort_size,
  window,
  accrual_rate,
  method = c("imputation", "ess"),
  accrual = c("exponential", "uniform", "fixed"),
  dlt_time = c("weibull", "uniform"),
  late_fraction = 0.5,
  prior_weights = c(1, 1, 1)/3,
  max_pending_ratio = NULL,
  min_completed = NULL,
  min_follow_up = 0,
  n_trials = 10000,
  start_dose = 1,
  n_earlystop = 18,
  p_saf = NULL,
  p_tox = NULL,
  cutoff_eli = 0.95,
  extrasafe = FALSE,
  offset = 0.05,
  bound_mtd = FALSE,
  mtd_max_estimate = NULL,
  min_mtd_sample = 1,
  overdose_cutoff = NULL,
  n_earlystop_rule = c("with_stay", "simple"),
  keep_trials = FALSE,
  verbose = FALSE,
  seed = 123
)

Arguments

target

Numeric scalar. Target DLT probability, for example 0.30.

scenarios

A list of scenarios. Each element is a list with a name and a p_true vector, or a plain numeric vector of true DLT probabilities in which case the list names are used as scenario names. Every scenario must have the same number of doses.

n_cohort

Integer scalar. Number of cohorts in a trial.

cohort_size

Integer scalar or vector. Number of patients per cohort. A scalar is used for every cohort. A vector shorter than n_cohort is padded with its last element and a longer one is truncated.

window

Numeric scalar. Length of the DLT assessment window.

accrual_rate

Numeric scalar. Average number of patients arriving per unit of time, in the same unit as window.

method

Character scalar, "imputation" (the default) or "ess". How the pending patients enter the estimate of the DLT probability. See tite_boin_decision_table.

accrual

Character scalar. Distribution of the times between arrivals: "exponential" (the default) for a Poisson process, "uniform" for a uniform distribution on (0, 2 / accrual_rate), as in the code of Lin and Yuan (2020), or "fixed" for arrivals exactly 1 / accrual_rate apart.

dlt_time

Character scalar. Distribution of the time to DLT within the window: "weibull" (the default), with the share of DLTs in the second half of the window set by late_fraction, or "uniform".

late_fraction

Numeric scalar strictly between 0 and 1. Share of the DLTs that occur in the second half of the assessment window under the Weibull distribution. Defaults to 0.5, the setting of Yuan et al. (2018) and Lin and Yuan (2020).

prior_weights

Numeric vector of three non-negative values. Prior probabilities that a DLT occurs in the first, second and last third of the assessment window, used to weight the follow-up of the pending patients in STFT (Yuan et al., 2018, Supplementary Appendix D) and ESS (Lin and Yuan, 2020, Supplementary S1). They are rescaled to sum to one. Defaults to equal weights, which give the unweighted STFT. The decision table does not change with the weights; only the value compared with its boundaries does. This describes the design and is separate from dlt_time and late_fraction, which describe how the simulated DLTs actually occur.

max_pending_ratio

Numeric scalar or NULL. Suspension rule on the proportion of pending patients. See tite_boin_decision_table.

min_completed

Integer scalar or NULL. Number of completed assessments required for escalation. See tite_boin_decision_table.

min_follow_up

Numeric scalar between 0 and 1. Shortest follow-up, as a fraction of window, that every pending patient at the current dose must have reached before the dose is escalated; accrual is suspended until then. Defaults to 0, which never suspends on this ground. See tite_boin_decision_table.

n_trials

Integer scalar. Number of trials to simulate. Defaults to 10000.

start_dose

Integer scalar. Dose level for the first cohort. Defaults to 1.

n_earlystop

Integer scalar. The trial stops once this many patients have been treated at the current dose and the design would stay there. Defaults to 18.

p_saf

Numeric scalar. Highest DLT probability deemed subtherapeutic. Defaults to 0.6 * target.

p_tox

Numeric scalar. Lowest DLT probability deemed overly toxic. Defaults to 1.4 * target.

cutoff_eli

Numeric scalar. Posterior probability cutoff for dose elimination. Defaults to 0.95.

extrasafe

Logical scalar. Apply the stricter safety stopping rule at the lowest dose. Defaults to FALSE.

offset

Numeric scalar between 0 and 0.5. Amount by which cutoff_eli is relaxed for the safety stopping rule. Defaults to 0.05.

bound_mtd

Logical scalar. Require the isotonic estimate at the selected dose to be at or below the de-escalation boundary. Defaults to FALSE.

mtd_max_estimate

Numeric scalar or NULL. Largest isotonic estimate a dose may have and still be selected as the MTD. See sim_boin.

min_mtd_sample

Integer scalar. Smallest number of patients a dose must have received to be eligible as the MTD. Defaults to 1.

overdose_cutoff

Numeric scalar or NULL. Doses whose true DLT probability exceeds this value count as overdoses in the overdose component of the result. Defaults to NULL, which uses target.

n_earlystop_rule

Character scalar, either "with_stay" or "simple". See boin_simulate.

keep_trials

Logical scalar. Keep the trial by trial data of every scenario. Defaults to FALSE.

verbose

Logical scalar. Report progress while the simulations run. Defaults to FALSE.

seed

Integer scalar or NULL. Random seed, applied to every scenario, so that a scenario simulated here matches the same scenario simulated on its own with sim_tite_boin. Defaults to 123.

Value

An object of class c("tite_boin_oc_multi", "boin_oc_multi"), which is a list with components

results

Named list of tite_boin_oc objects, one per scenario.

summary_table

Data frame collecting all scenarios, with the four rows of sim_boin_multi and two more per scenario for the average trial duration and the percentage of trials with accrual suspended, both in the last column.

scenario_names

Character vector of scenario names.

n_doses

Number of dose levels.

call

The matched call.

See Also

sim_tite_boin, sim_boin_multi

Examples

scenarios <- list(
  list(name = "MTD at dose 3", p_true = c(0.05, 0.15, 0.30, 0.45, 0.60)),
  list(name = "All toxic",     p_true = c(0.35, 0.45, 0.55, 0.65, 0.75))
)

oc <- sim_tite_boin_multi(
  target = 0.30,
  scenarios = scenarios,
  n_cohort = 10,
  cohort_size = 3,
  window = 3,
  accrual_rate = 2,
  n_trials = 200,
  seed = 123
)
oc


Operating Characteristics of the TITE-Comb-BOIN12 Design

Description

Simulate trials of the TITE-Comb-BOIN12 design of Lu et al. (2025), in which the DLT and the response may be observed late, with tite_comb_boin12_simulate, select the optimal biological dose combination (OBDC) of every trial with comb_boin12_select_obd from the complete data, and summarize the selection percentages, the numbers of patients, DLTs and responses at every combination and the trial durations.

Usage

sim_tite_comb_boin12(
  target,
  target_resp,
  p_true,
  p_resp,
  n_cohort,
  cohort_size,
  window,
  accrual_rate,
  resp_window = window,
  accrual = c("uniform", "exponential", "fixed"),
  event_time = c("weibull", "uniform"),
  late_fraction = 0.5,
  resp_late_fraction = 0.5,
  min_completed_share = 0.5,
  pending_estimate = c("conditional", "marginal"),
  pending_use = c("all", "utility"),
  n_trials = 10000,
  start_dose = c(1, 1),
  n_earlystop = NULL,
  n_earlystop_rule = c("with_stay", "simple"),
  p_saf = NULL,
  p_tox = NULL,
  cutoff_eli = 0.95,
  cutoff_eli_resp = 0.9,
  extrasafe = FALSE,
  offset = 0.05,
  psi00 = 40,
  psi11 = 60,
  benchmark_weight = 0.5,
  utility_prior = c(1, 1),
  n_star = 6,
  tie_break = c("higher", "random"),
  no_candidate = c("nearest", "stop"),
  resp_cor = 0,
  resp_cor_type = c("copula", "binary"),
  est_method = c("logistic", "observed"),
  obd_bound = c("rectangle", "contour"),
  dose_a = NULL,
  dose_b = NULL,
  logistic_scale = c(2.5, 2.5),
  n_draws = 4000,
  keep_trials = FALSE,
  verbose = FALSE,
  seed = 123
)

Arguments

target

Numeric scalar. Highest acceptable DLT probability, phi_T. It is the target of the BOIN boundaries lambda_e and lambda_d, of the admissibility of a combination and of the MTD combination that bounds the OBD combination.

target_resp

Numeric scalar. Lowest acceptable response probability, phi_E, as in sim_boin12.

p_true

Numeric matrix. True DLT probability of every combination, with one row per level of drug A and one column per level of drug B.

p_resp

Numeric matrix of the same size. True response probability of every combination.

n_cohort

Integer scalar. Number of cohorts in a trial.

cohort_size

Integer scalar or vector. Number of patients per cohort. A scalar is used for every cohort; a shorter vector is padded with its last element.

window

Numeric scalar. Length of the DLT assessment window.

accrual_rate

Numeric scalar. Average number of patients arriving per unit of time, in the same unit as window.

resp_window

Numeric scalar. Length of the response assessment window. Defaults to window.

accrual

Character scalar. Distribution of the times between arrivals: "uniform" (the default) on (0, 2 / accrual_rate), "exponential" for a Poisson process, or "fixed" for arrivals exactly 1 / accrual_rate apart.

event_time

Character scalar. Distribution of the times to DLT and to response: "weibull" (the default), with the share of the events in the second half of the window set by late_fraction and resp_late_fraction, or "uniform" over the window. With "weibull" the probabilities must be below 1.

late_fraction

Numeric scalar strictly between 0 and 1. Share of the DLTs that occur in the second half of the DLT window under the Weibull distribution. Defaults to 0.5.

resp_late_fraction

Numeric scalar strictly between 0 and 1. The same for the responses. Defaults to 0.5.

min_completed_share

Numeric scalar from 0 to 1. Share of the patients at the current dose who must have finished both assessments before the next decision; the decision, and the accrual, wait until then. Defaults to 0.5, the rule of Zhou et al. (2022), who suspend the accrual when more than half of the patients at the current dose have a pending outcome. With 1 every decision waits for all the outcomes, as in BOIN12.

pending_estimate

Character scalar. Value that replaces a pending outcome Y in the quasi-binomial likelihood: "conditional" (the default), the probability of the event given that it has not occurred during the time followed, pi_hat * (1 - w) / (1 - pi_hat * w), with w the fraction of the window followed, as in Equation (11) of Zhou et al. (2022); or "marginal", the estimate pi_hat itself, which reproduces the desirabilities of Table S.3 of their Supplement. See Details.

pending_use

Character scalar. Where the pending outcomes count: "all" (the default), in the estimated DLT rate of the decision, in the admissibility and in the utility, as in tite_boin12_simulate; "utility", only in the quasi-events of the utility, as Sections 2.2 and 3.1 of Lu et al. (2025) state the rules: the decision uses the observed DLT rate (DLTs over patients treated) and the admissibility the observed numbers of DLTs and responses, a pending outcome counting as no event.

n_trials

Integer scalar. Number of trials to simulate. Defaults to 10000.

start_dose

Integer vector of length 2. Levels of drug A and drug B of the first cohort. Defaults to c(1, 1).

n_earlystop

Integer scalar or NULL. Number of patients at the current combination that ends the trial when the next cohort would stay there (see n_earlystop_rule). Defaults to NULL, which runs every trial to the maximum sample size, as in Lu et al. (2025).

n_earlystop_rule

Character scalar. "with_stay" (the default) ends the trial at n_earlystop only when the next cohort would stay at the current combination; "simple" ends it in any case.

p_saf, p_tox

Numeric scalars or NULL. Highest DLT probability deemed subtherapeutic and lowest deemed overly toxic, which give the BOIN boundaries. Default to 0.6 * target and 1.4 * target.

cutoff_eli

Numeric scalar. A combination is inadmissible, together with every combination with at least the same levels of both drugs, when the posterior probability that its DLT rate exceeds target is at least this cutoff. Defaults to 0.95.

cutoff_eli_resp

Numeric scalar. A combination is inadmissible when the posterior probability that its response rate is below target_resp is at least this cutoff. Defaults to 0.90.

extrasafe

Logical scalar. Apply the cutoff cutoff_eli - offset to the lowest combination, as Lu et al. (2025) do with 0.85. Defaults to FALSE.

offset

Numeric scalar. Amount by which cutoff_eli is lowered at the lowest combination when extrasafe is TRUE. Defaults to 0.05, as in sim_comb_boin; Lu et al. (2025) use 0.10.

psi00, psi11

Numeric scalars from 0 to 100. Utility of a patient without DLT and without response, and with both, as in sim_boin12. Default to 40 and 60. The utility pE - wT * pT of Lu et al. (2025) is psi00 = 100 * wT / (1 + wT) and psi11 = 100 / (1 + wT); their wT = 0.11 is psi00 = 9.90991 and psi11 = 90.09009.

benchmark_weight

Numeric scalar above 0 and at most 1. Weight of the lowest acceptable utility in the utility benchmark, as in sim_boin12; it is the weight w_u of Lu et al. (2025), who use 0.6. Defaults to 0.5.

utility_prior

Numeric vector of two positive numbers. Beta prior of the utility of a combination divided by 100. Defaults to c(1, 1).

n_star

Integer scalar. With at least this many patients at the current combination and a DLT rate between lambda_e and lambda_d, the next combination is chosen from the current one and the two below it. Defaults to 6.

tie_break

Character scalar. Choice among the combinations of equal desirability: "higher" (the default) keeps those with the highest sum of the two levels and draws one of them at random when several remain; "random" draws one of all the tied combinations. See Details.

no_candidate

Character scalar. What happens when none of the combinations allowed for the next cohort is admissible: "nearest" (the default) goes to the admissible combination nearest to the current one; "stop" ends the trial without an OBD combination. See Details.

resp_cor

Numeric scalar between -1 and 1. Correlation between the DLT and the response of a patient, see resp_cor_type. Defaults to 0.

resp_cor_type

Character scalar. "copula" (the default) or "binary", as in sim_boin12.

est_method

Character scalar. Estimate of the response probability: "logistic" (the default) the posterior mean under the logistic model of Lu et al. (2025), see Details; "observed" the observed response rate.

obd_bound

Character scalar. Combinations from which the OBDC is chosen: "rectangle" (the default) those with both levels at most those of the MTDC, as Lu et al. (2025) write; "contour" those, in every column (level of drug B), at most the combination of that column whose isotonic DLT rate is closest to target, the rule that reproduces the results published by Lu et al. (2025). See Details.

dose_a, dose_b

Numeric vectors or NULL. Dose values of the levels of drug A and of drug B in the logistic model. Default to NULL, the level numbers. Each is standardized to mean 0 and standard deviation 0.5.

logistic_scale

Numeric vector of two positive numbers. Scales of the Cauchy priors of the intercept and of the other coefficients of the logistic model. Defaults to c(2.5, 2.5), as in Lu et al. (2025).

n_draws

Integer scalar. Number of points of the importance sampling of the logistic model. Defaults to 4000.

keep_trials

Logical scalar. Keep the simulated trials (trials) and the selected combinations (obd) in the result. Defaults to FALSE.

verbose

Logical scalar. Print progress messages. Defaults to FALSE.

seed

Integer scalar or NULL. Random seed. The state of the calling session is restored on exit. Defaults to 123.

Details

The OBDC of each trial is selected after every patient has finished both assessments, by the rules of comb_boin12_select_obd.

Value

An object of class comb_boin12_oc, as returned by sim_comb_boin12, with design set to "TITE-Comb-BOIN12" and one more component

duration

Average trial duration, in the unit of window.

References

Lu, M., Zhang, J., Yuan, Y. and Lin, R. (2025). Comb-BOIN12: A utility-based Bayesian optimal interval design for dose optimization in cancer drug-combination trials. Statistics in Biopharmaceutical Research, 17(2), 266-276. doi:10.1080/19466315.2024.2370403

See Also

sim_tite_comb_boin12_multi, tite_comb_boin12_simulate, sim_comb_boin12

Examples

# Scenario 16 of Lu et al. (2025), with their design settings, windows of
# 1 and 2 months and two patients a month
p_true <- matrix(c(0.05, 0.10, 0.15, 0.15, 0.20, 0.45), nrow = 2)
p_resp <- matrix(c(0.10, 0.20, 0.30, 0.40, 0.50, 0.60), nrow = 2)
oc <- sim_tite_comb_boin12(
  target = 0.33, target_resp = 0.2, p_true = p_true, p_resp = p_resp,
  n_cohort = 14, cohort_size = 3, window = 1, resp_window = 2,
  accrual_rate = 2, event_time = "uniform", n_trials = 200,
  psi00 = 100 * 0.11 / 1.11, psi11 = 100 / 1.11, benchmark_weight = 0.6,
  extrasafe = TRUE, offset = 0.10, est_method = "observed", seed = 123
)
oc


Operating Characteristics of the TITE-Comb-BOIN12 Design Across Scenarios

Description

Run sim_tite_comb_boin12 for several scenarios of DLT and response probabilities with the same design and collect the results in one table.

Usage

sim_tite_comb_boin12_multi(
  target,
  target_resp,
  scenarios,
  n_cohort,
  cohort_size,
  window,
  accrual_rate,
  resp_window = window,
  accrual = c("uniform", "exponential", "fixed"),
  event_time = c("weibull", "uniform"),
  late_fraction = 0.5,
  resp_late_fraction = 0.5,
  min_completed_share = 0.5,
  pending_estimate = c("conditional", "marginal"),
  pending_use = c("all", "utility"),
  n_trials = 10000,
  start_dose = c(1, 1),
  n_earlystop = NULL,
  n_earlystop_rule = c("with_stay", "simple"),
  p_saf = NULL,
  p_tox = NULL,
  cutoff_eli = 0.95,
  cutoff_eli_resp = 0.9,
  extrasafe = FALSE,
  offset = 0.05,
  psi00 = 40,
  psi11 = 60,
  benchmark_weight = 0.5,
  utility_prior = c(1, 1),
  n_star = 6,
  tie_break = c("higher", "random"),
  no_candidate = c("nearest", "stop"),
  resp_cor = 0,
  resp_cor_type = c("copula", "binary"),
  est_method = c("logistic", "observed"),
  obd_bound = c("rectangle", "contour"),
  dose_a = NULL,
  dose_b = NULL,
  logistic_scale = c(2.5, 2.5),
  n_draws = 4000,
  keep_trials = FALSE,
  verbose = FALSE,
  seed = 123
)

Arguments

target

Numeric scalar. Highest acceptable DLT probability, phi_T. It is the target of the BOIN boundaries lambda_e and lambda_d, of the admissibility of a combination and of the MTD combination that bounds the OBD combination.

target_resp

Numeric scalar. Lowest acceptable response probability, phi_E, as in sim_boin12.

scenarios

List of scenarios. Each element is a list with the matrices p_true and p_resp (one row per level of drug A, one column per level of drug B), and optionally name. Names of the list are used when name is absent. All scenarios must have the same numbers of levels.

n_cohort

Integer scalar. Number of cohorts in a trial.

cohort_size

Integer scalar or vector. Number of patients per cohort. A scalar is used for every cohort; a shorter vector is padded with its last element.

window

Numeric scalar. Length of the DLT assessment window.

accrual_rate

Numeric scalar. Average number of patients arriving per unit of time, in the same unit as window.

resp_window

Numeric scalar. Length of the response assessment window. Defaults to window.

accrual

Character scalar. Distribution of the times between arrivals: "uniform" (the default) on (0, 2 / accrual_rate), "exponential" for a Poisson process, or "fixed" for arrivals exactly 1 / accrual_rate apart.

event_time

Character scalar. Distribution of the times to DLT and to response: "weibull" (the default), with the share of the events in the second half of the window set by late_fraction and resp_late_fraction, or "uniform" over the window. With "weibull" the probabilities must be below 1.

late_fraction

Numeric scalar strictly between 0 and 1. Share of the DLTs that occur in the second half of the DLT window under the Weibull distribution. Defaults to 0.5.

resp_late_fraction

Numeric scalar strictly between 0 and 1. The same for the responses. Defaults to 0.5.

min_completed_share

Numeric scalar from 0 to 1. Share of the patients at the current dose who must have finished both assessments before the next decision; the decision, and the accrual, wait until then. Defaults to 0.5, the rule of Zhou et al. (2022), who suspend the accrual when more than half of the patients at the current dose have a pending outcome. With 1 every decision waits for all the outcomes, as in BOIN12.

pending_estimate

Character scalar. Value that replaces a pending outcome Y in the quasi-binomial likelihood: "conditional" (the default), the probability of the event given that it has not occurred during the time followed, pi_hat * (1 - w) / (1 - pi_hat * w), with w the fraction of the window followed, as in Equation (11) of Zhou et al. (2022); or "marginal", the estimate pi_hat itself, which reproduces the desirabilities of Table S.3 of their Supplement. See Details.

pending_use

Character scalar. Where the pending outcomes count: "all" (the default), in the estimated DLT rate of the decision, in the admissibility and in the utility, as in tite_boin12_simulate; "utility", only in the quasi-events of the utility, as Sections 2.2 and 3.1 of Lu et al. (2025) state the rules: the decision uses the observed DLT rate (DLTs over patients treated) and the admissibility the observed numbers of DLTs and responses, a pending outcome counting as no event.

n_trials

Integer scalar. Number of trials to simulate. Defaults to 10000.

start_dose

Integer vector of length 2. Levels of drug A and drug B of the first cohort. Defaults to c(1, 1).

n_earlystop

Integer scalar or NULL. Number of patients at the current combination that ends the trial when the next cohort would stay there (see n_earlystop_rule). Defaults to NULL, which runs every trial to the maximum sample size, as in Lu et al. (2025).

n_earlystop_rule

Character scalar. "with_stay" (the default) ends the trial at n_earlystop only when the next cohort would stay at the current combination; "simple" ends it in any case.

p_saf, p_tox

Numeric scalars or NULL. Highest DLT probability deemed subtherapeutic and lowest deemed overly toxic, which give the BOIN boundaries. Default to 0.6 * target and 1.4 * target.

cutoff_eli

Numeric scalar. A combination is inadmissible, together with every combination with at least the same levels of both drugs, when the posterior probability that its DLT rate exceeds target is at least this cutoff. Defaults to 0.95.

cutoff_eli_resp

Numeric scalar. A combination is inadmissible when the posterior probability that its response rate is below target_resp is at least this cutoff. Defaults to 0.90.

extrasafe

Logical scalar. Apply the cutoff cutoff_eli - offset to the lowest combination, as Lu et al. (2025) do with 0.85. Defaults to FALSE.

offset

Numeric scalar. Amount by which cutoff_eli is lowered at the lowest combination when extrasafe is TRUE. Defaults to 0.05, as in sim_comb_boin; Lu et al. (2025) use 0.10.

psi00, psi11

Numeric scalars from 0 to 100. Utility of a patient without DLT and without response, and with both, as in sim_boin12. Default to 40 and 60. The utility pE - wT * pT of Lu et al. (2025) is psi00 = 100 * wT / (1 + wT) and psi11 = 100 / (1 + wT); their wT = 0.11 is psi00 = 9.90991 and psi11 = 90.09009.

benchmark_weight

Numeric scalar above 0 and at most 1. Weight of the lowest acceptable utility in the utility benchmark, as in sim_boin12; it is the weight w_u of Lu et al. (2025), who use 0.6. Defaults to 0.5.

utility_prior

Numeric vector of two positive numbers. Beta prior of the utility of a combination divided by 100. Defaults to c(1, 1).

n_star

Integer scalar. With at least this many patients at the current combination and a DLT rate between lambda_e and lambda_d, the next combination is chosen from the current one and the two below it. Defaults to 6.

tie_break

Character scalar. Choice among the combinations of equal desirability: "higher" (the default) keeps those with the highest sum of the two levels and draws one of them at random when several remain; "random" draws one of all the tied combinations. See Details.

no_candidate

Character scalar. What happens when none of the combinations allowed for the next cohort is admissible: "nearest" (the default) goes to the admissible combination nearest to the current one; "stop" ends the trial without an OBD combination. See Details.

resp_cor

Numeric scalar between -1 and 1. Correlation between the DLT and the response of a patient, see resp_cor_type. Defaults to 0.

resp_cor_type

Character scalar. "copula" (the default) or "binary", as in sim_boin12.

est_method

Character scalar. Estimate of the response probability: "logistic" (the default) the posterior mean under the logistic model of Lu et al. (2025), see Details; "observed" the observed response rate.

obd_bound

Character scalar. Combinations from which the OBDC is chosen: "rectangle" (the default) those with both levels at most those of the MTDC, as Lu et al. (2025) write; "contour" those, in every column (level of drug B), at most the combination of that column whose isotonic DLT rate is closest to target, the rule that reproduces the results published by Lu et al. (2025). See Details.

dose_a, dose_b

Numeric vectors or NULL. Dose values of the levels of drug A and of drug B in the logistic model. Default to NULL, the level numbers. Each is standardized to mean 0 and standard deviation 0.5.

logistic_scale

Numeric vector of two positive numbers. Scales of the Cauchy priors of the intercept and of the other coefficients of the logistic model. Defaults to c(2.5, 2.5), as in Lu et al. (2025).

n_draws

Integer scalar. Number of points of the importance sampling of the logistic model. Defaults to 4000.

keep_trials

Logical scalar. Keep the simulated trials (trials) and the selected combinations (obd) in the result. Defaults to FALSE.

verbose

Logical scalar. Print progress messages. Defaults to FALSE.

seed

Integer scalar or NULL. Random seed. The state of the calling session is restored on exit. Defaults to 123.

Details

Every scenario is simulated with the same seed, so that a scenario simulated here matches the same scenario simulated on its own with sim_tite_comb_boin12.

Value

An object of class comb_boin12_oc_multi, as returned by sim_comb_boin12_multi, whose summary table also has the average trial duration of every scenario (Duration).

See Also

sim_tite_comb_boin12

Examples

# Scenarios 16 and 17 of Lu et al. (2025), windows of 1 and 2 months
scenarios <- list(
  "Scenario 16" = list(
    p_true = matrix(c(0.05, 0.10, 0.15, 0.15, 0.20, 0.45), nrow = 2),
    p_resp = matrix(c(0.10, 0.20, 0.30, 0.40, 0.50, 0.60), nrow = 2)),
  "Scenario 17" = list(
    p_true = matrix(c(0.05, 0.10, 0.15, 0.20, 0.40, 0.50), nrow = 2),
    p_resp = matrix(c(0.10, 0.20, 0.30, 0.40, 0.50, 0.55), nrow = 2))
)
oc <- sim_tite_comb_boin12_multi(
  target = 0.33, target_resp = 0.2, scenarios = scenarios,
  n_cohort = 14, cohort_size = 3, window = 1, resp_window = 2,
  accrual_rate = 2, event_time = "uniform", n_trials = 100,
  psi00 = 100 * 0.11 / 1.11, psi11 = 100 / 1.11, benchmark_weight = 0.6,
  extrasafe = TRUE, offset = 0.10, est_method = "observed", seed = 1
)
oc


Simulate TITE-BOIN12 Trials

Description

Simulate trials of the TITE-BOIN12 design of Zhou et al. (2022), the time-to-event version of BOIN12 in which patients arrive over time, the DLT and the response are assessed over windows and the decisions use the outcomes still pending through the approximated likelihood. Return the patients, DLTs and responses at every dose. This is the simulation engine behind sim_tite_boin12.

Usage

tite_boin12_simulate(
  target,
  target_resp,
  p_true,
  p_resp,
  n_cohort,
  cohort_size,
  window,
  accrual_rate,
  resp_window = window,
  accrual = c("uniform", "exponential", "fixed"),
  event_time = c("weibull", "uniform"),
  late_fraction = 0.5,
  resp_late_fraction = 0.5,
  min_completed_share = 0.5,
  pending_estimate = c("conditional", "marginal"),
  n_trials = 10000,
  start_dose = 1,
  n_earlystop = NULL,
  n_earlystop_rule = c("with_stay", "simple"),
  p_saf = NULL,
  p_tox = NULL,
  cutoff_eli = 0.95,
  cutoff_eli_resp = 0.9,
  psi00 = 40,
  psi11 = 60,
  benchmark_weight = 0.5,
  utility_prior = c(1, 1),
  n_star = 6,
  n_explore = 9,
  tie_break = c("higher", "random"),
  no_candidate = c("nearest", "stop"),
  explore_from = c("any", "admissible"),
  resp_cor = 0,
  resp_cor_type = c("copula", "binary"),
  seed = 123
)

Arguments

target

Numeric scalar. Highest acceptable DLT probability, called phi_T by Lin et al. (2020). It is the target of the BOIN boundaries lambda_e and lambda_d, of the admissibility of a dose and of the MTD that bounds the OBD. Lin et al. recommend a value slightly above the target of a design that only considers toxicity, for example 0.35 instead of 0.30.

target_resp

Numeric scalar. Lowest acceptable response probability, phi_E. Note that this is a lower limit, as in sim_bf_boin_et, whereas the target_resp of sim_boin_et is a target.

p_true

Numeric vector. True DLT probability at each dose.

p_resp

Numeric vector. True response probability at each dose.

n_cohort

Integer scalar. Number of cohorts in a trial.

cohort_size

Integer scalar or vector. Number of patients per cohort. A scalar is used for every cohort; a shorter vector is padded with its last element.

window

Numeric scalar. Length of the DLT assessment window.

accrual_rate

Numeric scalar. Average number of patients arriving per unit of time, in the same unit as window.

resp_window

Numeric scalar. Length of the response assessment window. Defaults to window.

accrual

Character scalar. Distribution of the times between arrivals: "uniform" (the default) on (0, 2 / accrual_rate), "exponential" for a Poisson process, or "fixed" for arrivals exactly 1 / accrual_rate apart.

event_time

Character scalar. Distribution of the times to DLT and to response: "weibull" (the default), with the share of the events in the second half of the window set by late_fraction and resp_late_fraction, or "uniform" over the window. With "weibull" the probabilities must be below 1.

late_fraction

Numeric scalar strictly between 0 and 1. Share of the DLTs that occur in the second half of the DLT window under the Weibull distribution. Defaults to 0.5.

resp_late_fraction

Numeric scalar strictly between 0 and 1. The same for the responses. Defaults to 0.5.

min_completed_share

Numeric scalar from 0 to 1. Share of the patients at the current dose who must have finished both assessments before the next decision; the decision, and the accrual, wait until then. Defaults to 0.5, the rule of Zhou et al. (2022), who suspend the accrual when more than half of the patients at the current dose have a pending outcome. With 1 every decision waits for all the outcomes, as in BOIN12.

pending_estimate

Character scalar. Value that replaces a pending outcome Y in the quasi-binomial likelihood: "conditional" (the default), the probability of the event given that it has not occurred during the time followed, pi_hat * (1 - w) / (1 - pi_hat * w), with w the fraction of the window followed, as in Equation (11) of Zhou et al. (2022); or "marginal", the estimate pi_hat itself, which reproduces the desirabilities of Table S.3 of their Supplement. See Details.

n_trials

Integer scalar. Number of trials to simulate. Defaults to 10000.

start_dose

Integer scalar. Dose level of the first cohort. Defaults to 1.

n_earlystop

Integer scalar or NULL. Number of patients at the current dose that ends the trial when the next cohort would stay there (see n_earlystop_rule). Defaults to NULL, which runs every trial to the maximum sample size, as in Lin et al. (2020).

n_earlystop_rule

Character scalar. "with_stay" (the default) ends the trial at n_earlystop only when the next cohort would stay at the current dose, as in the example of Zhou et al. (2022); "simple" ends it in any case.

p_saf, p_tox

Numeric scalars or NULL. Highest DLT probability deemed subtherapeutic and lowest deemed overly toxic, which give the BOIN boundaries. Default to 0.6 * target and 1.4 * target.

cutoff_eli

Numeric scalar. A dose is inadmissible, together with every higher dose, when the posterior probability that its DLT rate exceeds target is at least this cutoff. Defaults to 0.95.

cutoff_eli_resp

Numeric scalar. A dose is inadmissible when the posterior probability that its response rate is below target_resp is at least this cutoff. Defaults to 0.90.

psi00, psi11

Numeric scalars from 0 to 100. Utility of a patient without DLT and without response, and with both. The utility of a response without DLT is 100 and that of a DLT without response is 0. Default to 40 and 60, the example of Lin et al. (2020).

benchmark_weight

Numeric scalar above 0 and at most 1. The utility benchmark is benchmark_weight * u_low + (1 - benchmark_weight) * 100, where u_low is the expected utility of a dose whose DLT and response probabilities are target and target_resp, the two outcomes being independent. Defaults to 0.5, the benchmark of Lin et al. (2020); Lu et al. (2025) use 0.6.

utility_prior

Numeric vector of two positive numbers. Beta prior of the utility of a dose divided by 100. Defaults to c(1, 1).

n_star

Integer scalar. With at least this many patients at the current dose and a DLT rate between lambda_e and lambda_d, the next dose is chosen from the current dose and the dose below. Defaults to 6.

n_explore

Integer scalar. With at least this many patients at the current dose, a DLT rate below lambda_d and an untried admissible dose above, the next cohort goes to that dose. Defaults to 9.

tie_break

Character scalar. Choice among the doses of equal desirability: "higher" (the default) takes the highest of them, the rule of the BOIN12 software according to the 'escalation' package; "random" takes one of them at random, as stated in Table S2 of the Supplement of Lin et al. (2020). See Details.

no_candidate

Character scalar. What happens when none of the doses allowed for the next cohort is admissible: "nearest" (the default) goes to the admissible dose nearest to the current one; "stop" ends the trial without an OBD. See Details.

explore_from

Character scalar. Doses from which the exploration rule (see n_explore) escalates: "any" (the default) from any dose, as in the 'escalation' package; "admissible" only from an admissible dose, as the results published by Lin et al. (2020) indicate. See Details.

resp_cor

Numeric scalar between -1 and 1. Correlation between the DLT and the response of a patient, see resp_cor_type; with "copula" it also links the time to DLT and the time to response. Defaults to 0.

resp_cor_type

Character scalar. "copula" (the default) links the two outcomes by a Gaussian copula with correlation resp_cor, the bivariate normal model of Lin et al. (2020); "binary" sets the correlation of the two binary outcomes, as in boin_et_simulate.

seed

Integer scalar or NULL. Random seed. The state of the calling session is restored on exit. Defaults to 123.

Details

The first patient of a cohort arrives at the time of the previous decision, and the next decision is due when the next patient arrives. While fewer than a share min_completed_share of the patients at the current dose have finished both assessments, the decision waits for the next assessment to end. After the last cohort, and when the trial stops because n_earlystop is reached, the trial waits until every patient has finished both assessments, and the OBD is selected from the complete data, as in the example of Zhou et al. (2022).

At a decision, an outcome is observed once its event has occurred or its window has ended, and pending otherwise. For each dose, with w the fraction of the window followed by a pending patient, the DLT probability is estimated by pi_hat = DLTs observed / (DLTs observed + patients who completed the window without DLT + sum of w) (Equation 14 of the Supplement), and the response probability in the same way. The quasi-events of BOIN12 count each patient with a pending outcome by the expected utility, the pending outcome being replaced as set by pending_estimate and the two outcomes taken as independent for this purpose only. The desirability is that of BOIN12 with these quasi-events and the number of patients treated, and the rules of boin12_simulate are applied with pi_hat of the DLTs as the DLT rate of the current dose. With every outcome observed, these are exactly the quantities of BOIN12, so that min_completed_share = 1 with accrual = "fixed" gives the trials of boin12_simulate with the same seed.

Two points are not settled by Zhou et al. (2022) and are decided here as follows. Equation (11) replaces a pending outcome by its conditional expectation, but the desirabilities of their Table S.3 follow from pi_hat itself; both are offered by pending_estimate. The admissibility of a dose, which they update at every decision, uses the posterior of the approximated likelihood, Beta(1 + DLTs observed, 1 + patients who completed the window without DLT + sum of w), and the same for the responses, so that a response that is merely late does not exclude a dose. TITE-BOIN-ET (tite_boin_et_simulate) instead counts the pending patients as patients without the event, as the 'boinet' package does.

Each patient draws two uniform variates as in boin12_simulate; the time to DLT and the time to response are quantiles of their distributions at these variates, so that a DLT and a response occur within their windows with the probabilities p_true and p_resp. The times between arrivals draw further variates unless accrual = "fixed", and with tie_break = "random" a decision among tied doses draws one more variate after those of the cohort, as in boin12_simulate.

Value

An object of class boin12_trials, as returned by boin12_simulate, with design set to "TITE-BOIN12" and one more component

duration

Numeric vector of the duration of each trial: the time at which every patient has finished both assessments, or the time of the decision that stopped the trial because no dose was admissible or, with no_candidate = "stop", because no dose allowed for the next cohort was admissible.

The DLTs and responses are the final outcomes of all the patients.

References

Zhou, Y., Lin, R., Lee, J. J., Li, D., Wang, L., Li, R. and Yuan, Y. (2022). TITE-BOIN12: A Bayesian phase I/II trial design to find the optimal biological dose with late-onset toxicity and efficacy. Statistics in Medicine, 41(11), 1918-1931. doi:10.1002/sim.9337

Lin, R., Zhou, Y., Yan, F., Li, D. and Yuan, Y. (2020). BOIN12: Bayesian optimal interval phase I/II trial design for utility-based dose finding in immunotherapy and targeted therapies. JCO Precision Oncology, 4, 1393-1402. doi:10.1200/PO.20.00257

See Also

sim_tite_boin12, boin12_simulate, boin12_select_obd

Examples

# Scenario 1 of Zhou et al. (2022), windows of 45 and 60 days and three
# patients a month
trials <- tite_boin12_simulate(
  target = 0.35, target_resp = 0.25,
  p_true = c(0.05, 0.12, 0.27, 0.35, 0.50),
  p_resp = c(0.20, 0.35, 0.36, 0.37, 0.38),
  n_cohort = 12, cohort_size = 3, window = 45, resp_window = 60,
  accrual_rate = 3 / 30, n_trials = 200, seed = 123
)
trials
summary(trials$duration)


Decision Table for the TITE-BOIN Design

Description

Tabulate the dose assignment rule of the time-to-event Bayesian optimal interval (TITE-BOIN) design, which allows new patients to be treated while the DLT assessment of earlier patients is still pending. For every attainable combination of patients treated, DLTs observed and patients pending at the current dose, the table gives the decision or, when the decision depends on how long the pending patients have been followed, the values of the follow-up statistic at which it changes.

Usage

tite_boin_decision_table(
  target,
  max_n,
  method = c("imputation", "ess"),
  p_saf = NULL,
  p_tox = NULL,
  cutoff_eli = 0.95,
  max_pending_ratio = NULL,
  min_completed = NULL,
  min_follow_up = 0
)

Arguments

target

Numeric scalar. Target DLT probability, for example 0.30.

max_n

Integer scalar. Largest number of patients treated at a single dose.

method

Character scalar. How the pending patients enter the estimate of the DLT probability: "imputation" (the default) for the single mean imputation of Yuan et al. (2018), or "ess" for the effective sample size of Lin and Yuan (2020). See the details.

p_saf

Numeric scalar. Highest DLT probability deemed subtherapeutic. Defaults to 0.6 * target.

p_tox

Numeric scalar. Lowest DLT probability deemed overly toxic. Defaults to 1.4 * target.

cutoff_eli

Numeric scalar. Posterior probability cutoff for dose elimination. Defaults to 0.95.

max_pending_ratio

Numeric scalar greater than 0 and at most 1. Accrual is suspended when the proportion of the patients at the current dose whose assessment is pending exceeds this value, unless the dose is de-escalated whatever their outcomes. Defaults to 0.5 for "imputation", following Yuan et al. (2018), and to 1, which never suspends on this ground, for "ess".

min_completed

Integer scalar. While some patients are pending, escalation requires at least this many patients at the current dose to have completed the assessment, and accrual is suspended instead when fewer have. Defaults to 0 for "imputation" and to 2 for "ess", following Lin and Yuan (2020).

min_follow_up

Numeric scalar between 0 and 1. While some patients are pending, escalation also requires the shortest follow-up among the pending patients at the current dose, as a fraction of the assessment window (MF), to be at least this value, and accrual is suspended instead when it is not. Defaults to 0, which never suspends on this ground. Chen et al. (2025) recommend 0.25, their rule 2 with B = 25. The rule leaves the boundaries on the follow-up statistic unchanged, so it is recorded as an attribute rather than in the rows of the table.

Details

Suppose that n patients have been treated at the current dose, that r of them have completed the DLT assessment with n_tox DLTs, and that c = n - r are pending. The standardized total follow-up time (STFT) is the sum of the follow-up times of the pending patients divided by the length of the assessment window, so that STFT lies between 0 and c. With no pending patient the decision is that of the BOIN design, taken from boin_boundary.

method = "imputation" replaces each pending outcome by its expected value under a uniform time to DLT. The estimate of the DLT probability is (n_tox + q * (c - STFT)) / n, where q = p / (1 - p) and p = (n_tox + a) / (r + 1) is the posterior mean under a Beta(a, 1 - a) prior with a = target / 2 (Yuan et al., 2018, Supplementary Appendix A). The estimate decreases as STFT grows, so the rule becomes a pair of boundaries on STFT. As in the BOIN design, escalation is possible only while n_tox / n is below the target and de-escalation only once it reaches the target.

method = "ess" uses the approximated likelihood of Lin and Yuan (2020), under which the estimate is n_tox / ESS with the effective sample size ESS = r + STFT, which lies between r and n. The dose is escalated when ESS is at least n_tox / lambda_e and de-escalated when it is at most n_tox / lambda_d. The boundaries in the table refer to ESS.

The rules are applied in this order: elimination; de-escalation that holds whatever the outcomes of the pending patients, that is when n_tox / n is at least lambda_d; suspension for too many pending patients; and finally the boundaries on the follow-up statistic, in which an escalation blocked by min_completed becomes a suspension. An escalation that remains is then subject to min_follow_up. Elimination requires Pr(p > target | data) > cutoff_eli computed with all n treated patients, the pending ones counted as without DLT, which is how both articles define it. It is not evaluated before three patients have been treated.

Neither the length of the assessment window nor the weights given to the follow-up times change the table, because both enter only through STFT. A weighted STFT, such as that of a piecewise uniform time to DLT, is compared with the same boundaries.

Value

An object of class tite_boin_decision_table, which is a data frame with one row per attainable state of the current dose, ordered by n, n_tox and n_pending, and with the columns

n

Number of patients treated at the current dose, from 1 to max_n.

n_tox

Number of DLTs observed, which can only come from patients who completed the assessment.

n_pending

Number of patients whose assessment is pending.

decision

Decision code. "E" escalates, "S" stays, "D" de-escalates, "DE" de-escalates and eliminates the dose together with all higher doses, and "SUS" suspends accrual until more data are available. These do not depend on the follow-up of the pending patients. The codes "E/S", "S/D" and "E/S/D" mark states whose decision depends on the follow-up statistic through esc_bound and deesc_bound; in them "SUS" takes the place of "E" when escalation is blocked by min_completed.

esc_bound

Escalate, or suspend when escalation is blocked, when the follow-up statistic is at least this value. NA when no such boundary applies.

deesc_bound

De-escalate when the follow-up statistic is at most this value. NA when no such boundary applies.

The design parameters are stored as attributes: method, statistic ("STFT" or "ESS"), target, p_saf, p_tox, lambda_e, lambda_d, cutoff_eli, max_pending_ratio, min_completed and min_follow_up. When min_follow_up is positive, an escalation (code "E", or "E" as the first part of a code with a slash) in a state with pending patients takes place only when MF is at least min_follow_up, and accrual is suspended otherwise. The object has print and plot methods.

Agreement with the published tables

With the defaults, method = "imputation" reproduces every entry of Table 1 (target 0.2) of Yuan et al. (2018) and of Table S1 (target 0.3) of its supplementary appendix. These tables allow de-escalation when n_tox / n equals the target (Table 1, 15 patients with 3 DLTs), which equation (5) of the appendix, read literally, would not. The implementation follows the tables, which agree with the verbal description of the rule in the appendix.

With max_pending_ratio = 0.49 and min_follow_up = 0.25, method = "imputation" reproduces every entry of Table 1 (target 0.3, up to six patients) of Chen et al. (2025) and of Table A1 (target 0.25, up to nine patients) of the supplementary materials of Chen et al. (2026). Their rule 1 suspends accrual when fewer than 51 percent of the patients have completed the assessment, which for whole numbers of patients is the same as more than 49 percent pending, unless the observed DLT rate already exceeds lambda_d; this exception is the de-escalation that holds whatever the outcomes of the pending patients.

For method = "ess" no table for the BOIN design has been published; the tables of Lin and Yuan (2020) are for the keyboard and mTPI designs.

References

Yuan, Y., Lin, R., Li, D., Nie, L. and Warren, K. E. (2018). Time-to-Event Bayesian Optimal Interval Design to Accelerate Phase I Trials. Clinical Cancer Research, 24(20), 4921-4930.

Lin, R. and Yuan, Y. (2020). Time-to-Event Model-Assisted Designs for Dose-Finding Trials with Delayed Toxicity. Biostatistics, 21(4), 807-824.

Chen, K., Chen, T.-Y., Zhang, Y., Lin, R. and Yuan, Y. (2025). Practical Considerations for Using the TITE-BOIN Design to Handle Late-Onset Toxicity or Fast Accrual in Phase I Trials. Clinical Cancer Research, 31(13), 2573-2580.

Chen, K., Zhao, Y., Takeda, K. and Yuan, Y. (2026). BE-BOIN: A Dose Optimization Design Accommodating Backfill and Late-Onset Toxicity. Therapeutic Innovation and Regulatory Science. doi:10.1007/s43441-026-00994-0

See Also

print.tite_boin_decision_table, plot.tite_boin_decision_table, boin_decision_table

Examples

# Table 1 of Yuan et al. (2018)
decisions <- tite_boin_decision_table(target = 0.2, max_n = 15)
print(decisions, cohort_size = 3)

# Nine patients, one DLT and four pending: escalate once STFT reaches 2.15
decisions[decisions$n == 9 & decisions$n_tox == 1 & decisions$n_pending == 4, ]

# Table 1 of Chen et al. (2025): at least 51 percent of the patients with a
# completed assessment, and escalation only once every pending patient has
# been followed for a quarter of the window
decisions_chen <- tite_boin_decision_table(target = 0.3, max_n = 6,
                                           max_pending_ratio = 0.49,
                                           min_follow_up = 0.25)
print(decisions_chen, cohort_size = 3)

# The effective sample size of Lin and Yuan (2020)
decisions_ess <- tite_boin_decision_table(target = 0.3, max_n = 12, method = "ess")
print(decisions_ess, cohort_size = 3)


Simulate TITE-BOIN-ET Trials

Description

Run the TITE-BOIN-ET dose-finding algorithm of Takeda, Morita and Taguri (2020) over many simulated trials, in which patients arrive over time and the DLT and the response are assessed over windows, and return the patient, DLT and response counts at every dose. This is the simulation engine behind sim_tite_boin_et, exposed for users who want the raw trial data.

Usage

tite_boin_et_simulate(
  target,
  target_resp,
  p_true,
  p_resp,
  n_cohort,
  cohort_size,
  window,
  accrual_rate,
  resp_window = window,
  accrual = c("uniform", "exponential", "fixed"),
  event_time = c("weibull", "uniform"),
  late_fraction = 0.5,
  resp_late_fraction = 0.5,
  resp_cor = 0.2,
  min_completed_share = 0.5,
  n_trials = 10000,
  start_dose = 1,
  n_earlystop = NULL,
  p_saf = NULL,
  p_tox = NULL,
  p_saf_resp = NULL,
  cutoff_eli = 0.95,
  cutoff_eli_resp = 0.99,
  p_eli = NULL,
  p_eli_resp = NULL,
  boinet_compatible = FALSE,
  prior = rep(1/6, 6),
  seed = 123
)

Arguments

target

Numeric scalar. Target DLT probability, for example 0.30.

target_resp

Numeric scalar. Target response probability, for example 0.60.

p_true

Numeric vector. True DLT probability at each dose level, in increasing dose order.

p_resp

Numeric vector of the same length as p_true. True response probability at each dose level.

n_cohort

Integer scalar. Number of cohorts in a trial.

cohort_size

Integer scalar or vector. Number of patients per cohort. A scalar is used for every cohort. A vector shorter than n_cohort is padded with its last element and a longer one is truncated.

window

Numeric scalar. Length of the DLT assessment window.

accrual_rate

Numeric scalar. Average number of patients arriving per unit of time, in the same unit as window. The accrual argument of the 'boinet' package is the average time between arrivals, its inverse.

resp_window

Numeric scalar. Length of the response assessment window. Defaults to window.

accrual

Character scalar. Distribution of the times between arrivals: "uniform" (the default, as in 'boinet') on (0, 2 / accrual_rate), "exponential" for a Poisson process, or "fixed" for arrivals exactly 1 / accrual_rate apart.

event_time

Character scalar. Distribution of the times to DLT and to response: "weibull" (the default), with the share of the events in the second half of the window set by late_fraction and resp_late_fraction, or "uniform" on (0, window / p) for an event of probability p. With "weibull" the probabilities must be below 1.

late_fraction

Numeric scalar strictly between 0 and 1. Share of the DLTs that occur in the second half of the DLT window under the Weibull distribution. Defaults to 0.5.

resp_late_fraction

Numeric scalar strictly between 0 and 1. The same for the responses. Defaults to 0.5.

resp_cor

Numeric scalar strictly between -1 and 1. Correlation of the Gaussian copula that links the time to DLT and the time to response of a patient. Defaults to 0.2, the default of the 'boinet' package.

min_completed_share

Numeric scalar from 0 to 1. Share of the patients at the current dose who must have finished both assessments before the next decision; the decision waits until then. Defaults to 0.5, the rule of the 'boinet' package. Takeda et al. (2020) did not wait in their simulations, which is min_completed_share = 0, and recommended such a rule when the accrual is fast.

n_trials

Integer scalar. Number of trials to simulate. Defaults to 10000.

start_dose

Integer scalar. Dose level for the first cohort. Defaults to 1.

n_earlystop

Integer scalar or NULL. The trial stops once this many patients have been treated at any dose. Defaults to NULL, the maximum sample size, which is the default of the 'boinet' package.

p_saf

Numeric scalar. Highest DLT probability deemed subtherapeutic. Defaults to 0.1 * target, the value recommended by Takeda et al. (2018), which is far below the 0.6 * target of the BOIN design.

p_tox

Numeric scalar. Lowest DLT probability deemed overly toxic. Defaults to 1.4 * target.

p_saf_resp

Numeric scalar. Highest response probability deemed subtherapeutic. Defaults to 0.6 * target_resp.

cutoff_eli

Numeric scalar. A dose is no longer admissible when the posterior probability that its DLT rate is below p_eli falls below 1 - cutoff_eli. Defaults to 0.95.

cutoff_eli_resp

Numeric scalar. A dose is no longer admissible when the posterior probability that its response rate is above p_eli_resp falls below 1 - cutoff_eli_resp. Defaults to 0.99.

p_eli

Numeric scalar or NULL. DLT probability of the rule above. Defaults to NULL, which uses target as the 'boinet' package does. Takeda et al. (2018) used 0.40 with a cutoff of 0.90.

p_eli_resp

Numeric scalar or NULL. Response probability of the rule above. Defaults to NULL, which uses p_saf_resp as the 'boinet' package does. Takeda et al. (2018) used 0.20 with a cutoff of 0.90.

boinet_compatible

Logical scalar. Apply the rules of the 'boinet' package (version 1.6.0) exactly. Defaults to FALSE, which keeps to Takeda et al. (2018), who do not allow dose skipping during escalation; see Details.

prior

Numeric vector of length 6. Prior probabilities of the six hypotheses. Defaults to rep(1 / 6, 6), the noninformative choice of the article. The third hypothesis, under which every decision is correct, does not enter the criterion.

seed

Integer scalar or NULL. Random seed. When NULL the current state of the random number generator is used. The state of the calling session is restored on exit. Defaults to 123.

Details

The first patient of a cohort arrives at the time of the previous decision, and the next decision is due when the next patient arrives; after the last cohort it is due once every patient has been followed over both windows. While fewer than a share min_completed_share of the patients at the current dose have finished both assessments, the decision waits for the next assessment to end. The DLT and response rates of a dose then count a patient still under assessment by the fraction of the window followed so far (Takeda et al., 2020), and the decision rule of BOIN-ET is applied to these rates. The admissibility of the doses, which counts the patients still under assessment as patients without the event, and the moves between doses follow boin_et_simulate, including the changes from 'boinet' unless boinet_compatible is TRUE. These are the rules of boinet::tite.boinet().

The two event times of a patient come from their marginal distributions linked by a Gaussian copula, so that a DLT and a response occur within their windows with the probabilities p_true and p_resp. Each patient draws two uniform variates, so the trials agree with those of 'boinet' in distribution, not one by one.

Value

An object of class boin_et_trials, as returned by boin_et_simulate, with design set to "TITE-BOIN-ET" and one more component

duration

Numeric vector of the time of the last decision of each trial, which is the trial duration when all cohorts are enrolled.

The DLTs and responses are those observed at the last decision.

References

Takeda, K., Morita, S. and Taguri, M. (2020). TITE-BOIN-ET: Time-to-event Bayesian optimal interval design to accelerate dose-finding based on both efficacy and toxicity outcomes. Pharmaceutical Statistics, 19, 335-349. doi:10.1002/pst.1995

Yamaguchi, Y., Takeda, K. and Maruo, K. (2025). boinet: An R Package for Bayesian Optimal Interval Design for Dose Finding Based on Both Efficacy and Toxicity Outcomes. The R Journal, 17(2), 15-34. doi:10.32614/RJ-2025-012

See Also

sim_tite_boin_et, boin_et_select_obd

Examples

trials <- tite_boin_et_simulate(
  target = 0.30, target_resp = 0.60,
  p_true = c(0.05, 0.15, 0.25, 0.30, 0.35, 0.40),
  p_resp = c(0.05, 0.35, 0.55, 0.65, 0.75, 0.70),
  n_cohort = 12, cohort_size = 3, window = 30, resp_window = 45,
  accrual_rate = 1 / 10, n_trials = 200, seed = 123
)
trials
summary(trials$duration)


Simulate TITE-BOIN Trials

Description

Run the time-to-event BOIN (TITE-BOIN) design over many simulated trials, in which patients arrive over time and new patients are treated while the DLT assessment of earlier patients is still pending. Return the patient and DLT counts at every dose together with the duration of each trial and the time spent with accrual suspended.

Usage

tite_boin_simulate(
  target,
  p_true,
  n_cohort,
  cohort_size,
  window,
  accrual_rate,
  method = c("imputation", "ess"),
  accrual = c("exponential", "uniform", "fixed"),
  dlt_time = c("weibull", "uniform"),
  late_fraction = 0.5,
  prior_weights = c(1, 1, 1)/3,
  max_pending_ratio = NULL,
  min_completed = NULL,
  min_follow_up = 0,
  n_trials = 10000,
  start_dose = 1,
  n_earlystop = 18,
  p_saf = NULL,
  p_tox = NULL,
  cutoff_eli = 0.95,
  extrasafe = FALSE,
  offset = 0.05,
  n_earlystop_rule = c("with_stay", "simple"),
  seed = 123
)

Arguments

target

Numeric scalar. Target DLT probability, for example 0.30.

p_true

Numeric vector. True DLT probability at each dose level, in increasing dose order. The probability of a DLT within the assessment window.

n_cohort

Integer scalar. Number of cohorts in a trial.

cohort_size

Integer scalar or vector. Number of patients per cohort. A scalar is used for every cohort. A vector shorter than n_cohort is padded with its last element and a longer one is truncated.

window

Numeric scalar. Length of the DLT assessment window.

accrual_rate

Numeric scalar. Average number of patients arriving per unit of time, in the same unit as window.

method

Character scalar, "imputation" (the default) or "ess". How the pending patients enter the estimate of the DLT probability. See tite_boin_decision_table.

accrual

Character scalar. Distribution of the times between arrivals: "exponential" (the default) for a Poisson process, "uniform" for a uniform distribution on (0, 2 / accrual_rate), as in the code of Lin and Yuan (2020), or "fixed" for arrivals exactly 1 / accrual_rate apart.

dlt_time

Character scalar. Distribution of the time to DLT within the window: "weibull" (the default), with the share of DLTs in the second half of the window set by late_fraction, or "uniform".

late_fraction

Numeric scalar strictly between 0 and 1. Share of the DLTs that occur in the second half of the assessment window under the Weibull distribution. Defaults to 0.5, the setting of Yuan et al. (2018) and Lin and Yuan (2020).

prior_weights

Numeric vector of three non-negative values. Prior probabilities that a DLT occurs in the first, second and last third of the assessment window, used to weight the follow-up of the pending patients in STFT (Yuan et al., 2018, Supplementary Appendix D) and ESS (Lin and Yuan, 2020, Supplementary S1). They are rescaled to sum to one. Defaults to equal weights, which give the unweighted STFT. The decision table does not change with the weights; only the value compared with its boundaries does. This describes the design and is separate from dlt_time and late_fraction, which describe how the simulated DLTs actually occur.

max_pending_ratio

Numeric scalar or NULL. Suspension rule on the proportion of pending patients. See tite_boin_decision_table.

min_completed

Integer scalar or NULL. Number of completed assessments required for escalation. See tite_boin_decision_table.

min_follow_up

Numeric scalar between 0 and 1. Shortest follow-up, as a fraction of window, that every pending patient at the current dose must have reached before the dose is escalated; accrual is suspended until then. Defaults to 0, which never suspends on this ground. See tite_boin_decision_table.

n_trials

Integer scalar. Number of trials to simulate. Defaults to 10000.

start_dose

Integer scalar. Dose level for the first cohort. Defaults to 1.

n_earlystop

Integer scalar. The trial stops once this many patients have been treated at the current dose and the design would stay there. Defaults to 18.

p_saf

Numeric scalar. Highest DLT probability deemed subtherapeutic. Defaults to 0.6 * target.

p_tox

Numeric scalar. Lowest DLT probability deemed overly toxic. Defaults to 1.4 * target.

cutoff_eli

Numeric scalar. Posterior probability cutoff for dose elimination. Defaults to 0.95.

extrasafe

Logical scalar. Apply the stricter safety stopping rule at the lowest dose. Defaults to FALSE.

offset

Numeric scalar between 0 and 0.5. Amount by which cutoff_eli is relaxed for the safety stopping rule. Defaults to 0.05.

n_earlystop_rule

Character scalar, either "with_stay" or "simple". See boin_simulate.

seed

Integer scalar or NULL. Random seed. When NULL the current state of the random number generator is used. The state of the calling session is restored on exit. Defaults to 123.

Details

Patients arrive one at a time. The dose for a cohort is decided when its first patient arrives, from the data available at that moment, and the other patients of the cohort receive the same dose. The decision follows tite_boin_decision_table. A patient with a DLT completes the assessment when the DLT occurs, and a patient without one at the end of the window. When the decision is to suspend accrual, the arriving patient waits until the next pending patient at the current dose completes the assessment, or, with a positive min_follow_up, until the last pending patient to arrive at the current dose has been followed for that fraction of the window, whichever comes first, and the decision is taken again at that moment. Later patients arrive after the one who waited.

At every decision the rules are applied in the order used by boin_simulate: elimination at the current dose and the extra safety rule, early stopping on n_earlystop, then the dose transition. Because DLTs can be observed after a dose has been left, the elimination rule is also checked at the other doses; a dose that meets it is eliminated together with all higher doses, and the trial moves below it. Elimination counts every treated patient, the pending ones as without DLT.

One uniform variate is drawn from R's random number stream per patient, in enrollment order and in the cohort blocks of boin_simulate. It decides whether the patient has a DLT and, under the Weibull distribution, gives the time to DLT through the inverse distribution function, which falls inside the window exactly when there is a DLT. The times between arrivals come from a second generator (xoshiro256**) seeded with seed, or with one draw from R's stream when seed is NULL. As a result, whenever no patient is pending at any decision, for example with accrual = "fixed" and window shorter than 1 / accrual_rate, the trials are identical to those of boin_simulate with the same seed.

The follow-up of a pending patient counts towards STFT as the share of the window already covered, or, with prior_weights, as the prior probability that a DLT would have occurred by then. Both articles evaluate their designs with equal weights, the default.

The titration phase and the stay_on_1_of_3 option of boin_simulate are not available, as neither article defines them for the time-to-event design.

Value

An object of class tite_boin_trials, which is a list with components

n_pts

Integer matrix, n_trials by number of doses, of patients treated.

n_tox

Integer matrix of the same shape, of DLTs, counted once every patient has completed the assessment.

eliminated

Logical matrix of the same shape, marking doses eliminated during the trial.

cohorts_used

Integer vector of cohorts treated in each trial.

stop_reason

Character vector giving why each trial ended, with the values of boin_simulate.

duration

Numeric vector. Time from the first arrival until every enrolled patient has completed the assessment.

n_suspensions

Integer vector. Number of decisions at which accrual had to be suspended.

time_suspended

Numeric vector. Total time with accrual suspended.

boundary

The boin_boundary object used.

settings

List of the design parameters.

References

Yuan, Y., Lin, R., Li, D., Nie, L. and Warren, K. E. (2018). Time-to-Event Bayesian Optimal Interval Design to Accelerate Phase I Trials. Clinical Cancer Research, 24(20), 4921-4930.

Lin, R. and Yuan, Y. (2020). Time-to-Event Model-Assisted Designs for Dose-Finding Trials with Delayed Toxicity. Biostatistics, 21(4), 807-824.

See Also

tite_boin_decision_table, boin_simulate

Examples

# A three month window with two patients a month
trials <- tite_boin_simulate(
  target = 0.30,
  p_true = c(0.05, 0.15, 0.30, 0.45, 0.60),
  n_cohort = 10,
  cohort_size = 3,
  window = 3,
  accrual_rate = 2,
  n_trials = 200,
  seed = 123
)
trials

summary(trials$duration)


Simulate Trials of the TITE-Comb-BOIN12 Design

Description

Simulate trials of the TITE-Comb-BOIN12 design of Lu et al. (2025) for two drugs given together, in which the DLT and the response may be observed late: the rules of comb_boin12_simulate applied at the decision times and with the interim estimates of tite_boin12_simulate. Only the trial conduct is simulated; the OBD combination of each trial is selected by comb_boin12_select_obd (both are done by sim_tite_comb_boin12).

Usage

tite_comb_boin12_simulate(
  target,
  target_resp,
  p_true,
  p_resp,
  n_cohort,
  cohort_size,
  window,
  accrual_rate,
  resp_window = window,
  accrual = c("uniform", "exponential", "fixed"),
  event_time = c("weibull", "uniform"),
  late_fraction = 0.5,
  resp_late_fraction = 0.5,
  min_completed_share = 0.5,
  pending_estimate = c("conditional", "marginal"),
  pending_use = c("all", "utility"),
  n_trials = 10000,
  start_dose = c(1, 1),
  n_earlystop = NULL,
  n_earlystop_rule = c("with_stay", "simple"),
  p_saf = NULL,
  p_tox = NULL,
  cutoff_eli = 0.95,
  cutoff_eli_resp = 0.9,
  extrasafe = FALSE,
  offset = 0.05,
  psi00 = 40,
  psi11 = 60,
  benchmark_weight = 0.5,
  utility_prior = c(1, 1),
  n_star = 6,
  tie_break = c("higher", "random"),
  no_candidate = c("nearest", "stop"),
  resp_cor = 0,
  resp_cor_type = c("copula", "binary"),
  seed = 123
)

Arguments

target

Numeric scalar. Highest acceptable DLT probability, phi_T. It is the target of the BOIN boundaries lambda_e and lambda_d, of the admissibility of a combination and of the MTD combination that bounds the OBD combination.

target_resp

Numeric scalar. Lowest acceptable response probability, phi_E, as in sim_boin12.

p_true

Numeric matrix. True DLT probability of every combination, with one row per level of drug A and one column per level of drug B.

p_resp

Numeric matrix of the same size. True response probability of every combination.

n_cohort

Integer scalar. Number of cohorts in a trial.

cohort_size

Integer scalar or vector. Number of patients per cohort. A scalar is used for every cohort; a shorter vector is padded with its last element.

window

Numeric scalar. Length of the DLT assessment window.

accrual_rate

Numeric scalar. Average number of patients arriving per unit of time, in the same unit as window.

resp_window

Numeric scalar. Length of the response assessment window. Defaults to window.

accrual

Character scalar. Distribution of the times between arrivals: "uniform" (the default) on (0, 2 / accrual_rate), "exponential" for a Poisson process, or "fixed" for arrivals exactly 1 / accrual_rate apart.

event_time

Character scalar. Distribution of the times to DLT and to response: "weibull" (the default), with the share of the events in the second half of the window set by late_fraction and resp_late_fraction, or "uniform" over the window. With "weibull" the probabilities must be below 1.

late_fraction

Numeric scalar strictly between 0 and 1. Share of the DLTs that occur in the second half of the DLT window under the Weibull distribution. Defaults to 0.5.

resp_late_fraction

Numeric scalar strictly between 0 and 1. The same for the responses. Defaults to 0.5.

min_completed_share

Numeric scalar from 0 to 1. Share of the patients at the current dose who must have finished both assessments before the next decision; the decision, and the accrual, wait until then. Defaults to 0.5, the rule of Zhou et al. (2022), who suspend the accrual when more than half of the patients at the current dose have a pending outcome. With 1 every decision waits for all the outcomes, as in BOIN12.

pending_estimate

Character scalar. Value that replaces a pending outcome Y in the quasi-binomial likelihood: "conditional" (the default), the probability of the event given that it has not occurred during the time followed, pi_hat * (1 - w) / (1 - pi_hat * w), with w the fraction of the window followed, as in Equation (11) of Zhou et al. (2022); or "marginal", the estimate pi_hat itself, which reproduces the desirabilities of Table S.3 of their Supplement. See Details.

pending_use

Character scalar. Where the pending outcomes count: "all" (the default), in the estimated DLT rate of the decision, in the admissibility and in the utility, as in tite_boin12_simulate; "utility", only in the quasi-events of the utility, as Sections 2.2 and 3.1 of Lu et al. (2025) state the rules: the decision uses the observed DLT rate (DLTs over patients treated) and the admissibility the observed numbers of DLTs and responses, a pending outcome counting as no event.

n_trials

Integer scalar. Number of trials to simulate. Defaults to 10000.

start_dose

Integer vector of length 2. Levels of drug A and drug B of the first cohort. Defaults to c(1, 1).

n_earlystop

Integer scalar or NULL. Number of patients at the current combination that ends the trial when the next cohort would stay there (see n_earlystop_rule). Defaults to NULL, which runs every trial to the maximum sample size, as in Lu et al. (2025).

n_earlystop_rule

Character scalar. "with_stay" (the default) ends the trial at n_earlystop only when the next cohort would stay at the current combination; "simple" ends it in any case.

p_saf, p_tox

Numeric scalars or NULL. Highest DLT probability deemed subtherapeutic and lowest deemed overly toxic, which give the BOIN boundaries. Default to 0.6 * target and 1.4 * target.

cutoff_eli

Numeric scalar. A combination is inadmissible, together with every combination with at least the same levels of both drugs, when the posterior probability that its DLT rate exceeds target is at least this cutoff. Defaults to 0.95.

cutoff_eli_resp

Numeric scalar. A combination is inadmissible when the posterior probability that its response rate is below target_resp is at least this cutoff. Defaults to 0.90.

extrasafe

Logical scalar. Apply the cutoff cutoff_eli - offset to the lowest combination, as Lu et al. (2025) do with 0.85. Defaults to FALSE.

offset

Numeric scalar. Amount by which cutoff_eli is lowered at the lowest combination when extrasafe is TRUE. Defaults to 0.05, as in sim_comb_boin; Lu et al. (2025) use 0.10.

psi00, psi11

Numeric scalars from 0 to 100. Utility of a patient without DLT and without response, and with both, as in sim_boin12. Default to 40 and 60. The utility pE - wT * pT of Lu et al. (2025) is psi00 = 100 * wT / (1 + wT) and psi11 = 100 / (1 + wT); their wT = 0.11 is psi00 = 9.90991 and psi11 = 90.09009.

benchmark_weight

Numeric scalar above 0 and at most 1. Weight of the lowest acceptable utility in the utility benchmark, as in sim_boin12; it is the weight w_u of Lu et al. (2025), who use 0.6. Defaults to 0.5.

utility_prior

Numeric vector of two positive numbers. Beta prior of the utility of a combination divided by 100. Defaults to c(1, 1).

n_star

Integer scalar. With at least this many patients at the current combination and a DLT rate between lambda_e and lambda_d, the next combination is chosen from the current one and the two below it. Defaults to 6.

tie_break

Character scalar. Choice among the combinations of equal desirability: "higher" (the default) keeps those with the highest sum of the two levels and draws one of them at random when several remain; "random" draws one of all the tied combinations. See Details.

no_candidate

Character scalar. What happens when none of the combinations allowed for the next cohort is admissible: "nearest" (the default) goes to the admissible combination nearest to the current one; "stop" ends the trial without an OBD combination. See Details.

resp_cor

Numeric scalar between -1 and 1. Correlation between the DLT and the response of a patient, see resp_cor_type. Defaults to 0.

resp_cor_type

Character scalar. "copula" (the default) or "binary", as in sim_boin12.

seed

Integer scalar or NULL. Random seed. The state of the calling session is restored on exit. Defaults to 123.

Details

Patients arrive, are followed and are counted as in tite_boin12_simulate: the first patient of a cohort arrives at the time of the previous decision; the decision waits while fewer than a share min_completed_share of the patients at the current combination have finished both assessments; a pending outcome counts in the estimates of the DLT and response rates, in the admissibility and in the quasi-events of the desirability by the rules of Zhou et al. (2022). The decision follows the rules of comb_boin12_simulate, with the estimated DLT rate of the current combination, the admissibility computed from the interim posteriors (the DLT rule of a combination also excluding every combination with both levels at least its own, and extrasafe lowering the cutoff at the lowest combination) and the patients treated.

With pending_use = "utility" the decision uses the observed DLT rate of the current combination and the admissibility the posteriors Beta(1 + DLTs, 1 + patients treated - DLTs) and the same for the responses; only the desirability uses the pending outcomes.

With every outcome observed at every decision these are the quantities of Comb-BOIN12: with accrual = "fixed" and min_completed_share = 1 no variate is drawn for the times and the trials are exactly those of comb_boin12_simulate with the same seed. With one row or one column of combinations the trials are those of tite_boin12_simulate without exploration.

Lu et al. (2025) state the time-to-event rules of TITE-BOIN12 for TITE-Comb-BOIN12 without further detail; the accrual suspension and the estimates are those of tite_boin12_simulate, as in inst/reproduce/reproduce_Lu2025.R.

Value

An object of class comb_boin12_trials, as returned by comb_boin12_simulate, with design set to "TITE-Comb-BOIN12", the counts of the final outcomes of all patients, and one more component

duration

Numeric vector of the trial durations, in the unit of window: the time of the last decision of a trial stopped because no combination was admissible, and otherwise the time at which every patient has finished both assessments.

The timing arguments are added to settings.

References

Lu, M., Zhang, J., Yuan, Y. and Lin, R. (2025). Comb-BOIN12: A utility-based Bayesian optimal interval design for dose optimization in cancer drug-combination trials. Statistics in Biopharmaceutical Research, 17(2), 266-276. doi:10.1080/19466315.2024.2370403

Zhou, Y., Lin, R., Lee, J. J., Li, D., Wang, L., Li, R. and Yuan, Y. (2022). TITE-BOIN12: A Bayesian phase I/II trial design to find the optimal biological dose with late-onset toxicity and efficacy. Statistics in Medicine, 41(11), 1918-1931. doi:10.1002/sim.9337

See Also

sim_tite_comb_boin12, comb_boin12_simulate, tite_boin12_simulate

Examples

# Scenario 16 of Lu et al. (2025), with their utility (wT = 0.11), windows
# of 1 and 2 months and two patients a month
p_true <- matrix(c(0.05, 0.10, 0.15, 0.15, 0.20, 0.45), nrow = 2)
p_resp <- matrix(c(0.10, 0.20, 0.30, 0.40, 0.50, 0.60), nrow = 2)
trials <- tite_comb_boin12_simulate(
  target = 0.33, target_resp = 0.2, p_true = p_true, p_resp = p_resp,
  n_cohort = 14, cohort_size = 3, window = 1, resp_window = 2,
  accrual_rate = 2, event_time = "uniform", n_trials = 200,
  psi00 = 100 * 0.11 / 1.11, psi11 = 100 / 1.11, benchmark_weight = 0.6,
  extrasafe = TRUE, offset = 0.10, seed = 123
)
trials