Package 'FIND'

Title: Objective Comparison of Phase I Dose-Finding Designs
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.
Authors: Yuan Ji [aut], Yunxuan Zhang [aut, cre]
Maintainer: Yunxuan Zhang <[email protected]>
License: MIT + file LICENSE
Version: 0.1.1
Built: 2026-05-23 08:48:10 UTC
Source: https://github.com/cran/FIND

Help Index

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 design_* functions) or legacy arguments (`3+3`, BOIN, mTPI2, i3+3, G3).

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 (design_boin, design_i3plus3, design_mtpi2, design_g3plus3, or design_3plus3).
...

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 (pTp_T).
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 dd. Let ndn_d and ydy_d represent the number of participants treated at dose dd and the number of participants experienced DLT, respectively. Let pdp_d be the toxicity probability at dose dd. Also, denote ydnd\frac{y_d}{n_d} the observed toxicity rate at the current dose.

The BOIN design uses the following decision rules: if ydnd\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 ydnd\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 pTp_T represents the target DLT rate. If Pr(pd>pT∣yd,nd)>0.95Pr(p_d > p_T | y_d , n_d ) > 0.95, dose dd and those higher than dd 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 dd. Let ndn_d and ydy_d represent the number of participants treated at dose dd and the number of participants experienced DLT, respectively. Let pdp_d be the toxicity probability at dose dd. Also, denote ydnd\frac{y_d}{n_d} the observed toxicity rate at the current dose.

The G3 design uses the following decision rules. For nn 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 ydnd\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 ydnd\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 ydnd\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(pd>0.25∣yd,nd)>0.95Pr(p_d > 0.25 | y_d , n_d ) > 0.95, dose dd and those higher than dd 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 (pTp_T).
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 dd. Let ndn_d and ydy_d represent the number of participants treated at dose dd and the number of participants experienced DLT, respectively. Let pdp_d be the toxicity probability at dose dd. Also, denote ydnd\frac{y_d}{n_d} the observed toxicity rate at the current dose.

The i3+3 design uses the following decision rules.

If ydnd\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 ydnd\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 ydnd\frac{y_d}{n_d} is higher than the de-escalation boundary (i.e. above the EI), there are two options: option one, if yd−1nd\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 yd−1nd\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 pTp_T represents the target DLT rate. If Pr(pd>pT∣yd,nd)>0.95Pr(p_d > p_T | y_d , n_d ) > 0.95, dose dd and those higher than dd 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 (pTp_T).
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 dd. Let ndn_d and ydy_d represent the number of participants treated at dose dd and the number of participants experienced DLT, respectively. Let pdp_d be the toxicity probability at dose dd. Also, denote ydnd\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 pTp_T represents the target DLT rate. If Pr(pd>pT∣yd,nd)>0.95Pr(p_d > p_T | y_d , n_d ) > 0.95, dose dd and those higher than dd 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 run_simulation()) or legacy arguments (`3+3`, BOIN, mTPI2, i3+3, G3).

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 (DU.pp=0.95) for general use.
n.earlystop

a numeric value; the early stopping parameter. If the number of participants treated at the current dose reaches n.earlystop, stop the trial and select the MTD based on the observed data. The default value n.earlystop=100 essentially turns off this type of early stopping.
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 dd. Let ndn_d and ydy_d represent the number of participants treated at dose dd and the number of participants experienced DLT, respectively. Let pdp_d be the toxicity probability at dose dd. Also, denote ydnd\frac{y_d}{n_d} the observed toxicity rate at the current dose.

The BOIN design uses the following decision rules: if ydnd\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 ydnd\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 pTp_T represents the pT DLT rate. If Pr(pd>pT∣yd,nd)>0.95Pr(p_d > p_T | y_d , n_d ) > 0.95, dose dd and those higher than dd 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 n.earlystop, stop the trial and select the MTD based on the observed data. The default value n.earlystop=100 essentially turns off this type of early stopping.
ntrial

a numeric value; the total number of simulated trials.
seed

a numeric value; the random seed for simulation.

Details

Denote the current dose dd. Let ndn_d and ydy_d represent the number of participants treated at dose dd and the number of participants experienced DLT, respectively. Let pdp_d be the toxicity probability at dose dd. Also, denote ydnd\frac{y_d}{n_d} the observed toxicity rate at the current dose.

The G3 design uses the following decision rules. For nn 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 ydnd\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 ydnd\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 ydnd\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(pd>0.25∣yd,nd)>0.95Pr(p_d > 0.25 | y_d , n_d ) > 0.95, dose dd and those higher than dd 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 (DU.pp=0.95) for general use.
n.earlystop

a numeric value; the early stopping parameter. If the number of participants treated at the current dose reaches n.earlystop, stop the trial and select the MTD based on the observed data. The default value n.earlystop=100 essentially turns off this type of early stopping.
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 dd. Let ndn_d and ydy_d represent the number of participants treated at dose dd and the number of participants experienced DLT, respectively. Let pdp_d be the toxicity probability at dose dd. Also, denote ydnd\frac{y_d}{n_d} the observed toxicity rate at the current dose.

The i3+3 design uses the following decision rules. If ydnd\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 ydnd\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 ydnd\frac{y_d}{n_d} is higher than the de-escalation boundary (i.e. above the EI), there are two options: option one, if yd−1nd\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 yd−1nd\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 pTp_T represents the target DLT rate. If Pr(pd>pT∣yd,nd)>0.95Pr(p_d > p_T | y_d , n_d ) > 0.95, dose dd and those higher than dd 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 (DU.pp=0.95) for general use.
n.earlystop

a numeric value; the early stopping parameter. If the number of participants treated at the current dose reaches n.earlystop, stop the trial and select the MTD based on the observed data. The default value n.earlystop=100 essentially turns off this type of early stopping.
ntrial

a numeric value; the total number of simulated trials.
seed

a numeric value; the random seed for simulation.

Details

Denote the current dose dd. Let ndn_d and ydy_d represent the number of participants treated at dose dd and the number of participants experienced DLT, respectively. Let pdp_d be the toxicity probability at dose dd. Also, denote ydnd\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 pTp_T represents the pT DLT rate. If Pr(pd>pT∣yd,nd)>0.95Pr(p_d > p_T | y_d , n_d ) > 0.95, dose dd and those higher than dd 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 (design_boin, design_i3plus3, design_mtpi2, design_g3plus3, or design_3plus3).
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 (DU.pp=0.95) for general use.
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 ($p.true). It should takes value of 0 or 1, and 1 specifies the true MTD.

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