Getting Started

Introduction

This vignette serves as an introductory guide to the phase12designs package. In this tutorial, we will walk through how to (1) install and load the package, (2) simulate a single scenario, and (3) simulate multiple scenarios For demonstrative purposes, we will be using the uTPI method and its corresponding functions to run the simulations. Users are encouraged to consult the reference manual for additional specifications required by alternative methods.

Installation

The development version of phase12designs can be installed from GitHub using the devtools package.

install.packages("devtools")
devtools::install_github("Angela-Cao/phase12designs")

After installation, load the package with:

library(phase12designs)

Simulating a Single Trial Scenario

To simulate a single early-phase clinical trial scenario, select an oc_* function. These functions compute operating characteristics under fixed trial conditions for a specified design. Here, we use the oc_utpi() function to generate a scenario with target toxicity probability of \(\phi_T = 0.35\) and lower efficacy rate limit of \(\zeta_E = 0.25\). This call simulates 10,000 independent trials with 10 cohorts of 3 patients each, using the uTPI model. Since no explicit dose-level probabilities are provided, random scenarios are internally generated.

results <- oc_utpi(
  ndose = 5,
  target_t = 0.35,
  lower_e = 0.25,
  ncohort = 10,
  cohortsize = 3,
  startdose = 1,
  utilitytype = 1,
  u1 = 60,     # only used if utilitytype != 1 or 2
  u2 = 40,
  prob = NULL,
  ntrial = 10000
)

The function returns a summary of key operating characteristics across all simulated trials:

To view the summarized results:

print(results)

This output allows researchers to assess how well the design performs under the specified assumptions.

Fixed Scenarios

To evaluate the performance of a design under a fixed, user-defined trial scenario, define a named list containing the following components:

For example,

prob_fixed <- list(
  pE = c(0.4, 0.5, 0.6, 0.6, 0.6),
  pT = c(0.1, 0.2, 0.3, 0.4, 0.4),
  obd = 3,
  mtd = 2
)

This example assumes increasing efficacy and toxicity probabilities across five dose levels, with the third dose as the true OBD and the second dose as the true MTD. To simulate under this fixed scenario, pass prob_fixed (instead of NULL) to the prob argument in the oc_utpi() function:

results_fixed <- oc_utpi(
  ndose = 5,
  target_t = 0.35,
  lower_e = 0.25,
  prob = prob_fixed,
)

print(results_fixed)

Customizing Utility Parameters

To use a custom utility structure, assign utilitytype a value other than 1 or 2, which refer to predefined weights, and specify the desired weights through the u1 and u2 parameters. For example:

results_custom <- oc_utpi(
  ndose = 5,
  target_t = 0.35,
  lower_e = 0.25,
  utilitytype = 3,
  u1 = 50,
  u2 = 30
)

This flexibility allows users to tailor the relative importance of efficacy and toxicity outcomes to suit specific trial needs.

Simulating Multiple Scenarios

To evaluate a design’s performance across a range of clinical scenarios, select a simulate_* functions. These function evaluate operating characteristics under multiple configurations, such as varying number of cohorts, while optionally holding other parameters fixed.

Example Usage

In this example, we demonstrate simulate_utpi(), which uses the oc_utpi function internally to evaluate operating characteristics. Here, we simulate trials with 5 dose levels, a target toxicity probability of \(\phi_T = 0.45\), and a lower efficacy rate limit of \(\zeta_E = 0.15\). We vary the number of cohorts from 8 to 12 and use the default cohort size of 3.

simulate_utpi(
  ndose = 5,
  ssizerange = 8:12,
  target_t = 0.45,
  lower_e = 0.35,
  cohortsize = 3,
  startdose = 1,
  ntrial = 1000,
  utilitytype = 1
)

By default, if the prob parameter is left as NULL, the function generates a different random scenario for each iteration. To simulate under a fixed probability scenario, pass a named list to the prob argument (see Fixed Scenarios).

Each simulation replicates the trial process ntrial times for combinations of:

For each specified OBD, the function saves results in a subfolder.