| 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 |
| 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_lambdaEscalation and de-escalation interval boundaries.
boin_p_toxThe toxic threshold giving a required de-escalation boundary.
boin_boundaryInteger decision boundaries as a function of sample size.
boin_decision_tableDecision table indexed by DLTs and patients, with print and plot methods.
boin_stopping_tableSafety stopping boundary as a two-row table.
tite_boin_decision_tableDecision 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_boinOperating characteristics for one scenario.
sim_boin_multiOperating characteristics for several scenarios.
boin_simulateRaw trial data from the simulation engine.
boin_isotonicIsotonic estimates of the DLT probability.
boin_select_mtdMTD selection from completed trials.
sim_tite_boinOperating characteristics of the time-to-event BOIN design for one scenario, with trial duration and suspensions of accrual.
sim_tite_boin_multiThe same for several scenarios.
tite_boin_simulateRaw trial data from the time-to-event BOIN engine, with patients arriving over time and DLTs observed late.
Backfilling
sim_bf_boinOperating characteristics of the BOIN design with backfilling (BF-BOIN) for one scenario of DLT and response probabilities.
sim_bf_boin_multiThe same for several scenarios.
bf_boin_simulateRaw trial data from the BF-BOIN engine, with backfilled patients and responses.
sim_be_boinOperating characteristics of BE-BOIN, which combines backfilling with the time-to-event BOIN design, for one scenario.
sim_be_boin_multiThe same for several scenarios.
be_boin_simulateRaw trial data from the BE-BOIN engine.
Drug combinations
sim_comb_boinOperating characteristics of the BOIN drug-combination design of Lin and Yin (2017) for one matrix of DLT probabilities.
sim_comb_boin_multiThe same for several matrices.
comb_boin_simulateRaw trial data from the drug-combination engine.
comb_boin_select_mtdSelection of the MTD combination from completed trials.
comb_boin_nextThe combination for the next cohort of a trial in progress, with print and plot methods.
Optimal biological dose (BOIN-ET)
boin_et_boundaryBoundaries of the BOIN-ET design of Takeda, Taguri and Morita (2018), which decides from both the DLT and the response.
boin_et_decision_tableDecision table indexed by DLTs and responses, with a print method.
sim_boin_etOperating characteristics of BOIN-ET for one scenario of DLT and response probabilities, with the selection of the optimal biological dose (OBD).
sim_boin_et_multiThe same for several scenarios.
boin_et_simulateRaw trial data from the BOIN-ET engine.
boin_et_select_obdSelection of the OBD from completed trials, with the estimators and selection rules of the 'boinet' package.
sim_tite_boin_etOperating characteristics of the time-to-event TITE-BOIN-ET design of Takeda, Morita and Taguri (2020).
sim_tite_boin_et_multiThe same for several scenarios.
tite_boin_et_simulateRaw trial data from the TITE-BOIN-ET engine.
sim_bf_boin_etOperating characteristics of the backfill BF-BOIN-ET design of Takeda, Zhu and Hirakawa (2025).
sim_bf_boin_et_multiThe same for several scenarios.
Optimal biological dose (BOIN12 and TITE-BOIN12)
boin12_decision_tableDesirability scores of the BOIN12 design of Lin et al. (2020), indexed by patients, DLTs and responses.
sim_boin12Operating characteristics of BOIN12 for one scenario of DLT and response probabilities, with the selection of the OBD.
sim_boin12_multiThe same for several scenarios.
boin12_simulateRaw trial data from the BOIN12 engine.
boin12_select_obdOBD selection from completed trials.
sim_tite_boin12Operating characteristics of the time-to-event TITE-BOIN12 design of Zhou et al. (2022).
sim_tite_boin12_multiThe same for several scenarios.
tite_boin12_simulateRaw trial data from the TITE-BOIN12 engine.
The 3+3 design
oc_3p3Operating characteristics of the traditional 3+3 design, in closed form.
sim_3p3The same design by simulation, as a check on the closed form.
decision_table_3p3Decision table of the 3+3 design, with print and plot methods.
Tables and figures
oc_scenariosTrue scenarios with the utilities and the true MTDs and OBDs, with print and plot methods.
oc_resultsResults of several designs in one long table, with print and plot methods.
oc_compareSeveral designs judged against the true doses, with print and plot methods.
Author(s)
Maintainer: Gosuke Homma my.name.is.gosuke@gmail.com (ORCID)
Authors:
Gosuke Homma my.name.is.gosuke@gmail.com (ORCID)
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:
Report bugs at https://github.com/gosukehommaEX/simFastBOIN/issues
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 |
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 |
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
|
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 |
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: |
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:
|
no_slot |
Character scalar. What happens to a patient who arrives when neither the
dose escalation nor any backfill dose can take a patient: |
accrual |
Character scalar. Distribution of the times between arrivals:
|
dlt_time |
Character scalar. Distribution of the time to DLT within the window, and of
the time to response within the response window: |
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 |
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
|
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 |
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 |
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 |
p_tox |
Numeric scalar. Lowest DLT probability deemed overly toxic.
Defaults to |
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 |
offset |
Numeric scalar between 0 and 0.5. Amount by which |
n_earlystop_rule |
Character scalar, either |
seed |
Integer scalar or |
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 |
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
|
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 |
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: |
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:
|
no_slot |
Character scalar. What happens to a patient who arrives when neither the
dose escalation nor any backfill dose can take a patient: |
accrual |
Character scalar. Distribution of the times between arrivals:
|
dlt_time |
Character scalar. Distribution of the time to DLT within the window, and of
the time to response within the response window: |
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 |
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 |
p_tox |
Numeric scalar. Lowest DLT probability deemed overly toxic.
Defaults to |
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 |
offset |
Numeric scalar between 0 and 0.5. Amount by which |
stay_on_1_of_3 |
Logical scalar. When |
n_earlystop_rule |
Character scalar, either |
seed |
Integer scalar or |
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_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 |
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 |
boundary |
The |
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
|
target_resp |
Numeric scalar. Lowest acceptable response probability, phi_E. Note that
this is a lower limit, as in |
n |
Integer vector. Numbers of patients at a dose to tabulate. Defaults to
|
p_saf, p_tox |
Numeric scalars or |
cutoff_eli |
Numeric scalar. A dose is inadmissible, together with every higher dose,
when the posterior probability that its DLT rate exceeds |
cutoff_eli_resp |
Numeric scalar. A dose is inadmissible when the posterior probability
that its response rate is below |
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
|
utility_prior |
Numeric vector of two positive numbers. Beta prior of the utility of a
dose divided by 100. Defaults to |
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
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_tox_resp |
Counts of the patients with both a DLT and a response, of the same shape
as |
target |
Numeric scalar. Highest acceptable DLT probability, called phi_T by Lin
et al. (2020). It is the target of the BOIN boundaries
|
target_resp |
Numeric scalar. Lowest acceptable response probability, phi_E. Note that
this is a lower limit, as in |
cutoff_eli |
Numeric scalar. A dose is inadmissible, together with every higher dose,
when the posterior probability that its DLT rate exceeds |
cutoff_eli_resp |
Numeric scalar. A dose is inadmissible when the posterior probability
that its response rate is below |
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
|
utility_prior |
Numeric vector of two positive numbers. Beta prior of the utility of a
dose divided by 100. Defaults to |
est_method |
Character scalar. Estimate of the utility of a dose:
|
early_stop |
Logical vector or |
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, |
reason |
Character vector: |
utility |
Numeric matrix of the utility estimates (on the scale 0
to 100; for |
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
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
|
target_resp |
Numeric scalar. Lowest acceptable response probability, phi_E. Note that
this is a lower limit, as in |
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 |
n_earlystop_rule |
Character scalar. |
p_saf, p_tox |
Numeric scalars or |
cutoff_eli |
Numeric scalar. A dose is inadmissible, together with every higher dose,
when the posterior probability that its DLT rate exceeds |
cutoff_eli_resp |
Numeric scalar. A dose is inadmissible when the posterior probability
that its response rate is below |
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
|
utility_prior |
Numeric vector of two positive numbers. Beta prior of the utility of a
dose divided by 100. Defaults to |
n_star |
Integer scalar. With at least this many patients at the current dose and
a DLT rate between |
n_explore |
Integer scalar. With at least this many patients at the current dose, a
DLT rate below |
tie_break |
Character scalar. Choice among the doses of equal desirability:
|
no_candidate |
Character scalar. What happens when none of the doses allowed for the
next cohort is admissible: |
explore_from |
Character scalar. Doses from which the exploration rule (see
|
resp_cor |
Numeric scalar between -1 and 1. Correlation between the DLT and the
response of a patient, see |
resp_cor_type |
Character scalar. |
seed |
Integer scalar or |
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: |
early_stop |
Logical vector, |
design |
|
boundary |
List with |
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
|
p_saf |
Numeric scalar. Highest DLT probability deemed subtherapeutic.
Defaults to |
p_tox |
Numeric scalar. Lowest DLT probability deemed overly toxic.
Defaults to |
cutoff_eli |
Numeric scalar. Posterior probability cutoff above which a dose is eliminated for toxicity. Defaults to 0.95. |
extrasafe |
Logical scalar. When |
offset |
Numeric scalar between 0 and 0.5. Amount by which |
stay_on_1_of_3 |
Logical scalar. When |
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 |
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,
|
b_stop |
Safety stopping boundary at the lowest dose, all |
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 |
p_tox |
Numeric scalar. Lowest DLT probability deemed overly toxic.
Defaults to |
cutoff_eli |
Numeric scalar. Posterior probability cutoff for dose elimination. Defaults to 0.95. |
stay_on_1_of_3 |
Logical scalar. When |
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 |
p_tox |
Numeric scalar. Lowest DLT probability deemed overly toxic. Defaults to
|
p_saf_resp |
Numeric scalar. Highest response probability deemed subtherapeutic.
Defaults to |
prior |
Numeric vector of length 6. Prior probabilities of the six hypotheses.
Defaults to |
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 |
lambda2 |
Upper DLT boundary. The dose is de-escalated when the
observed DLT rate is at least |
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 |
p_saf |
Numeric scalar. Highest DLT probability deemed subtherapeutic. Defaults
to |
p_tox |
Numeric scalar. Lowest DLT probability deemed overly toxic. Defaults to
|
p_saf_resp |
Numeric scalar. Highest response probability deemed subtherapeutic.
Defaults to |
cutoff_eli |
Numeric scalar. A dose is no longer admissible when the posterior
probability that its DLT rate is below |
cutoff_eli_resp |
Numeric scalar. A dose is no longer admissible when the posterior
probability that its response rate is above |
p_eli |
Numeric scalar or |
p_eli_resp |
Numeric scalar or |
prior |
Numeric vector of length 6. Prior probabilities of the six hypotheses.
Defaults to |
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 |
|
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_resp |
Response counts of the same shape as |
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 |
p_tox |
Numeric scalar. Lowest DLT probability deemed overly toxic. Defaults to
|
p_saf_resp |
Numeric scalar. Highest response probability deemed subtherapeutic.
Defaults to |
cutoff_eli |
Numeric scalar. A dose is no longer admissible when the posterior
probability that its DLT rate is below |
cutoff_eli_resp |
Numeric scalar. A dose is no longer admissible when the posterior
probability that its response rate is above |
p_eli |
Numeric scalar or |
p_eli_resp |
Numeric scalar or |
est_method |
Character scalar. Estimator of the response rates: |
obd_method |
Character scalar. Selection rule: |
w1, w2 |
Numeric scalars. Weights of the weighted utility
|
t_low, t_upp |
Numeric scalars or |
e_low, e_upp |
Numeric scalars or |
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 |
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 |
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, |
reason |
Character vector: |
probe |
Numeric matrix of the response estimates, |
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
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 |
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_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 |
p_saf |
Numeric scalar. Highest DLT probability deemed subtherapeutic. Defaults
to |
p_tox |
Numeric scalar. Lowest DLT probability deemed overly toxic. Defaults to
|
p_saf_resp |
Numeric scalar. Highest response probability deemed subtherapeutic.
Defaults to |
cutoff_eli |
Numeric scalar. A dose is no longer admissible when the posterior
probability that its DLT rate is below |
cutoff_eli_resp |
Numeric scalar. A dose is no longer admissible when the posterior
probability that its response rate is above |
p_eli |
Numeric scalar or |
p_eli_resp |
Numeric scalar or |
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 |
boinet_compatible |
Logical scalar. Apply the rules of the 'boinet' package (version 1.6.0)
exactly. Defaults to |
prior |
Numeric vector of length 6. Prior probabilities of the six hypotheses.
Defaults to |
seed |
Integer scalar or |
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_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, |
design |
|
boundary |
The |
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 |
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 |
odc_tie |
Character scalar. How tied candidates are reported: |
cutoff_eli, p_eli |
As in |
excluded |
Logical array or matrix of the same size, or |
early_stop |
Logical vector or |
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 ( |
n_tied |
Integer vector, the number of tied candidates. |
tied |
Logical array, the tied candidates of every trial (with
|
mtd_col |
Integer matrix, trial by level of drug A, the level of drug B of the MTDC of every row. |
reason |
Character vector: |
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
|
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 |
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: |
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
|
rule4 |
Character scalar. Choice among the neighboring combinations when the DLT
rate is between |
p_saf, p_tox, p_saf_resp, prior |
Design parameters of the BOIN-ET boundaries, as in
|
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 |
Numeric scalar or |
resp_cor |
Numeric scalar between -1 and 1. Correlation between the DLT and the
response of a patient, see |
resp_cor_type |
Character scalar. |
seed |
Integer scalar or |
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 isAlB1, the rows start at rowl - 1(at row 1 whenlis 1) and the rows above are skipped."etc2"starts every row at its lowest combination."etc1"starts the row below the candidateAlBmof the previous subtrial at levelm - 1of drug B (etc1_start = "diagonal") or at levelm("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: columnj + 1of drug B from level 1 of drug A up to levelL - j, then rowL - jfrom columnj + 2toM, each started at its lowest combination. WithL > Mthe shapes run out of columns afterM - 1of 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 text of Section 2.2 describes BOIN-ETC2 with the L-shaped subtrials and BOIN-ETC3 with the rows started at their lowest combination. Their Figure 2 and Supplementary Figures S1 and S2, their tables and their code have it the other way round, and so has this function.
The text and the figures start a row of BOIN-ETC1 one level of drug B below the previous candidate (
"diagonal"); the code that produced the tables starts it at the same level ("below"), and only that rule reproduces the published allocation.In rule 4, the code of the authors drops the response rate of an untreated combination below the current one but not the combination, so that the choice moves one combination down (from the current combination to the untreated one, or from the one above to the current one); it also breaks a tie among the first eligible combinations rather than among the tied ones.
rule4 = "authors_code"applies these rules. An untreated combination below the current one only happens in BOIN-ETC1, and its published allocation is reproduced only with these rules.The code excludes only the current combination and may treat an excluded lowest combination again; here the text is followed (the published results do not depend on the difference). The text does not say what happens when
A1B1is excluded.
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, |
cohorts_used, n_subtrials |
Integer vectors of the cohorts enrolled and of the subtrials run. |
stop_reason |
Character vector: |
early_stop |
Logical vector, |
design |
|
boundary |
List with |
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 |
admissible |
Logical matrix of the same shape as |
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
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 |
p_tox |
Numeric scalar. Lowest DLT probability deemed overly toxic, so that dose
de-escalation is required. Defaults to |
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
|
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
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 |
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 |
offset |
Numeric scalar between 0 and 0.5. Amount by which |
bound_mtd |
Logical scalar. Require the isotonic estimate at the selected dose to be at
or below the de-escalation boundary. Defaults to |
p_tox |
Numeric scalar. Lowest DLT probability deemed overly toxic, used to derive
the de-escalation boundary when |
mtd_max_estimate |
Numeric scalar or |
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 |
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
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_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 |
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 |
p_tox |
Numeric scalar. Lowest DLT probability deemed overly toxic.
Defaults to |
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 |
offset |
Numeric scalar between 0 and 0.5. Amount by which |
titration |
Logical scalar. Start with single patient cohorts until the first DLT is
seen. Ignored when the first cohort size is one. Defaults to |
stay_on_1_of_3 |
Logical scalar. When |
n_earlystop_rule |
Character scalar, either |
seed |
Integer scalar or |
titration_doses |
Integer scalar or |
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_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 |
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
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 |
cohort_size |
Integer scalar or |
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
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 |
psi00, psi11 |
Numeric scalars from 0 to 100. Utilities of a patient with neither a
DLT nor a response and with both, as in |
est_method |
Character scalar. Estimate of the response probability:
|
obd_bound |
Character scalar. Combinations from which the OBDC is chosen:
|
dose_a, dose_b |
Numeric vectors or |
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 |
n_draws |
Integer scalar. Number of points of the importance sampling of the logistic model. Defaults to 4000. |
early_stop |
Logical vector or |
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 ( |
mtd_a, mtd_b |
Integer vectors, the levels of the MTDC. |
reason |
Character vector: |
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 ( |
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 |
target_resp |
Numeric scalar. Lowest acceptable response probability, phi_E, as in
|
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 |
n_earlystop |
Integer scalar or |
n_earlystop_rule |
Character scalar. |
p_saf, p_tox |
Numeric scalars or |
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 |
cutoff_eli_resp |
Numeric scalar. A combination is inadmissible when the posterior
probability that its response rate is below |
extrasafe |
Logical scalar. Apply the cutoff |
offset |
Numeric scalar. Amount by which |
psi00, psi11 |
Numeric scalars from 0 to 100. Utility of a patient without DLT and
without response, and with both, as in |
benchmark_weight |
Numeric scalar above 0 and at most 1. Weight of the lowest acceptable
utility in the utility benchmark, as in |
utility_prior |
Numeric vector of two positive numbers. Beta prior of the utility of a
combination divided by 100. Defaults to |
n_star |
Integer scalar. With at least this many patients at the current
combination and a DLT rate between |
tie_break |
Character scalar. Choice among the combinations of equal desirability:
|
no_candidate |
Character scalar. What happens when none of the combinations allowed
for the next cohort is admissible: |
resp_cor |
Numeric scalar between -1 and 1. Correlation between the DLT and the
response of a patient, see |
resp_cor_type |
Character scalar. |
seed |
Integer scalar or |
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: |
early_stop |
Logical vector, |
design |
|
boundary |
List with |
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 |
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 |
p_tox |
Numeric scalar. Lowest DLT probability deemed overly toxic.
Defaults to |
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 |
offset |
Numeric scalar between 0 and 0.5. Amount by which |
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 |
next_dose |
Integer matrix with columns |
tie |
Whether two candidates tie, in which case the design picks one of them at random. |
stop_reason |
|
note |
A sentence explaining a decision to stay when the rule called for a move that is not available, otherwise |
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 |
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
|
n_tox |
Integer matrix or array of the same shape as |
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 |
offset |
Numeric scalar between 0 and 0.5. Amount by which |
bound_mtd |
Logical scalar. Require the isotonic estimate at the selected combination
to be below the de-escalation boundary. Defaults to |
p_tox |
Numeric scalar. Lowest DLT probability deemed overly toxic, used to derive
the de-escalation boundary when |
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 |
mtd_b |
Dose level of drug B in the selected combination, or |
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_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 |
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 |
p_tox |
Numeric scalar. Lowest DLT probability deemed overly toxic.
Defaults to |
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 |
offset |
Numeric scalar between 0 and 0.5. Amount by which |
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 |
seed |
Integer scalar or |
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 |
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 |
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 |
|
n |
Number of patients treated at the current dose, 3 or 6. |
n_tox |
Number of patients with a DLT, from 0 to |
decision |
Decision code. During escalation, |
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 |
start_dose |
Integer scalar. Dose level for the first cohort. Defaults to 1. |
overdose_cutoff |
Numeric scalar or |
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 |
together with p_true, n_doses, mtd_rule,
start_dose, method and the call.
See Also
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 |
truth |
The result of |
overdose_cutoff |
Numeric scalar or |
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 |
pct_correct |
Percentage of trials selecting a true MTD or OBD;
|
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, |
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
|
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 |
|
scenario |
Factor of the scenario names. A single-scenario result is named "Scenario 1". |
dose |
Dose level, or |
metric |
Factor: per dose, |
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 |
target |
Numeric scalar. Target DLT probability; the true MTD is the dose whose DLT probability is closest to it. |
target_resp |
Numeric scalar or |
tox_limit |
Numeric scalar. Highest acceptable DLT probability; a dose with a higher
DLT probability cannot be the true OBD. Defaults to |
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
|
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 |
true_mtd, true_obd |
|
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 |
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 |
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 |
... |
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 |
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 |
... |
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
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 |
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 |
... |
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 |
metrics |
Character vector. Columns of |
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
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 |
metric |
Character scalar. The per-dose quantity: |
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
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 |
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 |
n |
Integer vector or |
cohort_size |
Integer scalar or |
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 |
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 |
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
|
kable |
Logical scalar. Print only the table, formatted by |
kable_format |
Character scalar passed to |
... |
Further arguments, currently ignored. |
Value
The object x, invisibly.
See Also
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 |
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 |
kable |
Logical scalar. Print only the table, formatted by |
kable_format |
Character scalar passed to |
... |
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 |
... |
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 |
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 |
kable |
Logical scalar. Print the table with |
kable_format |
Character scalar. Format passed to |
... |
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 |
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 |
kable |
Logical scalar. Print the table with |
kable_format |
Character scalar. Format passed to |
... |
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 |
desirability |
Logical scalar. Show the posterior probabilities as well. Defaults to
|
... |
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 |
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
|
kable |
Logical scalar. Print the table with |
kable_format |
Character scalar. Format passed to |
... |
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 |
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
|
kable |
Logical scalar. Print the table with |
kable_format |
Character scalar. Format passed to |
... |
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 |
... |
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 |
cohort_size |
Integer scalar or |
... |
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 |
cohort_size |
Integer scalar or |
... |
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 |
... |
Further arguments, currently ignored. |
Value
The object x, invisibly.
See Also
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 |
... |
Further arguments, currently ignored. |
Value
The object x, invisibly.
See Also
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 |
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
|
kable |
Logical scalar. Print the table with |
kable_format |
Character scalar. Format passed to |
... |
Further arguments, currently ignored. |
Value
The object x, invisibly.
See Also
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 |
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
|
kable |
Logical scalar. Print the table with |
kable_format |
Character scalar. Format passed to |
... |
Further arguments, currently ignored. |
Value
The object x, invisibly.
See Also
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 |
... |
Further arguments, currently ignored. |
Value
The object x, invisibly.
See Also
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 |
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
|
kable |
Logical scalar. Print the table with |
kable_format |
Character scalar. Format passed to
|
... |
Not used. |
Value
x, invisibly.
See Also
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 |
digits |
Integer scalar. Decimal places. Defaults to 1. |
kable |
Logical scalar. Print the table with |
kable_format |
Character scalar. Format passed to
|
... |
Not used. |
Value
x, invisibly.
See Also
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 |
... |
Not used. |
Value
x, invisibly.
See Also
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 |
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
|
kable |
Logical scalar. Return the table through |
kable_format |
Character scalar passed to |
... |
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 |
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
|
kable |
Logical scalar. Return the table through |
kable_format |
Character scalar passed to |
... |
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 |
... |
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 |
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
|
kable |
Logical scalar. Print the table with |
kable_format |
Character scalar. Format passed to
|
... |
Not used. |
Value
x, invisibly.
See Also
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 |
digits |
Integer scalar. Decimal places. Defaults to 1. |
kable |
Logical scalar. Print the table with |
kable_format |
Character scalar. Format passed to
|
... |
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
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 |
... |
Not used. |
Value
x, invisibly.
See Also
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 |
... |
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 |
digits |
Integer scalar. Number of decimal places. Defaults to 1. |
kable |
Logical scalar. Return the table through |
kable_format |
Character scalar passed to |
... |
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 |
digits |
Integer scalar. Number of decimal places. Defaults to 1. |
kable |
Logical scalar. Return the table through |
kable_format |
Character scalar passed to |
... |
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 |
... |
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 |
... |
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 |
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
|
kable |
Logical scalar. Return the table through |
kable_format |
Character scalar passed to |
... |
Further arguments, currently ignored. |
Value
The object x, invisibly.
See Also
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 |
digits |
Integer scalar. Number of decimals. Defaults to 1. |
... |
Further arguments, currently ignored. |
Value
x, invisibly.
See Also
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 |
metric |
Character vector. Per-dose quantities to print, among
|
digits |
Integer scalar. Number of decimals. Defaults to 1. |
... |
Further arguments, currently ignored. |
Value
x, invisibly.
See Also
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 |
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 |
cohort_size |
Integer scalar or |
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 |
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
|
kable |
Logical scalar. Return the table through |
kable_format |
Character scalar passed to |
... |
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 |
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
|
kable |
Logical scalar. Return the table through |
kable_format |
Character scalar passed to |
... |
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 |
... |
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_lambdafor the interval boundaries, orboin_boundaryfor the integer decision boundaries.get_boin_decision()use
boin_decision_table.get_boin_stopping_boundaries()use
boin_boundarywithextrasafe = TRUEand read theb_stopcomponent.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 |
start_dose |
Integer scalar. Dose level for the first cohort. Defaults to 1. |
overdose_cutoff |
Numeric scalar or |
seed |
Integer scalar or |
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
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 |
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
|
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 |
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: |
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:
|
no_slot |
Character scalar. What happens to a patient who arrives when neither the
dose escalation nor any backfill dose can take a patient: |
accrual |
Character scalar. Distribution of the times between arrivals:
|
dlt_time |
Character scalar. Distribution of the time to DLT within the window, and of
the time to response within the response window: |
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 |
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
|
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 |
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 |
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 |
p_tox |
Numeric scalar. Lowest DLT probability deemed overly toxic.
Defaults to |
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 |
offset |
Numeric scalar between 0 and 0.5. Amount by which |
bound_mtd |
Logical scalar. Require the isotonic estimate at the selected dose to be at
or below the de-escalation boundary. Defaults to |
mtd_max_estimate |
Numeric scalar or |
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 |
n_earlystop_rule |
Character scalar, either |
keep_trials |
Logical scalar. Keep the full trial by trial data in the result.
Defaults to |
verbose |
Logical scalar. Report progress while the simulation runs.
Defaults to |
seed |
Integer scalar or |
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 |
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
|
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 |
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: |
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:
|
no_slot |
Character scalar. What happens to a patient who arrives when neither the
dose escalation nor any backfill dose can take a patient: |
accrual |
Character scalar. Distribution of the times between arrivals:
|
dlt_time |
Character scalar. Distribution of the time to DLT within the window, and of
the time to response within the response window: |
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 |
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
|
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 |
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 |
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 |
p_tox |
Numeric scalar. Lowest DLT probability deemed overly toxic.
Defaults to |
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 |
offset |
Numeric scalar between 0 and 0.5. Amount by which |
bound_mtd |
Logical scalar. Require the isotonic estimate at the selected dose to be at
or below the de-escalation boundary. Defaults to |
mtd_max_estimate |
Numeric scalar or |
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 |
n_earlystop_rule |
Character scalar, either |
keep_trials |
Logical scalar. Keep the full trial by trial data in the result.
Defaults to |
verbose |
Logical scalar. Report progress while the simulation runs.
Defaults to |
seed |
Integer scalar or |
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 |
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
|
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 |
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: |
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:
|
no_slot |
Character scalar. What happens to a patient who arrives when neither the
dose escalation nor any backfill dose can take a patient: |
accrual |
Character scalar. Distribution of the times between arrivals:
|
dlt_time |
Character scalar. Distribution of the time to DLT within the window, and of
the time to response within the response window: |
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 |
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 |
p_tox |
Numeric scalar. Lowest DLT probability deemed overly toxic.
Defaults to |
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 |
offset |
Numeric scalar between 0 and 0.5. Amount by which |
stay_on_1_of_3 |
Logical scalar. When |
bound_mtd |
Logical scalar. Require the isotonic estimate at the selected dose to be at
or below the de-escalation boundary. Defaults to |
mtd_max_estimate |
Numeric scalar or |
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 |
n_earlystop_rule |
Character scalar, either |
keep_trials |
Logical scalar. Keep the full trial by trial data in the result.
Defaults to |
verbose |
Logical scalar. Report progress while the simulation runs.
Defaults to |
seed |
Integer scalar or |
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 |
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 |
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 |
p_true |
Numeric vector. True DLT probability at each dose level, in increasing dose order. |
p_resp |
Numeric vector of the same length as |
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 |
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 |
resp_window |
Numeric scalar. Length of the response assessment window. Defaults to
|
accrual |
Character scalar. Distribution of the times between arrivals:
|
event_time |
Character scalar. Distribution of the times to DLT and to response:
|
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 |
p_tox |
Numeric scalar or |
p_saf_resp |
Numeric scalar or |
cutoff_eli |
Numeric scalar. A dose with |
cutoff_eli_resp |
Numeric scalar. Such a dose is excluded alone when the posterior
probability that its response rate is below |
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, 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 |
backfill_extension |
Numeric scalar. Time, in the unit of |
keep_trials |
Logical scalar. Keep the simulated trials and the selected OBDs in the
result. Defaults to |
verbose |
Logical scalar. Report progress with messages. Defaults to |
seed |
Integer scalar or |
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 |
|
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 |
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 |
scenarios |
List of scenarios. Each element is a list with the components
|
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 |
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 |
resp_window |
Numeric scalar. Length of the response assessment window. Defaults to
|
accrual |
Character scalar. Distribution of the times between arrivals:
|
event_time |
Character scalar. Distribution of the times to DLT and to response:
|
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 |
p_tox |
Numeric scalar or |
p_saf_resp |
Numeric scalar or |
cutoff_eli |
Numeric scalar. A dose with |
cutoff_eli_resp |
Numeric scalar. Such a dose is excluded alone when the posterior
probability that its response rate is below |
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, 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 |
backfill_extension |
Numeric scalar. Time, in the unit of |
keep_trials |
Logical scalar. Keep the simulated trials and the selected OBDs in the
result. Defaults to |
verbose |
Logical scalar. Report progress with messages. Defaults to |
seed |
Integer scalar or |
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 |
summary_table |
Data frame with seven rows per scenario, as shown
by |
scenario_names |
Character vector of scenario names. |
n_doses |
Number of doses. |
call |
The matched call. |
See Also
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 |
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
|
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 |
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: |
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:
|
no_slot |
Character scalar. What happens to a patient who arrives when neither the
dose escalation nor any backfill dose can take a patient: |
accrual |
Character scalar. Distribution of the times between arrivals:
|
dlt_time |
Character scalar. Distribution of the time to DLT within the window, and of
the time to response within the response window: |
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 |
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 |
p_tox |
Numeric scalar. Lowest DLT probability deemed overly toxic.
Defaults to |
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 |
offset |
Numeric scalar between 0 and 0.5. Amount by which |
stay_on_1_of_3 |
Logical scalar. When |
bound_mtd |
Logical scalar. Require the isotonic estimate at the selected dose to be at
or below the de-escalation boundary. Defaults to |
mtd_max_estimate |
Numeric scalar or |
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 |
n_earlystop_rule |
Character scalar, either |
keep_trials |
Logical scalar. Keep the trial by trial data of every scenario.
Defaults to |
verbose |
Logical scalar. Report progress while the simulations run.
Defaults to |
seed |
Integer scalar or |
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 |
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_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 |
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 |
p_tox |
Numeric scalar. Lowest DLT probability deemed overly toxic.
Defaults to |
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 |
offset |
Numeric scalar between 0 and 0.5. Amount by which |
titration |
Logical scalar. Start with single patient cohorts until the first DLT is
seen. Ignored when the first cohort size is one. Defaults to |
stay_on_1_of_3 |
Logical scalar. When |
bound_mtd |
Logical scalar. Require the isotonic estimate at the selected dose to be at
or below the de-escalation boundary. Defaults to |
mtd_max_estimate |
Numeric scalar or |
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 |
n_earlystop_rule |
Character scalar, either |
keep_trials |
Logical scalar. Keep the full trial by trial data in the result.
Defaults to |
verbose |
Logical scalar. Report progress while the simulation runs.
Defaults to |
seed |
Integer scalar or |
titration_doses |
Integer scalar or |
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 |
stop_reason_percent |
Percentage of trials by reason for stopping. |
trials |
Trial level data when |
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
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
|
target_resp |
Numeric scalar. Lowest acceptable response probability, phi_E. Note that
this is a lower limit, as in |
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 |
n_earlystop_rule |
Character scalar. |
p_saf, p_tox |
Numeric scalars or |
cutoff_eli |
Numeric scalar. A dose is inadmissible, together with every higher dose,
when the posterior probability that its DLT rate exceeds |
cutoff_eli_resp |
Numeric scalar. A dose is inadmissible when the posterior probability
that its response rate is below |
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
|
utility_prior |
Numeric vector of two positive numbers. Beta prior of the utility of a
dose divided by 100. Defaults to |
n_star |
Integer scalar. With at least this many patients at the current dose and
a DLT rate between |
n_explore |
Integer scalar. With at least this many patients at the current dose, a
DLT rate below |
tie_break |
Character scalar. Choice among the doses of equal desirability:
|
no_candidate |
Character scalar. What happens when none of the doses allowed for the
next cohort is admissible: |
explore_from |
Character scalar. Doses from which the exploration rule (see
|
resp_cor |
Numeric scalar between -1 and 1. Correlation between the DLT and the
response of a patient, see |
resp_cor_type |
Character scalar. |
est_method |
Character scalar. Estimate of the utility of a dose:
|
keep_trials |
Logical scalar. Keep the simulated trials and the selected OBDs in the
result. Defaults to |
verbose |
Logical scalar. Report progress with messages. Defaults to |
seed |
Integer scalar or |
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 |
|
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 |
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 |
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
|
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
|
target_resp |
Numeric scalar. Lowest acceptable response probability, phi_E. Note that
this is a lower limit, as in |
scenarios |
List of scenarios. Each element is a list with the components
|
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 |
n_earlystop_rule |
Character scalar. |
p_saf, p_tox |
Numeric scalars or |
cutoff_eli |
Numeric scalar. A dose is inadmissible, together with every higher dose,
when the posterior probability that its DLT rate exceeds |
cutoff_eli_resp |
Numeric scalar. A dose is inadmissible when the posterior probability
that its response rate is below |
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
|
utility_prior |
Numeric vector of two positive numbers. Beta prior of the utility of a
dose divided by 100. Defaults to |
n_star |
Integer scalar. With at least this many patients at the current dose and
a DLT rate between |
n_explore |
Integer scalar. With at least this many patients at the current dose, a
DLT rate below |
tie_break |
Character scalar. Choice among the doses of equal desirability:
|
no_candidate |
Character scalar. What happens when none of the doses allowed for the
next cohort is admissible: |
explore_from |
Character scalar. Doses from which the exploration rule (see
|
resp_cor |
Numeric scalar between -1 and 1. Correlation between the DLT and the
response of a patient, see |
resp_cor_type |
Character scalar. |
est_method |
Character scalar. Estimate of the utility of a dose:
|
keep_trials |
Logical scalar. Keep the simulated trials and the selected OBDs in the
result. Defaults to |
verbose |
Logical scalar. Report progress with messages. Defaults to |
seed |
Integer scalar or |
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 |
summary_table |
Data frame with six rows per scenario, as shown by
|
scenario_names |
Character vector of scenario names. |
n_doses |
Number of doses. |
call |
The matched call. |
See Also
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 |
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_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 |
p_saf |
Numeric scalar. Highest DLT probability deemed subtherapeutic. Defaults
to |
p_tox |
Numeric scalar. Lowest DLT probability deemed overly toxic. Defaults to
|
p_saf_resp |
Numeric scalar. Highest response probability deemed subtherapeutic.
Defaults to |
cutoff_eli |
Numeric scalar. A dose is no longer admissible when the posterior
probability that its DLT rate is below |
cutoff_eli_resp |
Numeric scalar. A dose is no longer admissible when the posterior
probability that its response rate is above |
p_eli |
Numeric scalar or |
p_eli_resp |
Numeric scalar or |
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 |
boinet_compatible |
Logical scalar. Apply the rules of the 'boinet' package (version 1.6.0)
exactly. Defaults to |
prior |
Numeric vector of length 6. Prior probabilities of the six hypotheses.
Defaults to |
est_method |
Character scalar. Estimator of the response rates: |
obd_method |
Character scalar. Selection rule: |
w1, w2 |
Numeric scalars. Weights of the weighted utility
|
t_low, t_upp |
Numeric scalars or |
e_low, e_upp |
Numeric scalars or |
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 |
verbose |
Logical scalar. Report progress with messages. Defaults to |
seed |
Integer scalar or |
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 |
|
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
|
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
|
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
|
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
|
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_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 |
p_saf |
Numeric scalar. Highest DLT probability deemed subtherapeutic. Defaults
to |
p_tox |
Numeric scalar. Lowest DLT probability deemed overly toxic. Defaults to
|
p_saf_resp |
Numeric scalar. Highest response probability deemed subtherapeutic.
Defaults to |
cutoff_eli |
Numeric scalar. A dose is no longer admissible when the posterior
probability that its DLT rate is below |
cutoff_eli_resp |
Numeric scalar. A dose is no longer admissible when the posterior
probability that its response rate is above |
p_eli |
Numeric scalar or |
p_eli_resp |
Numeric scalar or |
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 |
boinet_compatible |
Logical scalar. Apply the rules of the 'boinet' package (version 1.6.0)
exactly. Defaults to |
prior |
Numeric vector of length 6. Prior probabilities of the six hypotheses.
Defaults to |
est_method |
Character scalar. Estimator of the response rates: |
obd_method |
Character scalar. Selection rule: |
w1, w2 |
Numeric scalars. Weights of the weighted utility
|
t_low, t_upp |
Numeric scalars or |
e_low, e_upp |
Numeric scalars or |
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 |
verbose |
Logical scalar. Report progress with messages. Defaults to |
seed |
Integer scalar or |
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 |
summary_table |
Data frame with six rows per scenario, as shown by
|
scenario_names |
Character vector of scenario names. |
n_doses |
Number of doses. |
call |
The matched call. |
See Also
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
|
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 |
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: |
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
|
rule4 |
Character scalar. Choice among the neighboring combinations when the DLT
rate is between |
p_saf, p_tox, p_saf_resp, prior |
Design parameters of the BOIN-ET boundaries, as in
|
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 |
Numeric scalar or |
resp_cor |
Numeric scalar between -1 and 1. Correlation between the DLT and the
response of a patient, see |
resp_cor_type |
Character scalar. |
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 |
odc_tie |
Character scalar. |
keep_trials |
Logical scalar. Keep the simulated trials ( |
verbose |
Logical scalar. Print progress messages. Defaults to |
seed |
Integer scalar or |
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 |
|
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 |
pct_true_obd_selected, pct_patients_true_obd |
Percentage of
trials selecting a true optimal combination (with
|
overdose |
List with the |
stop_reason_percent |
Percentage of trials by stopping reason. |
odc_tie, settings, call |
The settings used. |
trials, obd, tied |
With |
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
|
scenarios |
List of scenarios. Each element is a list with the matrices
|
n_cohort |
Integer scalar. Number of cohorts in a trial; with |
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: |
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
|
rule4 |
Character scalar. Choice among the neighboring combinations when the DLT
rate is between |
p_saf, p_tox, p_saf_resp, prior |
Design parameters of the BOIN-ET boundaries, as in
|
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 |
Numeric scalar or |
resp_cor |
Numeric scalar between -1 and 1. Correlation between the DLT and the
response of a patient, see |
resp_cor_type |
Character scalar. |
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 |
odc_tie |
Character scalar. |
keep_trials |
Logical scalar. Keep the simulated trials ( |
verbose |
Logical scalar. Print progress messages. Defaults to |
seed |
Integer scalar or |
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 |
summary_table |
Data frame with one row per scenario, as shown by
|
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 |
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 |
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 |
p_tox |
Numeric scalar. Lowest DLT probability deemed overly toxic.
Defaults to |
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 |
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 |
bound_mtd |
Logical scalar. Bound the isotonic estimate at the selected MTD by the de-escalation boundary. |
mtd_max_estimate |
Numeric scalar or |
min_mtd_sample |
Integer scalar. Smallest number of patients for a dose to be eligible. |
overdose_cutoff |
Numeric scalar or |
n_earlystop_rule |
Character scalar, either |
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 |
titration_doses |
Integer scalar or |
Value
An object of class boin_oc_multi, which is a list with components
results |
Named list of |
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
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_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 |
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 |
p_tox |
Numeric scalar. Lowest DLT probability deemed overly toxic.
Defaults to |
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 |
offset |
Numeric scalar between 0 and 0.5. Amount by which |
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 |
bound_mtd |
Logical scalar. Require the isotonic estimate at the selected combination
to be below the de-escalation boundary. Defaults to |
overdose_cutoff |
Numeric scalar or |
keep_trials |
Logical scalar. Keep the full trial by trial data in the result.
Defaults to |
verbose |
Logical scalar. Report progress while the simulation runs.
Defaults to |
seed |
Integer scalar or |
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 |
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 |
stop_reason_percent |
Percentage of trials by reason for stopping. |
trials |
Trial level data when |
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 |
target_resp |
Numeric scalar. Lowest acceptable response probability, phi_E, as in
|
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 |
n_earlystop |
Integer scalar or |
n_earlystop_rule |
Character scalar. |
p_saf, p_tox |
Numeric scalars or |
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 |
cutoff_eli_resp |
Numeric scalar. A combination is inadmissible when the posterior
probability that its response rate is below |
extrasafe |
Logical scalar. Apply the cutoff |
offset |
Numeric scalar. Amount by which |
psi00, psi11 |
Numeric scalars from 0 to 100. Utility of a patient without DLT and
without response, and with both, as in |
benchmark_weight |
Numeric scalar above 0 and at most 1. Weight of the lowest acceptable
utility in the utility benchmark, as in |
utility_prior |
Numeric vector of two positive numbers. Beta prior of the utility of a
combination divided by 100. Defaults to |
n_star |
Integer scalar. With at least this many patients at the current
combination and a DLT rate between |
tie_break |
Character scalar. Choice among the combinations of equal desirability:
|
no_candidate |
Character scalar. What happens when none of the combinations allowed
for the next cohort is admissible: |
resp_cor |
Numeric scalar between -1 and 1. Correlation between the DLT and the
response of a patient, see |
resp_cor_type |
Character scalar. |
est_method |
Character scalar. Estimate of the response probability:
|
obd_bound |
Character scalar. Combinations from which the OBDC is chosen:
|
dose_a, dose_b |
Numeric vectors or |
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 |
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 ( |
verbose |
Logical scalar. Print progress messages. Defaults to |
seed |
Integer scalar or |
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 |
|
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 |
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 |
stop_reason_percent |
Percentage of trials by stopping reason. |
est_method, obd_bound, settings, call |
The settings used. |
trials, obd |
With |
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 |
target_resp |
Numeric scalar. Lowest acceptable response probability, phi_E, as in
|
scenarios |
List of scenarios. Each element is a list with the matrices
|
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 |
n_earlystop |
Integer scalar or |
n_earlystop_rule |
Character scalar. |
p_saf, p_tox |
Numeric scalars or |
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 |
cutoff_eli_resp |
Numeric scalar. A combination is inadmissible when the posterior
probability that its response rate is below |
extrasafe |
Logical scalar. Apply the cutoff |
offset |
Numeric scalar. Amount by which |
psi00, psi11 |
Numeric scalars from 0 to 100. Utility of a patient without DLT and
without response, and with both, as in |
benchmark_weight |
Numeric scalar above 0 and at most 1. Weight of the lowest acceptable
utility in the utility benchmark, as in |
utility_prior |
Numeric vector of two positive numbers. Beta prior of the utility of a
combination divided by 100. Defaults to |
n_star |
Integer scalar. With at least this many patients at the current
combination and a DLT rate between |
tie_break |
Character scalar. Choice among the combinations of equal desirability:
|
no_candidate |
Character scalar. What happens when none of the combinations allowed
for the next cohort is admissible: |
resp_cor |
Numeric scalar between -1 and 1. Correlation between the DLT and the
response of a patient, see |
resp_cor_type |
Character scalar. |
est_method |
Character scalar. Estimate of the response probability:
|
obd_bound |
Character scalar. Combinations from which the OBDC is chosen:
|
dose_a, dose_b |
Numeric vectors or |
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 |
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 ( |
verbose |
Logical scalar. Print progress messages. Defaults to |
seed |
Integer scalar or |
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 |
summary_table |
Data frame with one row per scenario, as shown by
|
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
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 |
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 |
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 |
p_tox |
Numeric scalar. Lowest DLT probability deemed overly toxic.
Defaults to |
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 |
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 |
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 |
Value
An object of class comb_boin_oc_multi, which is a list with components
results |
Named list of |
summary_table |
Data frame with one row per scenario: the true MTD combinations (those closest to |
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
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 |
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 |
method |
Character scalar, |
accrual |
Character scalar. Distribution of the times between arrivals:
|
dlt_time |
Character scalar. Distribution of the time to DLT within the window:
|
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 |
max_pending_ratio |
Numeric scalar or |
min_completed |
Integer scalar or |
min_follow_up |
Numeric scalar between 0 and 1. Shortest follow-up, as a fraction of
|
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 |
p_tox |
Numeric scalar. Lowest DLT probability deemed overly toxic.
Defaults to |
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 |
offset |
Numeric scalar between 0 and 0.5. Amount by which |
bound_mtd |
Logical scalar. Require the isotonic estimate at the selected dose to be at
or below the de-escalation boundary. Defaults to |
mtd_max_estimate |
Numeric scalar or |
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 |
n_earlystop_rule |
Character scalar, either |
keep_trials |
Logical scalar. Keep the full trial by trial data in the result.
Defaults to |
verbose |
Logical scalar. Report progress while the simulation runs.
Defaults to |
seed |
Integer scalar or |
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
|
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
|
target_resp |
Numeric scalar. Lowest acceptable response probability, phi_E. Note that
this is a lower limit, as in |
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 |
resp_window |
Numeric scalar. Length of the response assessment window. Defaults to
|
accrual |
Character scalar. Distribution of the times between arrivals:
|
event_time |
Character scalar. Distribution of the times to DLT and to response:
|
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: |
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 |
n_earlystop_rule |
Character scalar. |
p_saf, p_tox |
Numeric scalars or |
cutoff_eli |
Numeric scalar. A dose is inadmissible, together with every higher dose,
when the posterior probability that its DLT rate exceeds |
cutoff_eli_resp |
Numeric scalar. A dose is inadmissible when the posterior probability
that its response rate is below |
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
|
utility_prior |
Numeric vector of two positive numbers. Beta prior of the utility of a
dose divided by 100. Defaults to |
n_star |
Integer scalar. With at least this many patients at the current dose and
a DLT rate between |
n_explore |
Integer scalar. With at least this many patients at the current dose, a
DLT rate below |
tie_break |
Character scalar. Choice among the doses of equal desirability:
|
no_candidate |
Character scalar. What happens when none of the doses allowed for the
next cohort is admissible: |
explore_from |
Character scalar. Doses from which the exploration rule (see
|
resp_cor |
Numeric scalar between -1 and 1. Correlation between the DLT and the
response of a patient, see |
resp_cor_type |
Character scalar. |
est_method |
Character scalar. Estimate of the utility of a dose:
|
keep_trials |
Logical scalar. Keep the simulated trials and the selected OBDs in the
result. Defaults to |
verbose |
Logical scalar. Report progress with messages. Defaults to |
seed |
Integer scalar or |
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 |
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
|
target_resp |
Numeric scalar. Lowest acceptable response probability, phi_E. Note that
this is a lower limit, as in |
scenarios |
List of scenarios. Each element is a list with the components
|
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 |
resp_window |
Numeric scalar. Length of the response assessment window. Defaults to
|
accrual |
Character scalar. Distribution of the times between arrivals:
|
event_time |
Character scalar. Distribution of the times to DLT and to response:
|
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: |
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 |
n_earlystop_rule |
Character scalar. |
p_saf, p_tox |
Numeric scalars or |
cutoff_eli |
Numeric scalar. A dose is inadmissible, together with every higher dose,
when the posterior probability that its DLT rate exceeds |
cutoff_eli_resp |
Numeric scalar. A dose is inadmissible when the posterior probability
that its response rate is below |
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
|
utility_prior |
Numeric vector of two positive numbers. Beta prior of the utility of a
dose divided by 100. Defaults to |
n_star |
Integer scalar. With at least this many patients at the current dose and
a DLT rate between |
n_explore |
Integer scalar. With at least this many patients at the current dose, a
DLT rate below |
tie_break |
Character scalar. Choice among the doses of equal desirability:
|
no_candidate |
Character scalar. What happens when none of the doses allowed for the
next cohort is admissible: |
explore_from |
Character scalar. Doses from which the exploration rule (see
|
resp_cor |
Numeric scalar between -1 and 1. Correlation between the DLT and the
response of a patient, see |
resp_cor_type |
Character scalar. |
est_method |
Character scalar. Estimate of the utility of a dose:
|
keep_trials |
Logical scalar. Keep the simulated trials and the selected OBDs in the
result. Defaults to |
verbose |
Logical scalar. Report progress with messages. Defaults to |
seed |
Integer scalar or |
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 |
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 |
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 |
resp_window |
Numeric scalar. Length of the response assessment window. Defaults to
|
accrual |
Character scalar. Distribution of the times between arrivals:
|
event_time |
Character scalar. Distribution of the times to DLT and to response:
|
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 |
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 |
p_saf |
Numeric scalar. Highest DLT probability deemed subtherapeutic. Defaults
to |
p_tox |
Numeric scalar. Lowest DLT probability deemed overly toxic. Defaults to
|
p_saf_resp |
Numeric scalar. Highest response probability deemed subtherapeutic.
Defaults to |
cutoff_eli |
Numeric scalar. A dose is no longer admissible when the posterior
probability that its DLT rate is below |
cutoff_eli_resp |
Numeric scalar. A dose is no longer admissible when the posterior
probability that its response rate is above |
p_eli |
Numeric scalar or |
p_eli_resp |
Numeric scalar or |
boinet_compatible |
Logical scalar. Apply the rules of the 'boinet' package (version 1.6.0)
exactly. Defaults to |
prior |
Numeric vector of length 6. Prior probabilities of the six hypotheses.
Defaults to |
est_method |
Character scalar. Estimator of the response rates: |
obd_method |
Character scalar. Selection rule: |
w1, w2 |
Numeric scalars. Weights of the weighted utility
|
t_low, t_upp |
Numeric scalars or |
e_low, e_upp |
Numeric scalars or |
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 |
verbose |
Logical scalar. Report progress with messages. Defaults to |
seed |
Integer scalar or |
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 |
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
|
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 |
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 |
resp_window |
Numeric scalar. Length of the response assessment window. Defaults to
|
accrual |
Character scalar. Distribution of the times between arrivals:
|
event_time |
Character scalar. Distribution of the times to DLT and to response:
|
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 |
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 |
p_saf |
Numeric scalar. Highest DLT probability deemed subtherapeutic. Defaults
to |
p_tox |
Numeric scalar. Lowest DLT probability deemed overly toxic. Defaults to
|
p_saf_resp |
Numeric scalar. Highest response probability deemed subtherapeutic.
Defaults to |
cutoff_eli |
Numeric scalar. A dose is no longer admissible when the posterior
probability that its DLT rate is below |
cutoff_eli_resp |
Numeric scalar. A dose is no longer admissible when the posterior
probability that its response rate is above |
p_eli |
Numeric scalar or |
p_eli_resp |
Numeric scalar or |
boinet_compatible |
Logical scalar. Apply the rules of the 'boinet' package (version 1.6.0)
exactly. Defaults to |
prior |
Numeric vector of length 6. Prior probabilities of the six hypotheses.
Defaults to |
est_method |
Character scalar. Estimator of the response rates: |
obd_method |
Character scalar. Selection rule: |
w1, w2 |
Numeric scalars. Weights of the weighted utility
|
t_low, t_upp |
Numeric scalars or |
e_low, e_upp |
Numeric scalars or |
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 |
verbose |
Logical scalar. Report progress with messages. Defaults to |
seed |
Integer scalar or |
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
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 |
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 |
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 |
method |
Character scalar, |
accrual |
Character scalar. Distribution of the times between arrivals:
|
dlt_time |
Character scalar. Distribution of the time to DLT within the window:
|
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 |
max_pending_ratio |
Numeric scalar or |
min_completed |
Integer scalar or |
min_follow_up |
Numeric scalar between 0 and 1. Shortest follow-up, as a fraction of
|
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 |
p_tox |
Numeric scalar. Lowest DLT probability deemed overly toxic.
Defaults to |
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 |
offset |
Numeric scalar between 0 and 0.5. Amount by which |
bound_mtd |
Logical scalar. Require the isotonic estimate at the selected dose to be at
or below the de-escalation boundary. Defaults to |
mtd_max_estimate |
Numeric scalar or |
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 |
n_earlystop_rule |
Character scalar, either |
keep_trials |
Logical scalar. Keep the trial by trial data of every scenario.
Defaults to |
verbose |
Logical scalar. Report progress while the simulations run.
Defaults to |
seed |
Integer scalar or |
Value
An object of class c("tite_boin_oc_multi", "boin_oc_multi"), which
is a list with components
results |
Named list of |
summary_table |
Data frame collecting all scenarios, with the four rows
of |
scenario_names |
Character vector of scenario names. |
n_doses |
Number of dose levels. |
call |
The matched call. |
See Also
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 |
target_resp |
Numeric scalar. Lowest acceptable response probability, phi_E, as in
|
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 |
resp_window |
Numeric scalar. Length of the response assessment window. Defaults to
|
accrual |
Character scalar. Distribution of the times between arrivals:
|
event_time |
Character scalar. Distribution of the times to DLT and to response:
|
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: |
pending_use |
Character scalar. Where the pending outcomes count: |
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 |
n_earlystop |
Integer scalar or |
n_earlystop_rule |
Character scalar. |
p_saf, p_tox |
Numeric scalars or |
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 |
cutoff_eli_resp |
Numeric scalar. A combination is inadmissible when the posterior
probability that its response rate is below |
extrasafe |
Logical scalar. Apply the cutoff |
offset |
Numeric scalar. Amount by which |
psi00, psi11 |
Numeric scalars from 0 to 100. Utility of a patient without DLT and
without response, and with both, as in |
benchmark_weight |
Numeric scalar above 0 and at most 1. Weight of the lowest acceptable
utility in the utility benchmark, as in |
utility_prior |
Numeric vector of two positive numbers. Beta prior of the utility of a
combination divided by 100. Defaults to |
n_star |
Integer scalar. With at least this many patients at the current
combination and a DLT rate between |
tie_break |
Character scalar. Choice among the combinations of equal desirability:
|
no_candidate |
Character scalar. What happens when none of the combinations allowed
for the next cohort is admissible: |
resp_cor |
Numeric scalar between -1 and 1. Correlation between the DLT and the
response of a patient, see |
resp_cor_type |
Character scalar. |
est_method |
Character scalar. Estimate of the response probability:
|
obd_bound |
Character scalar. Combinations from which the OBDC is chosen:
|
dose_a, dose_b |
Numeric vectors or |
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 |
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 ( |
verbose |
Logical scalar. Print progress messages. Defaults to |
seed |
Integer scalar or |
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 |
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 |
target_resp |
Numeric scalar. Lowest acceptable response probability, phi_E, as in
|
scenarios |
List of scenarios. Each element is a list with the matrices
|
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 |
resp_window |
Numeric scalar. Length of the response assessment window. Defaults to
|
accrual |
Character scalar. Distribution of the times between arrivals:
|
event_time |
Character scalar. Distribution of the times to DLT and to response:
|
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: |
pending_use |
Character scalar. Where the pending outcomes count: |
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 |
n_earlystop |
Integer scalar or |
n_earlystop_rule |
Character scalar. |
p_saf, p_tox |
Numeric scalars or |
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 |
cutoff_eli_resp |
Numeric scalar. A combination is inadmissible when the posterior
probability that its response rate is below |
extrasafe |
Logical scalar. Apply the cutoff |
offset |
Numeric scalar. Amount by which |
psi00, psi11 |
Numeric scalars from 0 to 100. Utility of a patient without DLT and
without response, and with both, as in |
benchmark_weight |
Numeric scalar above 0 and at most 1. Weight of the lowest acceptable
utility in the utility benchmark, as in |
utility_prior |
Numeric vector of two positive numbers. Beta prior of the utility of a
combination divided by 100. Defaults to |
n_star |
Integer scalar. With at least this many patients at the current
combination and a DLT rate between |
tie_break |
Character scalar. Choice among the combinations of equal desirability:
|
no_candidate |
Character scalar. What happens when none of the combinations allowed
for the next cohort is admissible: |
resp_cor |
Numeric scalar between -1 and 1. Correlation between the DLT and the
response of a patient, see |
resp_cor_type |
Character scalar. |
est_method |
Character scalar. Estimate of the response probability:
|
obd_bound |
Character scalar. Combinations from which the OBDC is chosen:
|
dose_a, dose_b |
Numeric vectors or |
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 |
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 ( |
verbose |
Logical scalar. Print progress messages. Defaults to |
seed |
Integer scalar or |
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
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
|
target_resp |
Numeric scalar. Lowest acceptable response probability, phi_E. Note that
this is a lower limit, as in |
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 |
resp_window |
Numeric scalar. Length of the response assessment window. Defaults to
|
accrual |
Character scalar. Distribution of the times between arrivals:
|
event_time |
Character scalar. Distribution of the times to DLT and to response:
|
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: |
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 |
n_earlystop_rule |
Character scalar. |
p_saf, p_tox |
Numeric scalars or |
cutoff_eli |
Numeric scalar. A dose is inadmissible, together with every higher dose,
when the posterior probability that its DLT rate exceeds |
cutoff_eli_resp |
Numeric scalar. A dose is inadmissible when the posterior probability
that its response rate is below |
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
|
utility_prior |
Numeric vector of two positive numbers. Beta prior of the utility of a
dose divided by 100. Defaults to |
n_star |
Integer scalar. With at least this many patients at the current dose and
a DLT rate between |
n_explore |
Integer scalar. With at least this many patients at the current dose, a
DLT rate below |
tie_break |
Character scalar. Choice among the doses of equal desirability:
|
no_candidate |
Character scalar. What happens when none of the doses allowed for the
next cohort is admissible: |
explore_from |
Character scalar. Doses from which the exploration rule (see
|
resp_cor |
Numeric scalar between -1 and 1. Correlation between the DLT and the
response of a patient, see |
resp_cor_type |
Character scalar. |
seed |
Integer scalar or |
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
|
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: |
p_saf |
Numeric scalar. Highest DLT probability deemed subtherapeutic.
Defaults to |
p_tox |
Numeric scalar. Lowest DLT probability deemed overly toxic.
Defaults to |
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 |
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 |
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
|
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. |
esc_bound |
Escalate, or suspend when escalation is blocked, when the
follow-up statistic is at least this value. |
deesc_bound |
De-escalate when the follow-up statistic is at most this
value. |
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 |
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 |
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 |
resp_window |
Numeric scalar. Length of the response assessment window. Defaults to
|
accrual |
Character scalar. Distribution of the times between arrivals:
|
event_time |
Character scalar. Distribution of the times to DLT and to response:
|
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 |
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 |
p_saf |
Numeric scalar. Highest DLT probability deemed subtherapeutic. Defaults
to |
p_tox |
Numeric scalar. Lowest DLT probability deemed overly toxic. Defaults to
|
p_saf_resp |
Numeric scalar. Highest response probability deemed subtherapeutic.
Defaults to |
cutoff_eli |
Numeric scalar. A dose is no longer admissible when the posterior
probability that its DLT rate is below |
cutoff_eli_resp |
Numeric scalar. A dose is no longer admissible when the posterior
probability that its response rate is above |
p_eli |
Numeric scalar or |
p_eli_resp |
Numeric scalar or |
boinet_compatible |
Logical scalar. Apply the rules of the 'boinet' package (version 1.6.0)
exactly. Defaults to |
prior |
Numeric vector of length 6. Prior probabilities of the six hypotheses.
Defaults to |
seed |
Integer scalar or |
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 |
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 |
method |
Character scalar, |
accrual |
Character scalar. Distribution of the times between arrivals:
|
dlt_time |
Character scalar. Distribution of the time to DLT within the window:
|
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 |
max_pending_ratio |
Numeric scalar or |
min_completed |
Integer scalar or |
min_follow_up |
Numeric scalar between 0 and 1. Shortest follow-up, as a fraction of
|
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 |
p_tox |
Numeric scalar. Lowest DLT probability deemed overly toxic.
Defaults to |
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 |
offset |
Numeric scalar between 0 and 0.5. Amount by which |
n_earlystop_rule |
Character scalar, either |
seed |
Integer scalar or |
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_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 |
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 |
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 |
target_resp |
Numeric scalar. Lowest acceptable response probability, phi_E, as in
|
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 |
resp_window |
Numeric scalar. Length of the response assessment window. Defaults to
|
accrual |
Character scalar. Distribution of the times between arrivals:
|
event_time |
Character scalar. Distribution of the times to DLT and to response:
|
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: |
pending_use |
Character scalar. Where the pending outcomes count: |
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 |
n_earlystop |
Integer scalar or |
n_earlystop_rule |
Character scalar. |
p_saf, p_tox |
Numeric scalars or |
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 |
cutoff_eli_resp |
Numeric scalar. A combination is inadmissible when the posterior
probability that its response rate is below |
extrasafe |
Logical scalar. Apply the cutoff |
offset |
Numeric scalar. Amount by which |
psi00, psi11 |
Numeric scalars from 0 to 100. Utility of a patient without DLT and
without response, and with both, as in |
benchmark_weight |
Numeric scalar above 0 and at most 1. Weight of the lowest acceptable
utility in the utility benchmark, as in |
utility_prior |
Numeric vector of two positive numbers. Beta prior of the utility of a
combination divided by 100. Defaults to |
n_star |
Integer scalar. With at least this many patients at the current
combination and a DLT rate between |
tie_break |
Character scalar. Choice among the combinations of equal desirability:
|
no_candidate |
Character scalar. What happens when none of the combinations allowed
for the next cohort is admissible: |
resp_cor |
Numeric scalar between -1 and 1. Correlation between the DLT and the
response of a patient, see |
resp_cor_type |
Character scalar. |
seed |
Integer scalar or |
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
|
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