Quick Start Guide

In tsdf: Two-/Three-Stage Designs for Phase 1&2 Clinical Trials

This guide introduces the basic workflow of tsdf. For additional details, see the documentation for individual functions.

Installation

Install the package from R with:

install.packages("tsdf")

Then load the package:

library(tsdf)

The remaining sections give short examples of the main functions.

Zhong's 2-/3-stage Phase II designs

To calculate Zhong's two- or three-stage design, specify the left-side type I error (alpha1), right-side type I error (alpha2), type II error (beta), minimal response rate (pc), and postulated response rate (pe). The stage argument should be set to 2 or 3.

The following example computes a two-stage design:

# type I errors
alpha1 <- 0.15
alpha2 <- 0.10

# type II error
beta <- 0.15

# response rates
pc <- 0.25
pe <- pc + 0.20

# two-stage design
out <- opt.design(alpha1, alpha2, beta, pc, pe, stage = 2)

out is an object of class opt.design. The print method shows the recommended design and its operating characteristics:

print(out)

Alpha-spending methods are available for both two- and three-stage designs. opt.design() uses the Hwang-Shih-DeCani spending function, with sf.param controlling the shape of the spending rule. For two-stage designs, the default is NULL, which means no alpha-spending is used. For three-stage designs, the default is 4. For example, to use a Pocock-like spending function, set sf.param = 1:

opt.design(alpha1, alpha2, beta, pc, pe, stage = 2, sf.param = 1)

Decision table for Phase I dose-finding

dec.table() generates a decision table for a three-stage dose-finding design. alpha.l (left side), alpha.r (right side), and alpha.u (right-side type I error for "DU", usually smaller than alpha.r) control the decision boundaries. pt is the target toxicity level and may be given as either a single value or an interval.

This procedure also supports alpha-spending through the sf.param argument, which has the same interpretation as in opt.design(). The default is 4.

# cohort sizes at each stage
n <- rep(3, 3)

# type I errors
alpha.l <- 0.6
alpha.r <- 0.4
alpha.u <- 0.2

# target toxicity
pt <- 0.3

# generate the decision table
out <- dec.table(alpha.l, alpha.r, alpha.u, pt, n)

out is an object of class dec.table that contains the decision table, realized error rates, and input settings. In most cases, it is better to use the provided S3 methods than to extract components manually.

View the decision table with:

print(out)

Plot the decision boundaries with:

plot(out)

Dose-finding simulations

dec.sim() and sl.sim() run dose-finding simulations from a user-supplied decision table. To run a simulation, provide a decision table, the true toxicity probabilities for each dose level, the starting dose level (default: the lowest dose), and the number of simulated trials (default: 1000).

dec.sim() runs a single scenario. sl.sim() runs a list of scenarios stored in a .csv or .txt file.

The simulation functions expect the decision table to be a matrix- or data-frame-like object with sample sizes as column names. If you start from dec.table(), convert out$table before passing it to the simulation functions:

# true toxicity probabilities
truep <- c(0.3, 0.45, 0.5, 0.6)

# generate a decision table
dt <- dec.table(0.6, 0.4, 0.2, 0.3, c(3, 3, 3))

# convert the table object to a plain matrix for simulation
sim_table <- matrix(
  as.character(dt$table),
  nrow = nrow(dt$table),
  dimnames = dimnames(dt$table)
)

# run one simulation scenario
out1 <- dec.sim(truep, sim_table, start.level = 2, nsim = 1000)

The package also includes a sample scenario list:

test.file <- system.file("extdata", "testS.csv", package = "tsdf")

Run simulations across all scenarios with:

out2 <- sl.sim(sim_table, test.file)

out1 is an object of class dec.sim. When the scenario file contains more than one scenario, out2 has class c("sl.sim", "dec.sim"). Summary and plot methods are available for these objects. For example, the following command reports commonly used summary statistics:

# target toxicity for each scenario
pt <- c(0.3, 0.4)
summary(out2, pt)

There are four plot types for a dec.sim object. The s argument selects the scenario to display, and pt gives the target toxicity for each scenario. See ?plot.dec.sim for details:

# scenario information (true toxicity)
plot(out2, s = 2, pt = c(0.3, 0.4), type = "s")

# probability of selecting each dose as the MTD
plot(out2, s = 2, pt = c(0.3, 0.4), type = "prob")

# average number of patients treated at each dose
plot(out2, s = 2, pt = c(0.3, 0.4), type = "np")

# average number of DLTs at each dose
plot(out2, s = 2, pt = c(0.3, 0.4), type = "dlt")

To display all plot types in a single figure, run:

plot(out2, pt = c(0.3, 0.4), type = "all", cex = 0.7)

Scenario list and customized table format

The .csv or .txt files used by sl.sim() look like this:

sl <- system.file("extdata", "testS.csv", package = "tsdf")
knitr::kable(read.table(sl, header = TRUE, sep = ","))

This example is stored in inst/extdata/testS.csv and can be located with system.file(). The file should include:

• Start Dose: the starting dose level.
• N Trials: the number of simulated trials.
• Dose*: the true toxicity probability at each dose level.

If scenarios contain different numbers of dose levels, the raw file does not need explicit NA values; blank cells are sufficient.

Both dec.sim() and sl.sim() also support user-supplied decision tables. The table can be a matrix, data.frame, or similar rectangular object in R. The user is responsible for ensuring that the table is a valid dose-finding decision table. In particular, the column names should be the actual cumulative sample sizes rather than the default names created by read.table(), such as X.* or V.*.

For example, the following code reads the sample decision table included in the package:

table.file <- system.file("extdata", "decTable.csv", package = "tsdf")
dec <- read.csv(table.file, row.names = 1, check.names = FALSE)
colnames(dec)

After importing the table, it should have the following format:

knitr::kable(dec)

tsdf documentation built on April 26, 2026, 1:06 a.m.