simFastBOIN (version 1.3.2)

sim_boin: Run BOIN Simulation with Operating Characteristics

Description

Execute multiple BOIN trial simulations and compute operating characteristics. Combines patient enrollment, toxicity tracking, isotonic regression, and MTD selection into a single streamlined function.

Usage

sim_boin(
  n_trials = 10000,
  target,
  p_true,
  n_cohort,
  cohort_size,
  p_saf = NULL,
  p_tox = NULL,
  n_earlystop = 18,
  cutoff_eli = 0.95,
  extrasafe = FALSE,
  offset = 0.05,
  n_earlystop_rule = "with_stay",
  titration = FALSE,
  min_mtd_sample = 1,
  boundMTD = FALSE,
  return_details = FALSE,
  verbose = FALSE,
  seed = 123
)

Value

A list containing:

detailed_results

List of length n_trials (if return_details = TRUE). Each element contains: n_pts, n_tox, mtd, iso_est, reason, cohorts_completed. NULL if return_details = FALSE.

summary

Object of class "boin_summary" containing: p_true (true toxicity probabilities), mtd_selection_percent (MTD selection rate for each dose and percent with no MTD), avg_n_pts (average patients per dose), avg_n_tox (average DLTs per dose), avg_total_n_pts (average total patients per trial), avg_total_n_tox (average total DLTs per trial).

Arguments

n_trials

Numeric. Number of trials to simulate. Default is 10000.

target

Numeric. Target toxicity probability (e.g., 0.30 for 30%).

p_true

Numeric vector. True toxicity probabilities for each dose.

n_cohort

Numeric. Maximum number of cohorts per trial.

cohort_size

Numeric vector or scalar. Patients per cohort.

p_saf

Numeric. Highest toxicity probability deemed acceptable for safety. Default is 0.6 * target. Used with p_tox for safety/efficacy dose identification.

p_tox

Numeric. Lowest toxicity probability deemed unacceptable for toxicity. Default is 1.4 * target. Used with p_saf for safety/efficacy dose identification.

n_earlystop

Numeric. Sample size triggering early stopping. Default is 18.

cutoff_eli

Numeric. Cutoff probability for dose elimination. Default is 0.95.

extrasafe

Logical. Apply extra safety stopping rule at lowest dose. Default is FALSE.

offset

Numeric. Offset for safety cutoff when extrasafe = TRUE. Default is 0.05.

n_earlystop_rule

Character. Early stopping rule: "with_stay" or "simple". Default is "with_stay".

titration

Logical. Perform accelerated dose titration phase. Default is FALSE.

min_mtd_sample

Numeric. Minimum patients required for MTD consideration. Default is 1.

boundMTD

Logical. Impose constraint that MTD's isotonic estimate <= lambda_d. Default is FALSE.

return_details

Logical. If TRUE, return detailed trial-level results. If FALSE, return summary only. Default is FALSE.

verbose

Logical. If TRUE, print progress messages to console. If FALSE, run silently. Default is FALSE.

seed

Numeric. Random seed for reproducibility. Default is 123.

Details

The function executes the following workflow:

1. Generate patient enrollment and toxicity data via get_pts_and_tox

2. Apply isotonic regression via isotonic_regression

3. Select MTD via select_mtd

4. Compute operating characteristics (MTD selection rates, sample sizes, DLT counts)

Progress messages are printed to console only if verbose = TRUE. If return_details = TRUE, detailed trial-level results are returned; otherwise, only summary statistics are computed for efficiency.

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

# \donttest{
# Basic BOIN simulation (silent mode)
result <- sim_boin(
  n_trials = 10000,
  target = 0.30,
  p_true = c(0.10, 0.25, 0.40, 0.55, 0.70),
  n_cohort = 10,
  cohort_size = 3,
  seed = 123
)

# With progress messages
result_verbose <- sim_boin(
  n_trials = 10000,
  target = 0.30,
  p_true = c(0.10, 0.25, 0.40, 0.55, 0.70),
  n_cohort = 10,
  cohort_size = 3,
  verbose = TRUE,
  seed = 123
)
# }