| Type: | Package |
| Title: | Objective Comparison of Phase I Dose-Finding Designs |
| Version: | 0.1.1 |
| Description: | Generate decision tables and simulate operating characteristics for phase I dose-finding designs to enable objective comparison across methods. Supported designs include the traditional 3+3, Bayesian Optimal Interval (BOIN) (Liu and Yuan (2015) <doi:10.1158/1078-0432.CCR-14-1526>), modified Toxicity Probability Interval-2 (mTPI-2) (Guo et al. (2017) <doi:10.1002/sim.7185>), interval 3+3 (i3+3) (Liu et al. (2020) <doi:10.1177/0962280220939123>), and Generalized 3+3 (G3). Provides visualization tools for comparing decision rules and operating characteristics across multiple designs simultaneously. |
| Encoding: | UTF-8 |
| Language: | en-US |
| License: | MIT + file LICENSE |
| Suggests: | knitr, rmarkdown, testthat (≥ 3.0.0) |
| VignetteBuilder: | knitr |
| RoxygenNote: | 7.3.2 |
| Imports: | ggplot2, grid, gridExtra, gtable, dplyr, rlang, stats |
| Config/testthat/edition: | 3 |
| NeedsCompilation: | no |
| Packaged: | 2025-12-10 03:09:07 UTC; oliviazhang |
| Author: | Yuan Ji [aut], Yunxuan Zhang [aut, cre] |
| Maintainer: | Yunxuan Zhang <yunxuanz@uchicago.edu> |
| Repository: | CRAN |
| Date/Publication: | 2025-12-15 20:20:07 UTC |
FIND: Compare Objective Decision Tables for Phase I Dose-Finding Designs
Description
The FIND package provides tools to compare decision tables and evaluate operating characteristics for Phase I dose-finding trial designs. It implements five popular designs: 3+3, i3+3 (Interval-based 3+3), BOIN (Bayesian Optimal Interval), G3+3 (Generalized 3+3), and mTPI-2 (Modified Toxicity Probability Interval).
Main Functions
Design Constructors: design_boin(), design_i3plus3(), design_mtpi2(), design_g3plus3(), design_3plus3()
Generic Functions: get_decision(), run_simulation()
Wrapper Functions: decision_table(), oc_plot()
Utility Functions: load_true(), select_mtd(), summarize_metric()
Getting Started
The S3 interface provides the cleanest workflow:
# Create design specifications boin <- design_boin(pT = 0.25, EI = c(0.15, 0.35), npts = 12) i3 <- design_i3plus3(pT = 0.25, EI = c(0.2, 0.3), npts = 12) # Generate decision tables decision_table(boin, i3) # Run simulations p.true <- c(0.05, 0.10, 0.20, 0.30, 0.45) mtd.true <- c(0, 0, 1, 0, 0) boin_sim <- design_boin(pT = 0.25, EI = c(0.15, 0.35), ncohort = 10) results <- run_simulation(boin_sim, p.true = p.true, mtd.true = mtd.true) # Compare operating characteristics oc_plot(results)
Vignettes
See vignette("Generate_decision_tables"), vignette("Obtain_operating_characteristics"), and vignette("S3_interface_guide") for detailed examples.
Author(s)
Maintainer: Yunxuan Zhang yunxuanz@uchicago.edu
Authors:
Yuan Ji yji@bsd.uchicago.edu
References
Storer, B. E. (1989). Design and analysis of phase I clinical trials. Biometrics, 45, 925-937.
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.
Guo, W., Wang, S. J., Yang, S., Lynn, H. S., and Ji, Y. (2017). A Bayesian interval dose-finding design addressing Ockham's razor: mTPI-2. Contemporary Clinical Trials, 58, 23-33.
Liu, M., Wang, S. J., and Ji, Y. (2020). The i3+3 design for phase I clinical trials. Journal of Biopharmaceutical Statistics, 30(2), 294-304.
Generate Decision Tables with S3 Support
Description
Enhanced wrapper to generate decision tables that supports both legacy and S3 interfaces.
Usage
decision_table(...)
Arguments
... |
Either design objects (created with |
Value
A plot showing decision table(s) for the specified design(s).
Examples
# New S3 interface
boin <- design_boin(pT = 0.25, EI = c(0.15, 0.35), npts = 12)
i3 <- design_i3plus3(pT = 0.25, EI = c(0.2, 0.3), npts = 12)
# Generate decision tables
decision_table(boin, i3)
# Legacy interface still works
decision_table(
BOIN = get_decision_boin(pT = 0.25, EI = c(0.15, 0.35), npts = 12),
`i3+3` = get_decision_i3plus3(pT = 0.25, EI = c(0.2, 0.3), npts = 12)
)
Design Constructor Functions
Description
Constructor functions to create design specification objects for Phase I dose-finding trials.
Usage
design_boin(
pT,
EI,
npts = 12,
ncohort = NULL,
cohortsize = 3,
startdose = 1,
DU.pp = 0.95,
n.earlystop = 100,
extrasafe = FALSE,
ntrial = 1000,
seed = 6
)
design_i3plus3(
pT,
EI,
npts = 12,
ncohort = NULL,
cohortsize = 3,
startdose = 1,
DU.pp = 0.95,
n.earlystop = 100,
extrasafe = FALSE,
ntrial = 1000,
seed = 6
)
design_mtpi2(
pT,
EI,
npts = 12,
ncohort = NULL,
cohortsize = 3,
startdose = 1,
DU.pp = 0.95,
n.earlystop = 100,
extrasafe = FALSE,
ntrial = 1000,
seed = 6
)
design_g3plus3(
npts = 12,
ncohort = NULL,
cohortsize = 3,
startdose = 1,
DU.pp = 0.95,
n.earlystop = 100,
ntrial = 1000,
seed = 6
)
design_3plus3(
npts = 12,
ncohort = NULL,
cohortsize = 3,
startdose = 1,
ntrial = 1000,
seed = 6
)
Arguments
pT |
a numeric value; the target DLT rate. |
EI |
a vector of length 2; the equivalence interval (EI). |
npts |
a numeric value; the number of participants for decision table generation. |
ncohort |
a numeric value; the total number of cohorts for simulation. |
cohortsize |
a numeric value; the cohort size (default: 3). |
startdose |
a numeric value; the starting dose level (default: 1). |
DU.pp |
a numeric value; the cutoff to remove an overly toxic dose (default: 0.95). |
n.earlystop |
a numeric value; early stopping parameter (default: 100). |
extrasafe |
a logical value; whether to implement extra safety rule (default: FALSE). |
ntrial |
a numeric value; the total number of simulated trials (default: 1000). |
seed |
a numeric value; random seed for simulation (default: 6). |
Value
An S3 object of class boin_design, i3plus3_design, mtpi2_design,
g3plus3_design, or threethree_design containing the design specifications.
Examples
# Create a BOIN design specification
boin <- design_boin(pT = 0.25, EI = c(0.15, 0.35), npts = 12)
# Create an i3+3 design specification
i3 <- design_i3plus3(pT = 0.25, EI = c(0.2, 0.3), npts = 12)
Generate the decision table(s) for a single or multiple designs
Description
Generate the decision table(s) for a single or multiple designs
Usage
generate_decision_table(`3+3` = NULL,
`BOIN` = NULL,
`mTPI2` = NULL,
`i3+3` = NULL,
`G3` = NULL)
Arguments
3+3 |
the object returned by get_decision_3plus3() |
BOIN |
the object returned by get_decision_boin() |
mTPI2 |
the object returned by get_decision_mtpi2() |
i3+3 |
the object returned by get_decision_i3plus3() |
G3 |
the object returned by get_decision_g3plus3() |
Value
generate_decision_table() returns a figure displaying the decision table(s) for the user-specified design(s).
Generate the plot(s) displaying operating characteristics for a single or multiple designs
Description
Generate the plot(s) displaying operating characteristics for a single or multiple designs
Usage
generate_oc_plot(`3+3` = NULL,
`BOIN` = NULL,
`mTPI2` = NULL,
`i3+3` = NULL,
`G3` = NULL)
Arguments
3+3 |
the object returned by run_sim_threethree() |
BOIN |
the object returned by run_sim_boin() |
mTPI2 |
the object returned by run_sim_mtpi2() |
i3+3 |
the object returned by run_sim_i3() |
G3 |
the object returned by run_sim_g3() |
Value
generate_oc_plot() returns figures displaying the operating characteristics for the user-specified design(s).
Generate Decision Tables for Phase I Dose-Finding Designs
Description
Generic function to generate dosing decisions (E, S, D or DU) for phase I dose-finding designs.
Usage
get_decision(design, ...)
## S3 method for class 'boin_design'
get_decision(design, ...)
## S3 method for class 'i3plus3_design'
get_decision(design, ...)
## S3 method for class 'mtpi2_design'
get_decision(design, ...)
## S3 method for class 'g3plus3_design'
get_decision(design, ...)
## S3 method for class 'threethree_design'
get_decision(design, ...)
## Default S3 method:
get_decision(design, ...)
Arguments
design |
A design object created by one of the design constructor functions
( |
... |
Additional arguments passed to methods. |
Value
A list containing 'tab' (a dataframe with decisions E, S, D, or DU for each combination of y and n) and 'setup' (a list containing design parameters).
Examples
# Create design specifications
boin <- design_boin(pT = 0.25, EI = c(0.15, 0.35), npts = 12)
i3 <- design_i3plus3(pT = 0.25, EI = c(0.2, 0.3), npts = 12)
# Generate decision tables
decision_boin <- get_decision(boin)
decision_i3 <- get_decision(i3)
Dosing decision for the 3+3 design
Description
Generate dosing decisions (E, S, D or DU) of the 3+3 design for user-specified number of participants.
Usage
get_decision_3plus3(npts = 12)
Arguments
npts |
the number of participants within which dosing decisions are generated. |
Details
The 3+3 design uses the following decision rules.
(1). Start trial by treating three participants at the initial dose.
(2). Denote the dose level being used to treat participants as the current dose level. Treat three participants at the current dose level.
2a. If the maximum number of participants has been accrued, stop the trial. The MTD is inconclusive.
(3). Check the number of participants at the current dose level.
3a. If there are three participants, go to (4).
3b. If there are six participants, go to (5).
(4). Check the number of toxicities (among three participants) at the current dose level.
4a. If there are zero toxicities, escalate and go to (7).
4b. If there is one toxicity, stay at the current dose and go to (2).
4c. If there are two or three toxicities, declare that the MTD has been exceeded and go to (6).
(5). Check the number of toxicities (among six participants) at the current dose level.
5a. If there are zero toxicities, stop the trial and declare that the MTD is the current dose.
5b. If there is one toxicity, and the MTD has been exceeded, stop the trial and declare that the MTD is the current dose; otherwise, go to (7).
5c. If there are two or more than two toxicities, declare that the MTD has been exceeded and go to (6).
(6). The MTD has been exceeded.
6a. If the current dose is the lowest dose, stop the trial and declare that the MTD is lower than the lowest dose level.
6b. If then next-lower dose level has six participants, stop the trial and declare that the MTD is the next lower dose level; otherwise, the next lower dose level has three participants; set the current dose level to be the next-lower dose level and go to (2).
(7). Escalate if possible.
7a. If the current dose level is the highest dose level, stop the trial and declare that the MTD is the highest dose level.
7b. Otherwise, escalate to the next higher dose level and go to (2).
Value
get_decision_3plus3() returns:
(1) a dataframe containing the decisions (E, S, D or DU) for each combination of y and n ($tab),
(2) a list ($setup) containing user input parameters, such as npts.
References
Storer B. (1989). Design and analysis of phase i clinical trials, Biometrics, 925–937.
Yang, S., Wang, S.J. and Ji, Y., (2015). An integrated dose-finding tool for phase I trials in oncology. Contemporary clinical trials, 45, pp.426-434.
Examples
get_decision_3plus3(npts = 12)
Dosing decision for the BOIN design
Description
Generate dosing decisions (E, S, D or DU) of the BOIN design for user-specified number of participants.
Usage
get_decision_boin(pT,
EI,
npts)
Arguments
pT |
a numeric value that specifies the target DLT rate ( |
EI |
a vector that specifies the equivalence interval (EI). |
npts |
the number of participants within which dosing decisions are generated. |
Details
Denote the current dose d. Let n_d and y_d represent the
number of participants treated at dose d and the number of participants
experienced DLT, respectively. Let p_d be the toxicity probability at
dose d. Also, denote \frac{y_d}{n_d} the observed toxicity rate
at the current dose.
The BOIN design uses the following decision rules: if
\frac{y_d}{n_d} is lower than or equal to the escalation boundary,
the decision is to escalate to the next higher dose; if \frac{y_d}{n_d}
is higher than the de-escalation boundary, the decision is to the next lower
dose; otherwise, the decision is to stay at the current dose.
Also, the BOIN design includes a dose exclusion rule. Let p_T represents
the target DLT rate. If Pr(p_d > p_T | y_d , n_d ) > 0.95, dose d
and those higher than d are removed from the trial since they are deemed
excessively toxic.
Value
get_decision_boin() returns:
(1) a dataframe containing the decisions (E, S, D or DU) for each combination of y and n ($tab),
(2) a list ($setup) containing user input parameters, such as target, EI, npts, etc.
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
get_decision_boin(pT = 0.25,
EI = c(0.15,0.35),
npts = 12)
Dosing decision for the G3 design
Description
Generate dosing decisions (E, S, D or DU) of the G3 design for user-specified number of participants.
Usage
get_decision_g3plus3(npts = 12)
Arguments
npts |
the number of participants within which dosing decisions are generated. |
Details
Denote the current dose d. Let n_d and y_d represent the
number of participants treated at dose d and the number of participants
experienced DLT, respectively. Let p_d be the toxicity probability at
dose d. Also, denote \frac{y_d}{n_d} the observed toxicity rate
at the current dose.
The G3 design uses the following decision rules. For n is three or six,
we simply apply the 3+3 rules; otherwise, we use the following decision rules,
with EI being [0.2, 0.29]. If \frac{y_d}{n_d} is lower than the escalation
boundary (i.e. below the EI), the decision is to escalate to the next higher dose;
if \frac{y_d}{n_d} is between the escalation and de-escalation boundaries
(between the EI), the decision is to stay at the current dose; if
\frac{y_d}{n_d} is higher than the de-escalation boundary (i.e. above
the EI), the decision is to de-escalate to the next lower dose.
Also, the G3 design includes a dose exclusion rule. If Pr(p_d > 0.25 | y_d , n_d ) > 0.95,
dose d and those higher than d are removed from the trial since they
are deemed excessively toxic.
Value
get_decision_g3plus3() returns:
(1) a dataframe containing the decisions (E, S, D or DU) for each combination of y and n ($tab),
(2) a list ($setup) containing user input parameters, such as npts.
References
To be added.
Examples
get_decision_g3plus3(npts = 12)
Dosing decision for the i3+3 design
Description
Generate dosing decisions (E, S, D or DU) of the i3+3 design for user-specified number of participants.
Usage
get_decision_i3plus3(pT = NULL,
EI = NULL,
npts = 12)
Arguments
pT |
a numeric value that specifies the target DLT rate ( |
EI |
a vector that specifies the equivalence interval (EI). |
npts |
the number of participants within which dosing decisions are generated. |
Details
Denote the current dose d. Let n_d and y_d represent the
number of participants treated at dose d and the number of participants
experienced DLT, respectively. Let p_d be the toxicity probability at
dose d. Also, denote \frac{y_d}{n_d} the observed toxicity rate
at the current dose.
The i3+3 design uses the following decision rules.
If \frac{y_d}{n_d} is lower than the escalation boundary (i.e. below
the EI), the decision is to escalate to the next higher dose; if
\frac{y_d}{n_d} is between the escalation and de-escalation boundaries
(i.e. inside the EI), the decision is to stay at the current dose; if
\frac{y_d}{n_d} is higher than the de-escalation boundary (i.e. above
the EI), there are two options: option one, if \frac{y_d-1}{n_d} is
lower than the escalation boundary (i.e., below the EI), the decision is
to stay at the current dose; option two, else if \frac{y_d-1}{n_d}
is equal to or higher than the escalation boundary, the decision is to
de-escalate to the next lower dose.
Also, the i3+3 design includes a dose exclusion rule. Let p_T represents
the target DLT rate. If Pr(p_d > p_T | y_d , n_d ) > 0.95, dose d
and those higher than d are removed from the trial since they are deemed
excessively toxic.
Value
get_decision_i3plus3() returns:
(1) a dataframe containing the decisions (E, S, D or DU) for each combination of y and n ($tab),
(2) a list ($setup) containing user input parameters, such as target, EI, npts, etc.
References
Liu M., Wang, SJ. and Ji, Y. (2020). The i3+3 Design for Phase I Clinical Trials, Journal of biopharmaceutical statistics, 30(2):294–304.
Examples
get_decision_i3plus3(pT = 0.25,
EI = c(0.2,0.3),
npts = 12)
Dosing decision for the mTPI2 design
Description
Generate dosing decisions (E, S, D or DU) of the mTPI2 design for user-specified number of participants.
Usage
get_decision_mtpi2(pT,
EI,
npts)
Arguments
pT |
a numeric value that specifies the target DLT rate ( |
EI |
a vector that specifies the equivalence interval (EI). |
npts |
the number of participants within which dosing decisions are generated. |
Details
Denote the current dose d. Let n_d and y_d represent the
number of participants treated at dose d and the number of participants
experienced DLT, respectively. Let p_d be the toxicity probability at
dose d. Also, denote \frac{y_d}{n_d} the observed toxicity rate
at the current dose.
The mTPI2 design divides the probability of DLT into equal-width intervals: underdosing, target dosing, and overdosing. Utilizing a Bayesian model, mTPI-2 updates the posterior probability estimates of DLTs. If the interval which maximizes the posterior probability is among the underdosing intervals, the decision is to escalate to the next higher dose; if the interval which maximizes the posterior probability is the target dosing interval, the decision is to stay at the current dose; if the interval which maximizes the posterior probability is among the overdosing intervals, the decision is to to de-escalate to the next lower dose.
Also, the mTPI2 design includes a dose exclusion rule. Let p_T represents
the target DLT rate. If Pr(p_d > p_T | y_d , n_d ) > 0.95, dose d
and those higher than d are removed from the trial since they are deemed
excessively toxic.
Value
get_decision_mtpi2() returns:
(1) a dataframe containing the decisions (E, S, D or DU) for each combination of y and n ($tab),
(2) a list ($setup) containing user input parameters, such as target, EI, npts, etc.
References
Guo, W., Liu, S., & Yin, G. (2017). A more efficient Bayesian model for oncology dose-finding trials with toxicity probability interval. Clinical Trials, 14(1), 16-26.
Examples
get_decision_mtpi2(pT = 0.25,
EI = c(0.2,0.3),
npts = 12)
Load several commonly used scenarios
Description
Load several commonly used scenarios
Usage
load_true(pT = 0.25)
Arguments
pT |
the target DLT rate. |
Value
load_true() returns:
(1) a matrix ($p.true) containing the true toxicity probabilities of the investigational dose levels.
(2) a vector ($mtd.true) which specifies the true MTD.
Generate Operating Characteristics Plots with S3 Support
Description
Enhanced wrapper to generate OC plots that supports both legacy and S3 interfaces.
Usage
oc_plot(...)
Arguments
... |
Either simulation result objects (from |
Value
A list of plots showing operating characteristics for the specified design(s).
Examples
# New S3 interface
boin <- design_boin(pT = 0.25, EI = c(0.15, 0.35), ncohort = 10)
i3 <- design_i3plus3(pT = 0.25, EI = c(0.2, 0.3), ncohort = 10)
p.true <- c(0.05, 0.10, 0.20, 0.30, 0.45)
mtd.true <- c(0, 0, 1, 0, 0) # Dose 3 is the true MTD
# Run simulations
sim_boin <- run_simulation(boin, p.true = p.true, mtd.true = mtd.true)
sim_i3 <- run_simulation(i3, p.true = p.true, mtd.true = mtd.true)
# Generate OC plots
oc_plot(sim_boin, sim_i3)
Simulations for the 3+3 design.
Description
Conduct computer simulations for the 3+3 design.
Usage
run_sim_3plus3(p.true,
mtd.true,
startdose = 1,
ntrial = 1000,
seed = 6)
Arguments
p.true |
a vector or matrix containing the true toxicity probabilities of the investigational dose levels. |
mtd.true |
a numeric value or a vector which specifies the true MTD. |
startdose |
a numeric value; the starting dose level for the trial. |
ntrial |
a numeric value; the total number of simulated trials. |
seed |
a numeric value; the random seed for simulation. |
Details
The 3+3 design uses the following decision rules.
(1). Start trial by treating three participants at the initial dose.
(2). Denote the dose level being used to treat participants as the current dose level. Treat three participants at the current dose level.
(3). Check the number of participants at the current dose level.
3a. If there are three participants, go to (4).
3b. If there are six participants, go to (5).
(4). Check the number of toxicities (among three participants) at the current dose level.
4a. If there are zero toxicities, escalate and go to (7).
4b. If there is one toxicity, stay at the current dose and go to (2).
4c. If there are two or three toxicities, declare that the MTD has been exceeded and go to (6).
(5). Check the number of toxicities (among six participants) at the current dose level.
5a. If there are zero toxicities, stop the trial and declare that the MTD is the current dose.
5b. If there is one toxicity, and the MTD has been exceeded, stop the trial and declare that the MTD is the current dose; otherwise, go to (7).
5c. If there are two or more than two toxicities, declare that the MTD has been exceeded and go to (6).
(6). The MTD has been exceeded.
6a. If the current dose is the lowest dose, stop the trial and declare that the MTD is lower than the lowest dose level.
6b. If then next-lower dose level has six participants, stop the trial and declare that the MTD is the next lower dose level; otherwise, the next lower dose level has three participants; set the current dose level to be the next-lower dose level and go to (2).
(7). Escalate if possible.
7a. If the current dose level is the highest dose level, stop the trial and declare that the MTD is the highest dose level.
7b. Otherwise, escalate to the next higher dose level and go to (2).
Value
run_sim_3plus3() returns:
(1) a dataframe ($selection) with each column showing:
the numbered index for each scenarios specified,
the name of the design,
the selection percentage at each dose level,
the percentage of early stopping without selecting the MTD,
the percentage of overdosing selection (POS),
the percentage of correct selection (PCS),
the percentage of underdosing selection (PUS),
the numbered index for the true MTD, respectively.
(2) a dataframe ($allocation) with each column showing:
the numbered index for each scenarios specified,
the name of the design,
the number of participants treated at each dose level,
the average number of participants treated,
the percentage of overdosing assignment (POA),
the percentage of correct assignment (PCA),
the percentage of underdosing assignment (PUA),
the numbered index for the true MTD, respectively.
(3) a list ($setup) containing user input parameters.
References
Storer B. (1989). Design and analysis of phase i clinical trials, Biometrics, 925–937.
Yang, S., Wang, S.J. and Ji, Y., (2015). An integrated dose-finding tool for phase I trials in oncology. Contemporary clinical trials, 45, pp.426-434.
Examples
run_sim_3plus3(p.true = c(0.25, 0.41, 0.45, 0.49, 0.53),
mtd.true = c(1,0,0,0,0),
startdose = 1,
ntrial = 1000,
seed = 6)
Simulations for the BOIN design.
Description
Conduct computer simulations for the BOIN design.
Usage
run_sim_boin(p.true,
mtd.true,
pT,
EI,
ncohort,
cohortsize = 3,
startdose = 1,
DU.pp = 0.95,
n.earlystop = 100,
extrasafe = FALSE,
ntrial = 1000,
seed = 6)
Arguments
p.true |
a vector or matrix containing the true toxicity probabilities of the investigational dose levels. |
mtd.true |
a numeric value or a vector which specifies the true MTD. |
pT |
a numeric value; the target DLT rate. |
EI |
a vector which specifies the equivalence interval (EI). |
ncohort |
a numeric value; the total number of cohorts. |
cohortsize |
a numeric value; the cohort size. |
startdose |
a numeric value; the starting dose level for the trial. |
DU.pp |
a numeric value; the cutoff to remove an overly toxic dose for safety.
We recommend the default value of ( |
n.earlystop |
a numeric value; the early stopping parameter. If the number of participants
treated at the current dose reaches |
extrasafe |
a logical value which specifies whether to implement a more strict safety rule (see more in the Details). |
ntrial |
a numeric value; the total number of simulated trials. |
seed |
a numeric value; the random seed for simulation. |
Details
Denote the current dose d. Let n_d and y_d represent the
number of participants treated at dose d and the number of participants
experienced DLT, respectively. Let p_d be the toxicity probability at
dose d. Also, denote \frac{y_d}{n_d} the observed toxicity rate
at the current dose.
The BOIN design uses the following decision rules: if
\frac{y_d}{n_d} is lower than or equal to the escalation boundary,
the decision is to escalate to the next higher dose; if \frac{y_d}{n_d}
is higher than the de-escalation boundary, the decision is to the next lower
dose; otherwise, the decision is to stay at the current dose.
Also, the BOIN design includes a dose exclusion rule. Let p_T represents
the pT DLT rate. If Pr(p_d > p_T | y_d , n_d ) > 0.95, dose d
and those higher than d are removed from the trial since they are deemed
excessively toxic.
The BOIN design has two early stopping rules: (1) stop the trial if the lowest
dose is eliminated due to toxicity, and no dose should be selected as the MTD; and
(2) stop the trial and select the MTD if the number of participants treated at the current
dose reaches n.earlystop.
For some applications, investigators may prefer a more strict safety rule for MTD selection
(This can be achieved by setting extrasafe == TRUE). If the isotonically-transformed
posterior mean of the selected MTD is above the EI, select the next lower dose as the final MTD.
Value
run.sim.b() returns:
(1) a dataframe ($selection) with each column showing:
the numbered index for each scenarios specified,
the name of the design,
the selection percentage at each dose level,
the percentage of early stopping without selecting the MTD,
the percentage of overdosing selection (POS),
the percentage of correct selection (PCS),
the percentage of underdosing selection (PUS),
the numbered index for the true MTD, respectively.
(2) a dataframe ($allocation) with each column showing:
the numbered index for each scenarios specified,
the name of the design,
the number of participants treated at each dose level,
the average number of participants treated,
the percentage of overdosing assignment (POA),
the percentage of correct assignment (PCA),
the percentage of underdosing assignment (PUA),
the numbered index for the true MTD, respectively.
(3) a list ($setup) containing user input 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.
Examples
run_sim_boin(p.true = c(0.25, 0.41, 0.45, 0.49, 0.53),
mtd.true = c(1,0,0,0,0),
pT = 0.25,
EI = c(0.15,0.35),
ncohort = 9,
cohortsize = 3,
startdose = 1,
DU.pp = 0.95,
n.earlystop = 100,
extrasafe = FALSE,
ntrial = 1000,
seed = 6)
Simulations for the G3 design.
Description
Conduct computer simulations for the G3 design.
Usage
run_sim_g3plus3(p.true,
mtd.true,
ncohort,
cohortsize = 3,
startdose = 1,
n.earlystop = 100,
ntrial = 1000,
seed = 6)
Arguments
p.true |
a vector or matrix containing the true toxicity probabilities of the investigational dose levels. |
mtd.true |
a numeric value or a vector which specifies the true MTD. |
ncohort |
a numeric value; the total number of cohorts. |
cohortsize |
a numeric value; the cohort size. |
startdose |
a numeric value; the starting dose level for the trial. |
n.earlystop |
a numeric value; the early stopping parameter. If the number of participants
treated at the current dose reaches |
ntrial |
a numeric value; the total number of simulated trials. |
seed |
a numeric value; the random seed for simulation. |
Details
Denote the current dose d. Let n_d and y_d represent the
number of participants treated at dose d and the number of participants
experienced DLT, respectively. Let p_d be the toxicity probability at
dose d. Also, denote \frac{y_d}{n_d} the observed toxicity rate
at the current dose.
The G3 design uses the following decision rules. For n is three or six,
we simply apply the 3+3 rules; otherwise, we use the following decision rules,
with EI being [0.2, 0.29]. If \frac{y_d}{n_d} is lower than the escalation
boundary (i.e. below the EI), the decision is to escalate to the next higher dose;
if \frac{y_d}{n_d} is between the escalation and de-escalation boundaries
(between the EI), the decision is to stay at the current dose; if
\frac{y_d}{n_d} is higher than the de-escalation boundary (i.e. above
the EI), the decision is to de-escalate to the next lower dose.
Also, the G3 design includes a dose exclusion rule. If Pr(p_d > 0.25 | y_d , n_d ) > 0.95,
dose d and those higher than d are removed from the trial since
they are deemed excessively toxic.
Three rules (1)-(3) with which G3 selects the final MTD after the trial is completed. (1) After removing doses based on the dose exclusion rule in (b), at the end of the trial, G3 selects the highest tested dose for which the decision is to de-escalate. (2) If no tested doses have a decision to de-escalate (meaning their decisions are either escalate or stay), G3 selects the highest tested dose as the MTD. (3) If the lowest dose has a decision to de-escalate, no dose is selected as the MTD.
The G3 design has two early stopping rules: (1) stop the trial if the lowest
dose is eliminated due to toxicity, and no dose should be selected as the MTD; and
(2) stop the trial and select the MTD if the number of participants treated at the current
dose reaches n.earlystop.
Value
run_sim_g3plus3() returns:
(1) a dataframe ($selection) with each column showing:
the numbered index for each scenarios specified,
the name of the design,
the selection percentage at each dose level,
the percentage of early stopping without selecting the MTD,
the percentage of overdosing selection (POS),
the percentage of correct selection (PCS),
the percentage of underdosing selection (PUS),
the numbered index for the true MTD, respectively.
(2) a dataframe ($allocation) with each column showing:
the numbered index for each scenarios specified,
the name of the design,
the number of participants treated at each dose level,
the average number of participants treated,
the percentage of overdosing assignment (POA),
the percentage of correct assignment (PCA),
the percentage of underdosing assignment (PUA),
the numbered index for the true MTD, respectively.
(3) a list ($setup) containing user input parameters.
References
To be added
Examples
run_sim_g3plus3(p.true = c(0.25, 0.41, 0.45, 0.49, 0.53),
mtd.true = c(1,0,0,0,0),
ncohort = 9,
cohortsize = 3,
startdose = 1,
n.earlystop = 100,
ntrial = 1000,
seed = 6)
Simulations for the i3+3 design.
Description
Conduct computer simulations for the i3+3 design.
Usage
run_sim_i3plus3(p.true,
mtd.true,
pT,
EI,
ncohort,
cohortsize = 3,
startdose = 1,
DU.pp = 0.95,
n.earlystop = 100,
extrasafe = FALSE,
ntrial = 1000,
seed = 6)
Arguments
p.true |
a vector or matrix containing the true toxicity probabilities of the investigational dose levels. |
mtd.true |
a numeric value or a vector which specifies the true MTD. |
pT |
a numeric value; the target DLT rate. |
EI |
a vector which specifies the equivalence interval (EI). |
ncohort |
a numeric value; the total number of cohorts. |
cohortsize |
a numeric value; the cohort size. |
startdose |
a numeric value; the starting dose level for the trial. |
DU.pp |
a numeric value; the cutoff to remove an overly toxic dose for safety.
We recommend the default value of ( |
n.earlystop |
a numeric value; the early stopping parameter. If the number of participants
treated at the current dose reaches |
extrasafe |
a logical value which specifies whether to implement a more strict safety rule (see more in the Details). |
ntrial |
a numeric value; the total number of simulated trials. |
seed |
a numeric value; the random seed for simulation. |
Details
Denote the current dose d. Let n_d and y_d represent the
number of participants treated at dose d and the number of participants
experienced DLT, respectively. Let p_d be the toxicity probability at
dose d. Also, denote \frac{y_d}{n_d} the observed toxicity rate
at the current dose.
The i3+3 design uses the following decision rules. If
\frac{y_d}{n_d} is lower than the escalation boundary (i.e. below
the EI), the decision is to escalate to the next higher dose; if
\frac{y_d}{n_d} is between the escalation and de-escalation boundaries
(i.e. inside the EI), the decision is to stay at the current dose; if
\frac{y_d}{n_d} is higher than the de-escalation boundary (i.e. above
the EI), there are two options: option one, if \frac{y_d-1}{n_d} is
lower than the escalation boundary (i.e., below the EI), the decision is
to stay at the current dose; option two, else if \frac{y_d-1}{n_d}
is equal to or higher than the escalation boundary, the decision is to
de-escalate to the next lower dose.
Also, the i3+3 design includes a dose exclusion rule. Let p_T represents
the target DLT rate. If Pr(p_d > p_T | y_d , n_d ) > 0.95, dose d
and those higher than d are removed from the trial since they are deemed
excessively toxic.
The i3+3 design has two early stopping rules: (1) stop the trial if the lowest
dose is eliminated due to toxicity, and no dose should be selected as the MTD; and
(2) stop the trial and select the MTD if the number of participants treated at the current
dose reaches n.earlystop.
For some applications, investigators may prefer a more strict safety rule for MTD selection
(This can be achieved by setting extrasafe == TRUE). If the isotonically-transformed
posterior mean of the selected MTD is above the EI, select the next lower dose as the final MTD.
Value
run_sim_i3plus3() returns:
(1) a dataframe ($selection) with each column showing:
the numbered index for each scenarios specified,
the name of the design,
the selection percentage at each dose level,
the percentage of early stopping without selecting the MTD,
the percentage of overdosing selection (POS),
the percentage of correct selection (PCS),
the percentage of underdosing selection (PUS),
the numbered index for the true MTD, respectively.
(2) a dataframe ($allocation) with each column showing:
the numbered index for each scenarios specified,
the name of the design,
the number of participants treated at each dose level,
the average number of participants treated,
the percentage of overdosing assignment (POA),
the percentage of correct assignment (PCA),
the percentage of underdosing assignment (PUA),
the numbered index for the true MTD, respectively.
(3) a list ($setup) containing user input parameters.
References
Liu M., Wang, SJ. and Ji, Y. (2020). The i3+3 Design for Phase I Clinical Trials, Journal of biopharmaceutical statistics, 30(2):294–304.
Examples
run_sim_i3plus3(p.true = c(0.25, 0.41, 0.45, 0.49, 0.53),
mtd.true = c(1,0,0,0,0),
pT = 0.25,
EI = c(0.2,0.3),
ncohort = 9,
cohortsize = 3,
startdose = 1,
DU.pp = 0.95,
n.earlystop = 100,
extrasafe = FALSE,
ntrial = 1000,
seed = 6)
Simulations for the mTPI2 design.
Description
Conduct computer simulations for the mTPI2 design.
Usage
run_sim_mtpi2(p.true,
mtd.true,
pT,
EI,
ncohort,
cohortsize = 3,
startdose = 1,
DU.pp = 0.95,
n.earlystop = 100,
ntrial = 1000,
seed = 6)
Arguments
p.true |
a vector or matrix containing the true toxicity probabilities of the investigational dose levels. |
mtd.true |
a numeric value or a vector which specifies the true MTD. |
pT |
a numeric value; the target DLT rate. |
EI |
a vector which specifies the equivalence interval (EI). |
ncohort |
a numeric value; the total number of cohorts. |
cohortsize |
a numeric value; the cohort size. |
startdose |
a numeric value; the starting dose level for the trial. |
DU.pp |
a numeric value; the cutoff to remove an overly toxic dose for safety.
We recommend the default value of ( |
n.earlystop |
a numeric value; the early stopping parameter. If the number of participants
treated at the current dose reaches |
ntrial |
a numeric value; the total number of simulated trials. |
seed |
a numeric value; the random seed for simulation. |
Details
Denote the current dose d. Let n_d and y_d represent the
number of participants treated at dose d and the number of participants
experienced DLT, respectively. Let p_d be the toxicity probability at
dose d. Also, denote \frac{y_d}{n_d} the observed toxicity rate
at the current dose.
The mTPI2 design divides the probability of DLT into equal-width intervals: underdosing, target dosing, and overdosing. Utilizing a Bayesian model, mTPI-2 updates the posterior probability estimates of DLTs. If the interval which maximizes the posterior probability is among the underdosing intervals, the decision is to escalate to the next higher dose; if the interval which maximizes the posterior probability is the target dosing interval, the decision is to stay at the current dose; if the interval which maximizes the posterior probability is among the overdosing intervals, the decision is to to de-escalate to the next lower dose.
Also, the mTPI2 design includes a dose exclusion rule. Let p_T represents
the pT DLT rate. If Pr(p_d > p_T | y_d , n_d ) > 0.95, dose d
and those higher than d are removed from the trial since they are deemed
excessively toxic.
The mTPI2 design has two early stopping rules: (1) stop the trial if the lowest
dose is eliminated due to toxicity, and no dose should be selected as the MTD; and
(2) stop the trial and select the MTD if the number of participants treated at the current
dose reaches n.earlystop.
Value
run_sim_mtpi2() returns:
(1) a dataframe ($selection) with each column showing:
the numbered index for each scenarios specified,
the name of the design,
the selection percentage at each dose level,
the percentage of early stopping without selecting the MTD,
the percentage of overdosing selection (POS),
the percentage of correct selection (PCS),
the percentage of underdosing selection (PUS),
the numbered index for the true MTD, respectively.
(2) a dataframe ($allocation) with each column showing:
the numbered index for each scenarios specified,
the name of the design,
the number of participants treated at each dose level,
the average number of participants treated,
the percentage of overdosing assignment (POA),
the percentage of correct assignment (PCA),
the percentage of underdosing assignment (PUA),
the numbered index for the true MTD, respectively.
(3) a list ($setup) containing user input parameters, such as pT, EI, nparticipants, etc.
References
Guo, W., Liu, S., & Yin, G. (2017). A more efficient Bayesian model for oncology dose-finding trials with toxicity probability interval. Clinical Trials, 14(1), 16-26.
Examples
run_sim_mtpi2(p.true = c(0.25, 0.41, 0.45, 0.49, 0.53),
mtd.true = c(1,0,0,0,0),
pT = 0.25,
EI = c(0.15,0.35),
ncohort = 9,
cohortsize = 3,
startdose = 1,
DU.pp = 0.95,
n.earlystop = 100,
ntrial = 1000,
seed = 6)
Run Simulations for Phase I Dose-Finding Designs
Description
Generic function to conduct computer simulations for phase I dose-finding designs.
Usage
run_simulation(design, p.true, mtd.true, ...)
## S3 method for class 'boin_design'
run_simulation(design, p.true, mtd.true, ...)
## S3 method for class 'i3plus3_design'
run_simulation(design, p.true, mtd.true, ...)
## S3 method for class 'mtpi2_design'
run_simulation(design, p.true, mtd.true, ...)
## S3 method for class 'g3plus3_design'
run_simulation(design, p.true, mtd.true, ...)
## S3 method for class 'threethree_design'
run_simulation(design, p.true, mtd.true, ...)
## Default S3 method:
run_simulation(design, p.true, mtd.true, ...)
Arguments
design |
A design object created by one of the design constructor functions
( |
p.true |
A vector or matrix containing the true toxicity probabilities of the investigational dose levels. |
mtd.true |
A numeric value or vector specifying the true MTD. |
... |
Additional arguments passed to methods. |
Value
A list containing 'selection' (a dataframe showing selection percentages and metrics POS, PCS, PUS), 'allocation' (a dataframe showing participant allocation across dose levels), and 'setup' (a list containing design parameters and simulation settings).
Examples
# Create design specifications
boin <- design_boin(pT = 0.25, EI = c(0.15, 0.35), ncohort = 10)
i3 <- design_i3plus3(pT = 0.25, EI = c(0.2, 0.3), ncohort = 10)
# Define toxicity scenarios
p.true <- matrix(c(0.05, 0.10, 0.20, 0.30, 0.45,
0.10, 0.15, 0.25, 0.35, 0.50),
nrow = 2, byrow = TRUE)
# Binary matrix indicating true MTD for each scenario (dose 3 for both)
mtd.true <- matrix(c(0, 0, 1, 0, 0,
0, 0, 1, 0, 0),
nrow = 2, byrow = TRUE)
# Run simulations
sim_boin <- run_simulation(boin, p.true = p.true, mtd.true = mtd.true)
sim_i3 <- run_simulation(i3, p.true = p.true, mtd.true = mtd.true)
Select the maximum tolerated dose (MTD) using isotonic regression
Description
Select the maximum tolerated dose (MTD) when the trial is completed using isotonic regression
Usage
select_mtd(method,
pT,
EI,
n_obs,
y_obs,
DU.pp=0.95,
extrasafe = FALSE)
Arguments
method |
the design name; only i3+3 and BOIN are accepted. |
pT |
a numeric value; the target DLT rate. |
EI |
a vector which specifies the equivalence interval (EI). |
n_obs |
a vector containing the number of participants treated at each dose level. |
y_obs |
a vector containing the number of participants who experienced dose-limiting toxicity at each dose level. |
DU.pp |
a numeric value; the cutoff to remove an overly toxic dose for safety.
We recommend the default value of ( |
extrasafe |
a logical value which specifies whether to implement a more strict safety rule. |
Details
select_mtd() selects the MTD based on isotonic estimates of toxicity
probabilities. If there are ties, we select from the ties the highest dose
level when the estimate of the DLT rate is smaller than the target, or the
lowest dose level when the estimate of the DLT rate is greater than the target.
The isotonic estimates are obtained by the pooled-adjacent-violators algorithm
(PAVA) (Barlow, 1972).
Value
select_mtd() returns the selected MTD dose ($d_selected)
Summarize after conducting simulations
Description
Summarize after conducting simulations
Usage
summarize_metric(select.perc,
stop.perc,
nptsdose,
npts,
mtd.true)
Arguments
select.perc |
the selection percentage for each dose. |
stop.perc |
the percentage of early stopping without selecting the MTD. |
nptsdose |
the number of participants treated for each dose. |
npts |
the average number of participants treated. |
mtd.true |
a vector (or a matrix) with the same dimension as
the vector (or matrix) containing the true toxicity probabilities ( |
Value
summarize_metric() returns:
(1) a dataframe ($selection) with each column showing:
the numbered index for each scenarios specified,
the selection percentage at each dose level,
the percentage of early stopping without selecting the MTD,
the percentage of overdosing selection (POS),
the percentage of correct selection (PCS),
the percentage of underdosing selection (PUS), respectively.
(2) a dataframe ($allocation) with each column showing:
the numbered index for each scenarios specified,
the number of participants treated at each dose level,
the average number of participants treated,
the percentage of overdosing allocation (POA),
the percentage of correct allocation (PCA),
the percentage of underdosing allocation (PUA), respectively.
Examples
summarize_metric(select.perc = c(0.588, 0.218, 0.025, 0.0, 0.0, 0.0),
stop.perc = 0.168,
nptsdose = c(20.53, 9.03, 2.48, 0.29, 0.01, 0.00),
npts = 32.4,
mtd.true = c(1,0,0,0,0,0))