Title:	Object-Oriented Implementation of Dose Escalation Designs
Version:	2.0.0
Description:	Implements a wide range of dose escalation designs. The focus is on model-based designs, ranging from classical and modern continual reassessment methods (CRMs) based on dose-limiting toxicity endpoints to dual-endpoint designs taking into account a biomarker/efficacy outcome. Bayesian inference is performed via MCMC sampling in JAGS, and it is easy to setup a new design with custom JAGS code. However, it is also possible to implement 3+3 designs for comparison or models with non-Bayesian estimation. The whole package is written in a modular form in the S4 class system, making it very flexible for adaptation to new models, escalation or stopping rules. Further details are presented in Sabanes Bove et al. (2019) <doi:10.18637/jss.v089.i10>.
License:	GPL-2 | GPL-3 [expanded from: GPL (≥ 2)]
URL:	https://github.com/openpharma/crmPack, https://openpharma.github.io/crmPack/
BugReports:	https://github.com/openpharma/crmPack/issues
Depends:	ggplot2 (≥ 3.0.0), graphics, R (≥ 4.1.0)
Imports:	checkmate (≥ 2.2.0), dplyr, futile.logger, GenSA, gridExtra, kableExtra, knitr, lifecycle, magrittr, methods, mvtnorm, parallel, parallelly, Rdpack, rjags, rlang, survival, tibble, tidyselect (≥ 1.2.0), tools, utils
Suggests:	bookdown, broom, covr, data.tree, DiagrammeR, ggmcmc, quarto (≥ 1.4), rmarkdown, stringr, testthat (≥ 3.0.0), tidyr, vdiffr, withr
VignetteBuilder:	knitr, quarto
Config/testthat/edition:	3
Encoding:	UTF-8
Language:	en-US
LazyLoad:	yes
RoxygenNote:	7.3.3
RdMacros:	Rdpack
Collate:	'CrmPackClass-class.R' 'CrmPackClass-methods.R' 'Data-validity.R' 'helpers.R' 'Data-class.R' 'helpers_data.R' 'Data-methods.R' 'Rules-validity.R' 'Rules-class.R' 'ModelParams-validity.R' 'ModelParams-class.R' 'Model-validity.R' 'helpers_jags.R' 'Model-class.R' 'Design-validity.R' 'Design-class.R' 'McmcOptions-validity.R' 'McmcOptions-class.R' 'McmcOptions-methods.R' 'Samples-validity.R' 'Samples-class.R' 'logger.R' 'helpers_covr.R' 'mcmc.R' 'Simulations-validity.R' 'Simulations-class.R' 'helpers_broom.R' 'helpers_rules.R' 'Model-methods.R' 'checkmate.R' 'Rules-methods.R' 'Design-methods.R' 'fromQuantiles.R' 'Samples-methods.R' 'Simulations-methods.R' 'crmPack-package.R' 'helpers_design.R' 'helpers_knitr.R' 'helpers_knitr_CohortSize.R' 'helpers_knitr_Design.R' 'helpers_knitr_GeneralData.R' 'helpers_knitr_GeneralModel.R' 'helpers_knitr_Increments.R' 'helpers_knitr_NextBest.R' 'helpers_knitr_SafetyWindow.R' 'helpers_knitr_Stopping.R' 'helpers_model.R' 'helpers_samples.R' 'helpers_simulations.R' 'utils-pipe.R' 'utils.R'
NeedsCompilation:	no
Packaged:	2025-11-29 07:54:03 UTC; Daniel
Author:	Daniel Sabanes Bove [aut, cre], Wai Yin Yeung [aut], Burak Kuersad Guenhan [aut], Giuseppe Palermo [aut], Thomas Jaki [aut], Jiawen Zhu [aut], Ziwei Liao [aut], Dimitris Kontos [aut], Marlene Schulte-Goebel [aut], Doug Kelkhoff [aut], Oliver Boix [aut], Robert Adams [aut], Clara Beck [aut], John Kirkpatrick [aut], Wojciech Wójciak [aut], Guanya Peng [aut], Prerana Chandratre [aut], F. Hoffmann-La Roche AG [cph, fnd], Merck Healthcare KGaA [cph, fnd], Bayer AG [cph, fnd], RPACT GmbH [cph, fnd]
Maintainer:	Daniel Sabanes Bove <daniel.sabanes_bove@rconis.com>
Repository:	CRAN
Date/Publication:	2025-11-29 13:30:07 UTC

Object-oriented implementation of CRM designs

Description

Object-oriented implementation of CRM designs

Author(s)

Maintainer: Daniel Sabanes Bove daniel.sabanes_bove@rconis.com

Authors:

• Wai Yin Yeung winnie.yeung@roche.com

• Burak Kuersad Guenhan burakgunhan@gmail.com

• Giuseppe Palermo giuseppe.palermo@roche.com

• Thomas Jaki jaki.thomas@gmail.com

• Jiawen Zhu zhu.jiawen@gene.com

• Ziwei Liao ziwei.liao.fdu@gmail.com

• Dimitris Kontos dimitris.kontos@bayer.com

• Marlene Schulte-Goebel marlene.schulte-goebel@merckgroup.com

• Doug Kelkhoff doug.kelkhoff@gmail.com (ORCID)

• Oliver Boix oliver.boix@bayer.com

• Robert Adams robert.adams@bayer.com

• Clara Beck clara.beck@bayer.com

• John Kirkpatrick john@puzzledface.net

• Wojciech Wójciak wojciech.wojciak@gmail.com

• Guanya Peng

• Prerana Chandratre

Other contributors:

• F. Hoffmann-La Roche AG [copyright holder, funder]

• Merck Healthcare KGaA [copyright holder, funder]

• Bayer AG [copyright holder, funder]

• RPACT GmbH [copyright holder, funder]

References

Sabanés Bové D, Yeung WY, Palermo G, Jaki T (2019). “Model-Based Dose Escalation Designs in R with crmPack.” Journal of Statistical Software, 89(10), 1–22. doi:10.18637/jss.v089.i10.

See Also

Useful links:

• https://github.com/openpharma/crmPack

• https://openpharma.github.io/crmPack/

• Report bugs at https://github.com/openpharma/crmPack/issues

Pipe operator

Description

See magrittr::%>% for details.

Usage

lhs %>% rhs

Arguments

Value

The result of calling rhs(lhs).

Combine Two Stopping Rules with AND

Description

The method combining two atomic stopping rules.

Usage

## S4 method for signature 'Stopping,Stopping'
e1 & e2

Arguments

Value

The StoppingAll object.

Examples

## Example of combining two atomic stopping rules with an AND ('&') operator

myStopping1 <- StoppingMinCohorts(nCohorts = 3)
myStopping2 <- StoppingTargetProb(target = c(0.2, 0.35), prob = 0.5)

myStopping <- myStopping1 & myStopping2

Combine an Atomic Stopping Rule and a Stopping List with AND

Description

The method combining an atomic stopping rule and a stopping list.

Usage

## S4 method for signature 'Stopping,StoppingAll'
e1 & e2

Arguments

Value

The modified StoppingAll object.

Examples

## Example of combining an atomic stopping rule with a list of stopping rules
## with an AND ('&') operator

myStopping1 <- StoppingMinCohorts(nCohorts = 3)
myStopping2 <- StoppingTargetProb(target = c(0.2, 0.35), prob = 0.5)

myStopping3 <- StoppingMinPatients(nPatients = 20)

myStopping <- myStopping3 & (myStopping1 | myStopping2)

Combine a Stopping List and an Atomic Stopping Rule with AND

Description

The method combining a stopping list and an atomic stopping rule.

Usage

## S4 method for signature 'StoppingAll,Stopping'
e1 & e2

Arguments

Value

The modified StoppingAll object.

Examples

## Example of combining a list of stopping rules with an atomic stopping rule
## with an AND ('&') operator

myStopping1 <- StoppingMinCohorts(nCohorts = 3)
myStopping2 <- StoppingTargetProb(target = c(0.2, 0.35), prob = 0.5)

myStopping3 <- StoppingMinPatients(nPatients = 20)

myStopping <- (myStopping1 | myStopping2) & myStopping3

CohortSize

Description

CohortSize is a class for cohort sizes.

Usage

.DefaultCohortSize()

.DefaultCohortSize()

Note

Typically, end users will not use the DefaultCohortSize() function.

Typically, end users will not use the DefaultCohortSize() function.

See Also

CohortSizeRange, CohortSizeDLT, CohortSizeConst, CohortSizeParts, CohortSizeMin, CohortSizeMin.

CohortSizeConst

Description

CohortSizeConst is the class for fixed and constant size of cohort.

Usage

CohortSizeConst(size)

.DefaultCohortSizeConst()

Arguments

Slots

size

(integer)
cohort size.

Note

Typically, end users will not use the .DefaultCohortSizeConst() function.

Examples

# Cohort of size 3, constant along the study.
my_size <- CohortSizeConst(size = 3)

CohortSizeDLT

Description

CohortSizeDLT is the class for cohort size based on number of DLTs.

Usage

CohortSizeDLT(intervals, cohort_size)

.DefaultCohortSizeDLT()

Arguments

Slots

intervals

(integer)
a vector with the left bounds of the relevant DLT intervals.

cohort_size

(integer)
a vector with the cohort sizes corresponding to the elements of intervals.

Note

Typically, end users will not use the .DefaultCohortSizeDLT() function.

Examples

# Rule for having cohort of size 1 until no DLT is observed and having cohort
# of size 3 as soon as 1 DLT is observed.
my_size <- CohortSizeDLT(intervals = c(0, 1), cohort_size = c(1, 3))

CohortSizeMax

Description

CohortSizeMax is the class for cohort size that is based on maximum of multiple cohort size rules. The cohort_sizes slot stores a set of cohort size rules, which are again the objects of class CohortSize. The maximum of these individual cohort sizes is taken to give the final cohort size.

Usage

.DefaultCohortSizeMax()

CohortSizeMax(cohort_sizes)

Arguments

Slots

cohort_sizes

(list)
a list of cohort size rules, i.e. objects of class CohortSize.

Note

Typically, end users will not use the .DefaultCohortSizeMax() function.

Examples

# Rule for cohort of size 1 for doses <30 and cohort of size 3 for doses >=30.
my_size1 <- CohortSizeRange(intervals = c(0, 10), cohort_size = c(1, 3))

# Rule for cohort of size 1 until no DLT were observed and cohort of size 3
# as soon as 1 DLT is observed.
my_size2 <- CohortSizeDLT(intervals = c(0, 1), cohort_size = c(1, 3))

# Cohort size rules of class 'CohortSizeMax' which will then be combined with
# the 'max' operation.
mySize <- CohortSizeMax(cohort_sizes = list(my_size1, my_size2))

CohortSizeMin

Description

CohortSizeMin is the class for cohort size that is based on minimum of multiple cohort size rules. The cohort_sizes slot stores a set of cohort size rules, which are again the objects of class CohortSize. The minimum of these individual cohort sizes is taken to give the final cohort size.

Usage

CohortSizeMin(cohort_sizes)

.DefaultCohortSizeMin()

Arguments

Slots

cohort_sizes

(list)
a list of cohort size rules, i.e. objects of class CohortSize.

Note

Typically, end users will not use the .DefaultCohortSizeMin() function.

Examples

# Rule for cohort of size 1 for doses <30 and cohort of size 3 for doses >=30.
my_size1 <- CohortSizeRange(intervals = c(0, 10), cohort_size = c(1, 3))

# Rule for cohort of size 1 until no DLT were observed and cohort of size 3
# as soon as 1 DLT is observed.
my_size2 <- CohortSizeDLT(intervals = c(0, 1), cohort_size = c(1, 3))

# Cohort size rules of class 'CohortSizeMin' which will then be combined with
# the 'min' operation.
my_size <- CohortSizeMin(cohort_sizes = list(my_size1, my_size2))

CohortSizeOrdinal

Description

CohortSizeOrdinal is the class for cohort size for an ordinal CRM trial.

Usage

CohortSizeOrdinal(grade, rule)

.DefaultCohortSizeOrdinal()

Arguments

Slots

grade

(integer)
the grade at which the rule should be applied

rule

(CohortSize)
the CohortSize rule to apply.

Note

Typically, end users will not use the .DefaultCohortSizeOrdinal() function.

Examples

CohortSizeOrdinal(
  grade = 1L,
  rule = CohortSizeRange(intervals = c(0, 30), cohort_size = c(1L, 3L))
)

CohortSizeParts

Description

CohortSizeParts is the class for cohort size that changes for the second part of the dose escalation. It works only in conjunction with DataParts objects.

Usage

CohortSizeParts(cohort_sizes)

.DefaultCohortSizeParts()

Arguments

Slots

cohort_sizes

(integer)
a vector of length two with two sizes, one for part 1, and one for part 2 respectively.

Note

Typically, end users will not use the .DefaultCohortSizeParts() function.

Examples

# Part 1 cohort size = 1, Part 2 cohort size = 3.
my_size <- CohortSizeParts(cohort_sizes = c(1, 3))

CohortSizeRange

Description

CohortSizeRange is the class for cohort size based on dose range.

Usage

CohortSizeRange(intervals, cohort_size)

.DefaultCohortSizeRange()

Arguments

Slots

intervals

(numeric)
a vector with the left bounds of the relevant dose intervals.

cohort_size

(integer)
an integer vector with the cohort sizes corresponding to the elements of intervals.

Note

Typically, end users will not use the .DefaultCohortSizeRange() function.

Examples

# Example for the rule having cohort of size 1 for doses <30
# and having cohort of size 3 for doses >=30.

my_size <- CohortSizeRange(intervals = c(0, 30), cohort_size = c(1, 3))

CrmPackClass

Description

CrmPackClass is a virtual class, from which all other crmPack classes inherit.

DADesign

Description

This class has special requirements for the model and data slots in comparison to the parent class Design:

Usage

DADesign(model, data, safetyWindow, ...)

.DefaultDADesign()

Arguments

Details

The safetyWindow slot should be an instance of the SafetyWindow class. It can be customized to specify the duration of the safety window for your trial. The safety window represents the time period required to observe toxicity data from the ongoing cohort before opening the next cohort. Note that even after opening the next cohort, further toxicity data will be collected and analyzed to make dose escalation decisions.

To specify a constant safety window, use the SafetyWindowConst constructor. For example:

mysafetywindow <- SafetyWindowConst(c(6, 2), 10, 20)

Slots

model

(GeneralModel)
the model to use, see in particular DALogisticLogNormal and TITELogisticLogNormal which make use of the time-to-DLT data.

data

(DataDA)
what is the dose grid, any previous data, etc.

safetyWindow

(SafetyWindow)
the safety window to apply between cohorts.

Note

Typically, end users will not use the .DefaultDADesign() function.

See Also

SafetyWindowConst for creating a constant safety window.

Examples

empty_data <- DataDA(
  doseGrid = c(
    0.1,
    0.5,
    1,
    1.5,
    3,
    6,
    seq(from = 10, to = 80, by = 2)
  ),
  Tmax = 60
)

npiece <- 10
t_max <- 60

lambda_prior <- function(k) {
  npiece / (t_max * (npiece - k + 0.5))
}

model <- DALogisticLogNormal(
  mean = c(-0.85, 1),
  cov = matrix(c(1, -0.5, -0.5, 1), nrow = 2),
  ref_dose = 56,
  npiece = npiece,
  l = as.numeric(t(apply(as.matrix(c(1:npiece), 1, npiece), 2, lambda_prior))),
  c_par = 2
)

my_increments <- IncrementsRelative(
  intervals = c(0, 20),
  increments = c(1, 0.33)
)

my_next_best <- NextBestNCRM(
  target = c(0.2, 0.35),
  overdose = c(0.35, 1),
  max_overdose_prob = 0.25
)

my_size1 <- CohortSizeRange(
  intervals = c(0, 30),
  cohort_size = c(1, 3)
)

my_size2 <- CohortSizeDLT(
  intervals = c(0, 1),
  cohort_size = c(1, 3)
)

my_size <- maxSize(my_size1, my_size2)

my_stopping1 <- StoppingTargetProb(
  target = c(0.2, 0.35),
  prob = 0.5
)

my_stopping2 <- StoppingMinPatients(nPatients = 50)

my_stopping <- (my_stopping1 | my_stopping2)

my_safety_window <- SafetyWindowConst(c(6, 2), 7, 7)

design <- DADesign(
  model = model,
  increments = my_increments,
  nextBest = my_next_best,
  stopping = my_stopping,
  cohort_size = my_size,
  data = empty_data,
  safetyWindow = my_safety_window,
  startingDose = 3
)

DALogisticLogNormal

Description

DALogisticLogNormal is the class for the logistic model with bivariate (log) normal prior and data augmentation. This class inherits from the LogisticLogNormal class.

Usage

DALogisticLogNormal(npiece = 3, l, c_par = 2, cond_pem = TRUE, ...)

.DefaultDALogisticLogNormal()

Arguments

Slots

npiece

(number)
the number of pieces in the PEM.

l

(numeric)
a vector used in the lambda prior.

c_par

(numeric)
a parameter used in the lambda prior; according to Liu's paper, c_par = 2 is recommended.

cond_pem

(flag)
is a conditional piecewise-exponential model used? (default). Otherwise an unconditional model is used.

Note

We still need to include here formula for the lambda prior.

Typically, end users will not use the .DefaultDALogisticLogNormal() function.

See Also

ModelLogNormal, LogisticNormal, LogisticLogNormal.

Examples

npiece <- 10
Tmax <- 60 # nolintr

lambda_prior <- function(k) {
  npiece / (Tmax * (npiece - k + 0.5))
}

model <- DALogisticLogNormal(
  mean = c(-0.85, 1),
  cov = matrix(c(1, -0.5, -0.5, 1), nrow = 2),
  ref_dose = 56,
  npiece = npiece,
  l = as.numeric(t(apply(as.matrix(c(1:npiece), 1, npiece), 2, lambda_prior))),
  c_par = 2
)

DASimulations

Description

This class captures the trial simulations from DA based designs. In comparison to the parent class Simulations, it contains additional slots to capture the time to DLT fits, additional parameters and the trial duration.

Usage

DASimulations(trial_duration, ...)

.DefaultDASimulations()

Arguments

Slots

trial_duration

(numeric)
the vector of trial duration values for all simulations.

Note

Typically, end users will not use the .DefaultDASimulations() function.

Likelihood of DLTs in each interval

Description

This is a helper function for the fitPEM methods below.

Usage

DLTLikelihood(lambda, Tmax)

Arguments

Value

vector with the probabilities for DLTs within the intervals.

Data

Description

Data is a class for the data input. It inherits from GeneralData.

Usage

Data(
  x = numeric(),
  y = integer(),
  ID = integer(),
  cohort = integer(),
  doseGrid = numeric(),
  placebo = FALSE,
  ...
)

.DefaultData()

Arguments

Details

The cohort can be missing if and only if placebo is equal to FALSE.

Slots

x

(numeric)
the doses for the patients.

y

(integer)
the vector of toxicity events (0 or 1 integers).

doseGrid

(numeric)
the vector of all possible doses (sorted), i.e. the dose grid.

nGrid

(integer)
number of gridpoints.

xLevel

(integer)
the levels for the doses the patients have been given, w.r.t doseGrid.

placebo

(logical)
if TRUE the first dose level in the doseGridis considered as PLACEBO.

Note

ID and cohort can be missing. Then a message will be issued and the variables will be filled with default IDs and best guesses cohort, i.e. a sorted (in ascending order) sequence of values from ⁠{1, 2, ...}⁠.

Typically, end users will not use the .DefaultData() function.

Examples

my_data <- Data(
  x = c(0.1, 0.5, 1.5, 3, 6, 10, 10, 10),
  y = c(0, 0, 0, 0, 0, 0, 1, 0),
  ID = as.integer(1:8),
  cohort = as.integer(c(1, 2, 3, 4, 5, 6, 6, 6)),
  doseGrid = c(
    0.1,
    0.5,
    1.5,
    3,
    6,
    seq(from = 10, to = 80, by = 2)
  )
)
my_data

DataDA

Description

DataDA is a class for the time-to-DLT augmented data. It inherits from Data and it contains additional DLT free survival times.

Usage

DataDA(
  u = numeric(),
  t0 = numeric(length(u)),
  Tmax = 0 + .Machine$double.xmin,
  ...
)

.DefaultDataDA()

Arguments

Slots

u

(numeric)
the continuous vector of DLT free survival times.

t0

(numeric)
time of initial dosing for each patient. Non-negative values sorted in ascending order.

Tmax

(number)
the DLT observation period.

Note

⁠survival time⁠ here refers to the time period for which the subject did not experience any DLT, and is not referring to deaths.

Typically, end users will not use the .DefaultDataDA() function.

Examples

my_data <- DataDA(
  u = c(42, 30, 15, 5, 20, 25, 30, 60),
  t0 = c(0, 15, 30, 40, 55, 70, 75, 85),
  Tmax = 60,
  x = c(0.1, 0.5, 1.5, 3, 6, 10, 10, 10),
  y = c(0, 0, 1, 1, 0, 0, 1, 0),
  doseGrid = c(0.1, 0.5, 1.5, 3, 6, seq(from = 10, to = 80, by = 2))
)

# Set up an empty data set.
empty_data <- DataDA(
  doseGrid = c(0.1, 0.5, 1, 1.5, 3, 6, seq(from = 10, to = 80, by = 2)),
  Tmax = 60
)
empty_data

DataDual

Description

DataDual is a class for the dual endpoint data. It inherits from Data and it contains additional biomarker information.

Usage

DataDual(w = numeric(), ...)

.DefaultDataDual()

Arguments

Slots

w

(numeric)
the continuous vector of biomarker values.

Note

Typically, end users will not use the .DefaultDataDual() function.

Examples

my_data <- DataDual(
  w = rnorm(8),
  x = c(0.1, 0.5, 1.5, 3, 6, 10, 10, 10),
  y = c(0, 0, 0, 0, 0, 0, 1, 0),
  doseGrid = c(
    0.1,
    0.5,
    1.5,
    3,
    6,
    seq(from = 10, to = 80, by = 2)
  )
)
my_data

DataGrouped

Description

DataGrouped is a class for a two groups dose escalation data set, comprised of a monotherapy (mono) and a combination therapy (combo) arm. It inherits from Data and it contains the additional group information.

Usage

DataGrouped(group = character(), ...)

.DefaultDataGrouped()

Arguments

Slots

group

(factor)
whether mono or combo was used.

Note

Typically, end users will not use the .DefaultDataGrouped() function.

Examples

my_data <- DataGrouped(
  x = c(0.1, 0.5, 1.5, 3, 6, 10, 10, 10),
  y = c(0, 0, 1, 1, 0, 0, 1, 0),
  doseGrid = c(0.1, 0.5, 1.5, 3, 6, seq(from = 10, to = 80, by = 2)),
  group = c("mono", "mono", "mono", "mono", "mono", "mono", "combo", "combo")
)

# Set up an empty data set.
empty_data <- DataGrouped(
  doseGrid = c(0.1, 0.5, 1, 1.5, 3, 6, seq(from = 10, to = 80, by = 2))
)
empty_data

DataMixture

Description

DataMixture is a class for the data with mixture sharing. It inherits from Data and it contains additional information on the mixture sharing.

Usage

DataMixture(xshare = numeric(), yshare = integer(), ...)

.DefaultDataMixture()

Arguments

Slots

xshare

(numeric)
the doses for the share patients.

yshare

(integer)
the vector of toxicity events (0 or 1) for the share patients.

nObsshare

(count)
number of share patients.

Note

Typically, end users will not use the .DefaultDataMixture() function.

Examples

my_data <- DataMixture(
  xshare = c(12, 14, 16, 18.0),
  yshare = c(0L, 1L, 1L, 1L),
  nObsshare = 4L,
  x = c(0.1, 0.5, 1.5),
  y = c(0, 0, 0),
  ID = 1:3,
  cohort = 1:3,
  doseGrid = c(0.1, 0.5, 1.5, 3, 6, seq(from = 10, to = 80, by = 2))
)
my_data

DataOrdinal

Description

DataOrdinal is a class for ordinal toxicity data. It inherits from GeneralData and it describes toxicity responses on an ordinal rather than binary scale.

Usage

DataOrdinal(
  x = numeric(),
  y = integer(),
  ID = integer(),
  cohort = integer(),
  doseGrid = numeric(),
  placebo = FALSE,
  yCategories = c(`No DLT` = 0L, DLT = 1L),
  ...
)

.DefaultDataOrdinal()

Arguments

Details

The cohort can be missing if and only if placebo is equal to FALSE.

Note

This class has been implemented as a sibling of the existing Data class (rather than as a parent or child) to minimise the risk of unintended side effects on existing classes and methods.

The default setting for the yCategories slot replicates the behaviour of the existing Data class.

Typically, end users will not use the .DefaultDataOrdinal() function.

Examples

DataOrdinal(
  x = c(10, 20, 30, 40, 50, 50, 50, 60, 60, 60),
  y = as.integer(c(0, 0, 0, 0, 0, 1, 0, 0, 1, 2)),
  ID = 1L:10L,
  cohort = as.integer(c(1:4, 5, 5, 5, 6, 6, 6)),
  doseGrid = c(seq(from = 10, to = 100, by = 10)),
  yCategories = c("No tox" = 0L, "Sub-tox AE" = 1L, "DLT" = 2L),
  placebo = FALSE
)

DataParts

Description

DataParts is a class for the data with two study parts. It inherits from Data and it contains additional information on the two study parts.

Usage

DataParts(part = integer(), nextPart = 1L, part1Ladder = numeric(), ...)

.DefaultDataParts()

Arguments

Slots

part

(integer)
which part does each of the patients belong to?

nextPart

(count)
what is the part for the next cohort (1 or 2)?

part1Ladder

(numeric)
what is the escalation ladder for part 1? This shall be an ordered subset of the doseGrid.

Note

Typically, end users will not use the .DefaultDataParts() function.

Examples

my_data <- DataParts(
  x = c(0.1, 0.5, 1.5),
  y = c(0, 0, 0),
  ID = 1:3,
  cohort = 1:3,
  doseGrid = c(0.1, 0.5, 1.5, 3, 6, seq(from = 10, to = 80, by = 2)),
  part = c(1L, 1L, 1L),
  nextPart = 1L,
  part1Ladder = c(0.1, 0.5, 1.5, 3, 6, 10)
)
my_data

Design

Description

Design is the class for rule-based designs. The difference between this class and its parent RuleDesign class is that Design class contains additional model, stopping and increments slots.

Usage

Design(model, stopping, increments, pl_cohort_size = CohortSizeConst(0L), ...)

.DefaultDesign()

Arguments

Slots

model

(GeneralModel)
the model to be used.

stopping

(Stopping)
stopping rule(s) for the trial.

increments

(Increments)
how to control increments between dose levels.

pl_cohort_size

(CohortSize)
rules for the cohort sizes for placebo, if any planned (defaults to constant 0 placebo patients).

Note

Typically, end users will not use the .DefaultDesign() function.

Examples

empty_data <- Data(doseGrid = c(1, 3, 5, 10, 15, 20, 25, 40, 50, 80, 100))

# Initialize the CRM model.
my_model <- LogisticLogNormal(
  mean = c(-0.85, 1),
  cov = matrix(c(1, -0.5, -0.5, 1), nrow = 2),
  ref_dose = 56
)

# Choose the rule for selecting the next dose.
my_next_best <- NextBestNCRM(
  target = c(0.2, 0.35),
  overdose = c(0.35, 1),
  max_overdose_prob = 0.25
)

# Choose the rule for the cohort-size.
my_size1 <- CohortSizeRange(
  intervals = c(0, 30),
  cohort_size = c(1, 3)
)
my_size2 <- CohortSizeDLT(
  intervals = c(0, 1),
  cohort_size = c(1, 3)
)
my_size <- maxSize(my_size1, my_size2)

# Choose the rule for stopping.
my_stopping1 <- StoppingMinCohorts(nCohorts = 3)
my_stopping2 <- StoppingTargetProb(
  target = c(0.2, 0.35),
  prob = 0.5
)
my_stopping3 <- StoppingMinPatients(nPatients = 20)
my_stopping <- (my_stopping1 & my_stopping2) | my_stopping3

# Choose the rule for dose increments.
my_increments <- IncrementsRelative(
  intervals = c(0, 20),
  increments = c(1, 0.33)
)

# Initialize the design.
design <- Design(
  model = my_model,
  nextBest = my_next_best,
  stopping = my_stopping,
  increments = my_increments,
  cohort_size = my_size,
  data = empty_data,
  startingDose = 3
)

DesignGrouped

Description

DesignGrouped combines two Design objects: one for the mono and one for the combo arm of a joint dose escalation design.

Usage

DesignGrouped(
  model,
  mono,
  combo = mono,
  first_cohort_mono_only = TRUE,
  same_dose_for_all = !same_dose_for_start,
  same_dose_for_start = FALSE,
  stop_mono_with_combo = FALSE,
  ...
)

Arguments

Details

• Note that the model slots inside the mono and combo parameters are ignored (because we don't fit separate regression models for the mono and combo arms). Instead, the model parameter is used to fit a joint regression model for the mono and combo arms together.

• same_dose_for_start = TRUE is useful as an option when we want to use same_dose_for_all = FALSE combined with first_cohort_mono_only = TRUE. This will allow to randomize patients to the mono and combo arms at the same dose as long as the selected dose for the cohorts stay the same. This can therefore further mitigate bias as long as possible between the mono and combo arms.

Slots

model

(LogisticLogNormalGrouped)
the model to be used, currently only one class is allowed.

mono

(Design)
defines the dose escalation rules for the mono arm, see details.

combo

(Design)
defines the dose escalation rules for the combo arm, see details.

first_cohort_mono_only

(flag)
whether first test one mono agent cohort, and then once its DLT data has been collected, we proceed from the second cohort onwards with concurrent mono and combo cohorts.

same_dose_for_all

(flag)
whether the lower dose of the separately determined mono and combo doses should be used as the next dose for both mono and combo in all cohorts.

same_dose_for_start

(flag)
indicates whether, when mono and combo are used in the same cohort for the first time, the same dose should be used for both. Note that this is different from same_dose_for_all which will always force them to be the same. If same_dose_for_all = TRUE, this is therefore ignored. See Details.

Note

Typically, end-users will not use the .DefaultDesignGrouped() function.

Examples

empty_data <- Data(doseGrid = c(1, 3, 5, 10, 15, 20, 25, 40, 50, 80, 100))

# Initialize the joint model.
my_model <- LogisticLogNormalGrouped(
  mean = c(-0.85, 0, 1, 0),
  cov = diag(1, 4),
  ref_dose = 56
)

# Choose the rule for selecting the next dose.
my_next_best <- NextBestNCRM(
  target = c(0.2, 0.35),
  overdose = c(0.35, 1),
  max_overdose_prob = 0.25
)

# Choose the rule for the cohort-size.
my_size1 <- CohortSizeRange(
  intervals = c(0, 30),
  cohort_size = c(1, 3)
)
my_size2 <- CohortSizeDLT(
  intervals = c(0, 1),
  cohort_size = c(1, 3)
)
my_size <- maxSize(my_size1, my_size2)

# Choose the rule for stopping.
my_stopping1 <- StoppingMinCohorts(nCohorts = 3)
my_stopping2 <- StoppingTargetProb(
  target = c(0.2, 0.35),
  prob = 0.5
)
my_stopping3 <- StoppingMinPatients(nPatients = 20)
my_stopping <- (my_stopping1 & my_stopping2) | my_stopping3

# Choose the rule for dose increments.
my_increments <- IncrementsRelative(
  intervals = c(0, 20),
  increments = c(1, 0.33)
)

# Rules to be used for both arms.
one_arm <- Design(
  model = .DefaultModelLogNormal(), # Ignored.
  nextBest = my_next_best,
  stopping = my_stopping,
  increments = my_increments,
  cohort_size = my_size,
  data = empty_data,
  startingDose = 3
)

# Initialize the design.
design <- DesignGrouped(
  model = my_model,
  mono = one_arm
)

# Alternative options: Here e.g.
# - use both mono in first cohort and afterwards have mono and combo in parallel,
# - in general allow different dose levels for the cohorts,
# - but for the start (i.e. second cohort) have the same dose for mono and combo.
# - Stop mono arm too, when combo arm is stopped.

design2 <- DesignGrouped(
  model = my_model,
  mono = one_arm,
  first_cohort_mono_only = TRUE,
  same_dose_for_all = FALSE,
  same_dose_for_start = TRUE,
  stop_mono_with_combo = TRUE
)

DesignOrdinal

Description

DesignOrdinal is the class for rule-based ordinal designs. The difference between this class and its parent RuleDesignOrdinal class is that the DesignOrdinal class contains additional model, stopping, increments and pl_cohort_size slots.

Usage

DesignOrdinal(
  model,
  stopping,
  increments,
  pl_cohort_size = CohortSizeOrdinal(1L, CohortSizeConst(0L)),
  ...
)

.DefaultDesignOrdinal()

Arguments

Details

Please note that stopping, increments or cohort size rules need to be wrapped into the corresponding StoppingOrdinal, IncrementsOrdinal or CohortSizeOrdinal classes, before a successful evaluation of the corresponding methods can take place. Note also that these wrappers cannot be nested, i.e., you cannot have an IncrementsOrdinal inside another IncrementsOrdinal (which also would not make sense) because it would not be clear which event grade to use for the methods calculation. However, multiple rules can be combined using the operators defined for these classes, e.g., StoppingOrdinal(1L, rule1 & rule2) | StoppingOrdinal(2L, rule3).

Slots

model

(LogisticLogNormalOrdinal)
the model to be used.

stopping

(Stopping)
stopping rule(s) for the trial.

increments

(Increments)
how to control increments between dose levels.

pl_cohort_size

(CohortSize)
rules for the cohort sizes for placebo, if any planned (defaults to constant 0 placebo patients).

Note

Typically, end users will not use the .DefaultDesignOrdinal() function.

Examples

my_size1 <- CohortSizeRange(
  intervals = c(0, 30),
  cohort_size = c(1, 3)
)
my_size2 <- CohortSizeDLT(
  intervals = c(0, 1),
  cohort_size = c(1, 3)
)
my_size <- CohortSizeOrdinal(1L, maxSize(my_size1, my_size2))

my_stopping1 <- StoppingMinCohorts(nCohorts = 3)
my_stopping2 <- StoppingTargetProb(
  target = c(0.2, 0.35),
  prob = 0.5
)
my_stopping3 <- StoppingMinPatients(nPatients = 20)
my_stopping <- StoppingOrdinal(1L, (my_stopping1 & my_stopping2) | my_stopping3)

# Initialize the design.
design <- DesignOrdinal(
  model = LogisticLogNormalOrdinal(
    mean = c(-3, -4, 1),
    cov = diag(c(3, 4, 1)),
    ref_dose = 50
  ),
  next_best = NextBestOrdinal(
    1L,
    NextBestNCRM(
      target = c(0.2, 0.35),
      overdose = c(0.35, 1),
      max_overdose_prob = 0.25
    )
  ),
  stopping = my_stopping,
  increments = IncrementsOrdinal(
    1L,
    IncrementsRelative(
      intervals = c(0, 20),
      increments = c(1, 0.33)
    )
  ),
  cohort_size = my_size,
  data = DataOrdinal(
    doseGrid = c(1, 3, 5, 10, 15, 20, 25, 40, 50, 80, 100),
    yCategories = c("No tox" = 0L, "Sub-tox AE" = 1L, "DLT" = 2L)
  ),
  starting_dose = 3
)

DualDesign

Description

DualDesign is the class for the dual-endpoint CRM design. This class has special requirements for the model and data slots in comparison to the parent class Design.

Usage

DualDesign(model, data, ...)

.DefaultDualDesign()

Arguments

Slots

model

(DualEndpoint)
the model to be used.

data

(DataDual)
specifies dose grid, any previous data, etc.

Note

the nextBest slot can be of any class, this allows for easy comparison with recommendation methods that don't use the biomarker information.

Typically, end users will not use the .DefaultDualDesign() function.

Examples

empty_data <- DataDual(doseGrid = c(1, 3, 5, 10, 15, 20, 25, 40, 50, 80, 100))

# Initialize the CRM model.
my_model <- DualEndpointRW(
  mean = c(0, 1),
  cov = matrix(c(1, 0, 0, 1), nrow = 2),
  sigma2betaW = 0.01,
  sigma2W = c(a = 0.1, b = 0.1),
  rho = c(a = 1, b = 1),
  rw1 = TRUE
)

# Choose the rule for selecting the next dose.
my_next_best <- NextBestDualEndpoint(
  target = c(0.9, 1),
  overdose = c(0.35, 1),
  max_overdose_prob = 0.25
)

# Choose the rule for the cohort-size.
my_size1 <- CohortSizeRange(
  intervals = c(0, 30),
  cohort_size = c(1, 3)
)
my_size2 <- CohortSizeDLT(
  intervals = c(0, 1),
  cohort_size = c(1, 3)
)
my_size <- maxSize(my_size1, my_size2)

# Choose the rule for stopping.
my_stopping1 <- StoppingTargetBiomarker(
  target = c(0.9, 1),
  prob = 0.5
)
my_stopping <- my_stopping1 | StoppingMinPatients(40)

# Choose the rule for dose increments.
my_increments <- IncrementsRelative(
  intervals = c(0, 20),
  increments = c(1, 0.33)
)

# Initialize the design.
design <- DualDesign(
  model = my_model,
  data = empty_data,
  nextBest = my_next_best,
  stopping = my_stopping,
  increments = my_increments,
  cohort_size = my_size,
  startingDose = 3
)

DualEndpoint

Description

DualEndpoint is the general class for the dual endpoint model.

Usage

DualEndpoint(mean, cov, ref_dose = 1, use_log_dose = FALSE, sigma2W, rho)

.DefaultDualEndpoint()

Arguments

Details

The idea of the dual-endpoint models is to model not only the dose-toxicity relationship, but also to model, at the same time, the relationship of a PD biomarker with the dose. The sub-classes of this class define how the dose-biomarker relationship is parametrized. This class here shall contain all the common features to reduce duplicate code. (This class however, must not be virtual as we need to create objects of it during the construction of subclass objects.)

The dose-toxicity relationship is modeled with probit regression model

probit[p(x)] = betaZ1 + betaZ2 * x/x*,

or

probit[p(x)] = betaZ1 + betaZ2 * log(x/x*),

in case when the option use_log_dose is TRUE. Here, p(x) is the probability of observing a DLT for a given dose x and x* is the reference dose. The prior

(betaZ1, log(betaZ2)) ~ Normal(mean, cov).

For the biomarker response w at a dose x, we assume

w(x) ~ Normal(f(x), sigma2W),

where f(x) is a function of the dose x, which is further specified in sub-classes. The biomarker variance sigma2W can be fixed or assigned an Inverse-Gamma prior distribution; see the details below under slot sigma2W.

Finally, the two endpoints y (the binary DLT variable) and w (the biomarker) can be correlated, by assuming a correlation of level rho between the underlying continuous latent toxicity variable z and the biomarker w. Again, this correlation can be fixed or assigned a prior distribution from the scaled Beta family; see the details below under slot rho.

Please see the example vignette by typing crmPackExample() for a full example.

Slots

betaZ_params

(ModelParamsNormal)
for the probit toxicity model, it contains the prior mean, covariance matrix and precision matrix which is internally calculated as an inverse of the covariance matrix.

ref_dose

(positive_number)
for the probit toxicity model, the reference dose.

use_log_dose

(flag)
for the probit toxicity model, whether a log transformation of the (standardized) dose should be used?

sigma2W

(numeric)
the biomarker variance. Either a fixed value or Inverse-Gamma distribution parameters, i.e. vector with two elements named a and b.

rho

(numeric)
either a fixed value for the correlation (between -1 and 1), or a named vector with two elements named a and b for the Beta prior on the transformation kappa = (rho + 1) / 2, which is in ⁠(0, 1)⁠. For example, ⁠a = 1, b = 1⁠ leads to a uniform prior on rho.

use_fixed

(logical)
indicates whether a fixed value for sigma2W or rho (for each parameter separately) is used or not. This slot is needed for internal purposes and must not be touched by the user.

Note

Typically, end users will not use the .DefaultDualEndpoint() function.

See Also

DualEndpointRW, DualEndpointBeta, DualEndpointEmax.

DualEndpointBeta

Description

DualEndpointBeta is the class for the dual endpoint model with beta function for dose-biomarker relationship.

Usage

DualEndpointBeta(E0, Emax, delta1, mode, ref_dose_beta = 1, ...)

.DefaultDualEndpointBeta()

Arguments

Details

This class extends the DualEndpoint class so that the dose-biomarker relationship f(x) is modelled by a parametric, rescaled beta density function:

f(x) = E0 + (Emax - E0) * Beta(delta1, delta2) * (x/x*)^{delta1} * (1 - x/x*)^{delta2},

where x* is the maximum dose (end of the dose range to be considered), delta1 and delta2 are the two beta function parameters, and E0, Emax are the minimum and maximum levels, respectively. For ease of interpretation, we use the parametrization based on delta1 and the mode, where

mode = delta1 / (delta1 + delta2),

so that multiplying this by x* gives the mode on the dose grid.

All parameters can currently be assigned uniform distributions or be fixed in advance. Note that E0 and Emax can have negative values or uniform distributions reaching into negative range, while delta1 and mode must be positive or have uniform distributions in the positive range.

Slots

E0

(numeric)
either a fixed number or the two uniform distribution parameters.

Emax

(numeric)
either a fixed number or the two uniform distribution parameters.

delta1

(numeric)
either a fixed positive number or the two parameters of the uniform distribution, that can take only positive values.

mode

(numeric)
either a fixed positive number or the two parameters of the uniform distribution, that can take only positive values.

ref_dose_beta

(positive_number)
the reference dose x* (note that this is different from the ref_dose in the inherited DualEndpoint model).

Note

Typically, end users will not use the .DefaultDualEndpointBeta() function.

See Also

DualEndpoint, DualEndpointRW, DualEndpointEmax.

Examples

my_model <- DualEndpointBeta(
  mean = c(0, 1),
  cov = matrix(c(1, 0, 0, 1), nrow = 2),
  ref_dose = 10,
  use_log_dose = TRUE,
  sigma2W = c(a = 0.1, b = 0.1),
  rho = c(a = 1, b = 1),
  E0 = c(0, 100),
  Emax = c(0, 500),
  delta1 = c(0, 5),
  mode = c(1, 15),
  ref_dose_beta = 1000
)

DualEndpointEmax

Description

DualEndpointEmax is the class for the dual endpoint model with Emax function for dose-biomarker relationship.

Usage

DualEndpointEmax(E0, Emax, ED50, ref_dose_emax = 1, ...)

.DefaultDualEndpointEmax()

Arguments

Details

This class extends the DualEndpoint class so that the dose-biomarker relationship f(x) is modelled by a parametric Emax function:

f(x) = E0 + [(Emax - E0) * (x/x*)]/[ED50 + (x/x*)],

where x* is a reference dose, E0 and Emax are the minimum and maximum levels for the biomarker, and ED50 is the dose achieving half of the maximum effect 0.5 * Emax. All parameters can currently be assigned uniform distributions or be fixed.

Slots

E0

(numeric)
either a fixed number or the two uniform distribution parameters.

Emax

(numeric)
either a fixed number or the two uniform distribution parameters.

ED50

(numeric)
either a fixed number or the two uniform distribution parameters.

ref_dose_emax

(positive_number)
the reference dose x* (note that this is different from the ref_dose in the inherited DualEndpoint model).

Note

Typically, end users will not use the .DefaultDualEndpointEmax() function.

See Also

DualEndpoint, DualEndpointRW, DualEndpointBeta.

Examples

my_model <- DualEndpointEmax(
  mean = c(0, 1),
  cov = matrix(c(1, 0, 0, 1), nrow = 2),
  sigma2W = c(a = 0.1, b = 0.1),
  rho = c(a = 1, b = 1),
  E0 = c(0, 100),
  Emax = c(0, 500),
  ED50 = c(10, 200),
  ref_dose_emax = 1000
)

DualEndpointRW

Description

DualEndpointRW is the class for the dual endpoint model with random walk prior for biomarker.

Usage

DualEndpointRW(sigma2betaW, rw1 = TRUE, ...)

.DefaultDualEndpointRW()

Arguments

Details

This class extends the DualEndpoint class so that the dose-biomarker relationship f(x) is modelled by a non-parametric random walk of first or second order. That means, for the first order random walk we assume

betaW_i - betaW_i-1 ~ Normal(0, (x_i - x_i-1) * sigma2betaW),

where betaW_i = f(x_i) is the biomarker mean at the i-th dose gridpoint x_i. For the second order random walk, the second-order differences instead of the first-order differences of the biomarker means follow the normal distribution with 0 mean and 2 * (x_i - x_i-2) * sigma2betaW variance.

The variance parameter sigma2betaW is important because it steers the smoothness of the function f(x), i.e.: if it is large, then f(x) will be very wiggly; if it is small, then f(x) will be smooth. This parameter can either be a fixed value or assigned an inverse gamma prior distribution.

Slots

sigma2betaW

(numeric)
the prior variance factor of the random walk prior for the biomarker model. Either a fixed value or Inverse-Gamma distribution parameters, i.e. vector with two elements named a and b.

rw1

(flag)
for specifying the random walk prior on the biomarker level. When TRUE, random walk of first order is used. Otherwise, the random walk of second order is used.

Note

Non-equidistant dose grids can be used now, because the difference x_i - x_i-1 is included in the modelling assumption above. Please note that due to impropriety of the random walk prior distributions, it is not possible to produce MCMC samples with empty data objects (i.e., sample from the prior). This is not a bug, but a theoretical feature of this model.

Typically, end users will not use the .DefaultDualEndpointRW() function.

See Also

DualEndpoint, DualEndpointBeta, DualEndpointEmax.

Examples

my_model <- DualEndpointRW(
  mean = c(0, 1),
  cov = matrix(c(1, 0, 0, 1), nrow = 2),
  sigma2W = c(a = 0.1, b = 0.1),
  rho = c(a = 1, b = 1),
  sigma2betaW = 0.01,
  rw1 = TRUE
)

DualResponsesDesign.R

Description

This is a class of design based on DLE responses using the LogisticIndepBeta model without DLE and efficacy samples. It contains all slots from the RuleDesign and TDsamplesDesign classes.

Usage

DualResponsesDesign(eff_model, data, ...)

.DefaultDualResponsesDesign()

Arguments

Slots

data

(DataDual)
the data set.

eff_model

(ModelEff)
the pseudo efficacy model to be used.

Note

Typically, end users will not use the .DefaultDualResponsesDesign() function.

Examples

empty_data <- DataDual(doseGrid = seq(25, 300, 25))

tox_model <- LogisticIndepBeta(
  binDLE = c(1.05, 1.8),
  DLEweights = c(3, 3),
  DLEdose = c(25, 300),
  data = empty_data
)

eff_model <- Effloglog(
  eff = c(1.223, 2.513),
  eff_dose = c(25, 300),
  nu = c(a = 1, b = 0.025),
  data = empty_data
)

my_next_best <- NextBestMaxGain(
  prob_target_drt = 0.35,
  prob_target_eot = 0.3
)

my_increments <- IncrementsRelative(
  intervals = c(25, 300),
  increments = c(2, 2)
)

my_size <- CohortSizeConst(size = 3)
my_stopping <- StoppingMinPatients(nPatients = 36)

design <- DualResponsesDesign(
  nextBest = my_next_best,
  cohort_size = my_size,
  startingDose = 25,
  model = tox_model,
  eff_model = eff_model,
  data = empty_data,
  stopping = my_stopping,
  increments = my_increments
)

DualResponsesSamplesDesign

Description

This is a class of design based on DLE responses using the LogisticIndepBeta model with DLE and efficacy samples. It contain all slots in RuleDesign and TDsamplesDesign class objects.

Usage

DualResponsesSamplesDesign(eff_model, data, ...)

.DefaultDualResponsesSamplesDesign()

Arguments

Slots

data

(DataDual)
the data set.

eff_model

(ModelEff)
the pseudo efficacy model to be used.

Note

Typically, end users will not use the .DefaultDualResponsesSamplesDesign() function.

Examples

empty_data <- DataDual(doseGrid = seq(25, 300, 25))

tox_model <- LogisticIndepBeta(
  binDLE = c(1.05, 1.8),
  DLEweights = c(3, 3),
  DLEdose = c(25, 300),
  data = empty_data
)
options <- McmcOptions(burnin = 100, step = 2, samples = 200)
tox_samples <- mcmc(empty_data, tox_model, options)

eff_model <- Effloglog(
  eff = c(1.223, 2.513),
  eff_dose = c(25, 300),
  nu = c(a = 1, b = 0.025),
  data = empty_data
)
eff_samples <- mcmc(empty_data, eff_model, options)

my_next_best <- NextBestMaxGainSamples(
  prob_target_drt = 0.35,
  prob_target_eot = 0.3,
  derive = function(samples) {
    as.numeric(quantile(samples, prob = 0.3))
  },
  mg_derive = function(mg_samples) {
    as.numeric(quantile(mg_samples, prob = 0.5))
  }
)

my_increments <- IncrementsRelative(
  intervals = c(25, 300),
  increments = c(2, 2)
)
my_size <- CohortSizeConst(size = 3)
my_stopping <- StoppingMinPatients(nPatients = 36)

design <- DualResponsesSamplesDesign(
  nextBest = my_next_best,
  cohort_size = my_size,
  startingDose = 25,
  model = tox_model,
  eff_model = eff_model,
  data = empty_data,
  stopping = my_stopping,
  increments = my_increments
)

DualSimulations

Description

This class captures the trial simulations from dual-endpoint model based designs. In comparison to the parent class Simulations, it contains additional slots to capture the dose-biomarker fits, and the sigma2W and rho estimates.

Usage

DualSimulations(rho_est, sigma2w_est, fit_biomarker, ...)

.DefaultDualSimulations()

Arguments

Slots

rho_est

(numeric)
vector of final posterior median rho estimates

sigma2w_est

(numeric)
vector of final posterior median sigma2W estimates

fit_biomarker

(list)
with the final dose-biomarker curve fits

Note

Typically, end users will not use the .DefaultDualSimulations() function.

Examples

data_list <- list(
  Data(
    x = 1:2,
    y = 0:1,
    doseGrid = 1:2,
    ID = 1L:2L,
    cohort = 1L:2L
  ),
  Data(
    x = 3:4,
    y = 0:1,
    doseGrid = 3:4,
    ID = 1L:2L,
    cohort = 1L:2L
  )
)

doses <- c(1, 2)
seed <- as.integer(123)

fit <- list(
  c(0.1, 0.2),
  c(0.3, 0.4)
)

stop_report <- matrix(c(TRUE, FALSE), nrow = 2)

stop_reasons <- list("A", "B")

additional_stats <- list(a = 1, b = 1)

dual_simulations_obj <- DualSimulations(
  rho_est = c(0.25, 0.35),
  sigma2w_est = c(0.15, 0.25),
  fit_biomarker = list(c(0.3, 0.4), c(0.4, 0.5)),
  fit = fit,
  stop_report = stop_report,
  stop_reasons = stop_reasons,
  additional_stats = additional_stats,
  data = data_list,
  doses = doses,
  seed = seed
)

DualSimulationsSummary

Description

This class captures the summary of dual-endpoint simulations output. In comparison to its parent class SimulationsSummary, it has additional slots.

Usage

.DefaultDualSimulationsSummary()

Slots

biomarker_fit_at_dose_most_selected

(numeric)
fitted biomarker level at most often selected dose.

mean_biomarker_fit

(list)
list with average, lower (2.5%) and upper (97.5%) quantiles of mean fitted biomarker level at each dose

Note

Typically, end users will not use the .DefaultDualSimulationsSummary() function.

EffFlexi

Description

EffFlexi is the class for the efficacy model in flexible form of prior expressed in form of pseudo data. In this class, a flexible form is used to describe the relationship between the efficacy responses and the dose levels and it is specified as

(W | betaW, sigma2W) ~ Normal(X * betaW, sigma2W * I),

where W is a vector of the efficacy responses, betaW is a column vector of the mean efficacy responses for all dose levels, and X is the design matrix with entries I_i,j that are equal to 1 if subject i is allocated to dose j, and 0 otherwise. The sigma2W is the variance of the efficacy responses which can be either a fixed number or a number from an inverse gamma distribution. This flexible form aims to capture different shapes of the dose-efficacy curve. In addition, the first (RW1) or second order (RW2) random walk model can be used for smoothing data. That is the random walk model is used to model the first or the second order differences of the mean efficacy responses to its neighboring dose levels of their mean efficacy responses.

The RW1 model is given as

betaW_j - betaW_j-1) ~ Normal(0, sigma2betaW),

and for RW2 as

betaW_j-2 - 2 * betaW_j-1 + beta_j ~ Normal(0, sigma2betaW),

where betaW_j is the vector of mean efficacy responses at dose j, and the sigma2betaW is the prior variance which can be either a fixed number or a number from an inverse gamma distribution.

The eff and eff_dose are the pseudo efficacy responses and dose levels at which these pseudo efficacy responses are observed. Both, eff and eff_dose must be vectors of length at least 2. The positions of the elements specified in eff and eff_dose must correspond to each other between these vectors.

Usage

EffFlexi(eff, eff_dose, sigma2W, sigma2betaW, rw1 = TRUE, data)

.DefaultEffFlexi()

Arguments

Details

This model will output the updated value or the updated values of the parameters of the inverse gamma distributions for sigma2W and sigma2betaW. The EffFlexi inherits all slots from ModelEff class.

Slots

eff

(numeric)
the pseudo efficacy responses. Each element here must represent responses treated based on one subject. It must be a vector of length at least 2 and the order of its elements must correspond to values specified in eff_dose.

eff_dose

(numeric)
the pseudo efficacy dose levels at which the pseudo efficacy responses are observed. It must be a vector of length at least 2 and the order of its elements must correspond to values specified in eff.

sigma2W

(numeric)
the prior variance of the flexible efficacy form. This is either a fixed value or a named vector with two positive numbers, the shape (a), and the rate (b) parameters for the gamma distribution.

sigma2betaW

(numeric)
the prior variance of the random walk model for the mean efficacy responses. This is either a fixed value or a named vector with two positive numbers, the shape (a), and the rate (b) parameters for the gamma distribution.

use_fixed

(logical)
indicates whether a fixed value for sigma2W and sigma2betaW (for each parameter separately) is used or not. This slot is needed for internal purposes and must not be touched by the user.

rw1

(flag)
used for smoothing data for this efficacy model. If it is TRUE, the first-order random walk model is used for the mean efficacy responses. Otherwise, the random walk of second order is used.

X

(matrix)
the design matrix for the efficacy responses. It is based on both the pseudo and the observed efficacy responses.

RW

(matrix)
the difference matrix for the random walk model. This slot is needed for internal purposes and must not be used by the user.

RW_rank

(integer)
is the rank of the difference matrix. This slot is needed for internal purposes and must not be used by the user.

Note

Typically, end users will not use the .DefaultEffFlexi() function.

Examples

# Obtain prior estimates for the efficacy model in flexible form, given the pseudo data.
# First define an empty data set by defining the dose levels used in the study.
# There are 12 dose levels used in the study, ranging from 25 to 300 mg with
# increments of 25.
emptydata <- DataDual(doseGrid = seq(25, 300, 25))

# Define the pseudo data, i.e.: fixed 2 dose levels 25 and 300 mg (`eff_dose`)
# and the efficacy responses 1.223 and 2.513 observed at these two dose levels (`eff`).
# The prior variance of the pseudo efficacy responses can be either a fixed value
# or two parameters for the inverse gamma distribution, the shape (a) and the
# rate (b) (`sigma2W`).
# The prior variance of the random walk model can be either a fixed value or two
# parameters for the inverse gamma distribution, the shape (a) and the rate (b)
# (`sigma2betaW`).
my_model <- EffFlexi(
  eff = c(1.223, 2.513),
  eff_dose = c(25, 300),
  sigma2W = c(a = 0.1, b = 0.1),
  sigma2betaW = c(a = 20, b = 50),
  rw1 = FALSE,
  data = emptydata
)

# Obtain estimates from the model given some observed data is available.
data <- DataDual(
  x = c(25, 50, 50, 75, 100, 100, 225, 300),
  y = c(0, 0, 0, 0, 1, 1, 1, 1),
  w = c(0.31, 0.42, 0.59, 0.45, 0.6, 0.7, 0.6, 0.52),
  doseGrid = emptydata@doseGrid
)

my_model1 <- EffFlexi(
  eff = c(1.223, 2.513),
  eff_dose = c(25, 300),
  sigma2W = c(a = 0.1, b = 0.1),
  sigma2betaW = c(a = 20, b = 50),
  rw1 = FALSE,
  data = data
)

Effloglog

Description

Effloglog is the class for the linear log-log efficacy model using pseudo data prior. It describes the relationship between continuous efficacy responses and corresponding dose levels in log-log scale. This efficacy log-log model is given as

y_i = theta1 + theta2 * log(log(x_i)) + epsilon_i,

where y_i is the efficacy response for subject i, x_i is the dose level treated for subject i and epsilon_i is the random error term of efficacy model at subject i. The error term epsilon_i is a random variable that follows normal distribution with mean 0 and variance nu^{-1}, which is assumed to be the same for all subjects. There are three parameters in this model, the intercept theta1, the slope theta2 and the precision nu of the efficacy responses, also known as the inverse of the variance of the pseudo efficacy responses. It can be a fixed constant or having a gamma distribution. Therefore, a single scalar value or a vector with two positive numbers values must be specified for nu slot. If there are some observed efficacy responses available, in the output, nu will display the updated value of the precision or the updated values for the parameters of the gamma distribution. The Effloglog inherits all slots from ModelEff class.

Usage

Effloglog(eff, eff_dose, nu, data, const = 0)

.DefaultEffloglog()

Arguments

Details

The prior of this model is specified in form of pseudo data. First, at least two dose levels are fixed. Then, using e.g. experts' opinion, the efficacy values that correspond to these dose levels can be obtained, The eff and eff_dose arguments represent the prior in form of the pseudo data. The eff represents the pseudo efficacy values. The eff_dose represents the dose levels at which these pseudo efficacy values are observed. Hence, the positions of the elements specified in eff and eff_dose must correspond to each other between these vectors. Since at least 2 pseudo efficacy values are needed to obtain modal estimates of the intercept and slope parameters, both eff and eff_dose must be vectors of length at least 2.

The joint prior distribution of the intercept theta1 and the slope theta2 of this model follows bivariate normal distribution with mean mu and covariance matrix (nu * Q)^{-1}. The mean mu is a 2 x 1 column vector that contains the prior modal estimates of the intercept and the slope. Scalar nu is the precision of the pseudo efficacy responses and Q is the prior or posterior (given that observed, no DLT data is available) precision matrix. It is specified as Q = X0^T * X0 + X^T * X, where X0 is a design matrix that is based on pseudo dose levels only, and X is a design matrix that is based on dose levels corresponding to the no DLT efficacy responses observed only (if any). Hence, the X0 (or X) will be of size r x 2, if there are r >= 2 pseudo efficacy responses specified (or if there are r no DLT efficacy responses observed in the data).

Slots

eff

(numeric)
the pseudo efficacy responses. Each element here must represent responses treated based on one subject. It must be a vector of length at least 2 and the order of its elements must correspond to values specified in eff_dose.

eff_dose

(numeric)
the pseudo efficacy dose levels at which the pseudo efficacy responses are observed. It must be a vector of length at least 2 and the order of its elements must correspond to values specified in eff.

nu

(numeric)
parameter of the prior precision of pseudo efficacy responses. This is either a fixed value or a named vector with two positive numbers, the shape (a), and the rate (b) parameters for the gamma distribution.

use_fixed

(flag)
indicates whether nu specified is a fixed value or a vector with two parameters for gamma distribution. This slot is for internal purposes only and must not be used by the user.

theta1

(number)
the intercept in this efficacy log-log model. This slot is used in output to display the resulting prior or posterior modal estimates obtained based on the pseudo and observed (if any) data.

theta2

(number)
the slope in this efficacy log-log model. This slot is used in output to display the resulting prior or posterior modal estimates obtained based on the pseudo and observed (if any) data.

Pcov

(matrix)
refers to the 2 x 2 covariance matrix of the estimators of the intercept theta1 and the slope theta2 parameters in this model. This is used in output to display the resulting prior and posterior covariance matrix of theta1 and theta2 obtained, based on the pseudo and observed (if any) data. This slot is needed for internal purposes.

X

(matrix)
is the design matrix that is based on either the pseudo dose levels or observed dose levels (without DLT). This is used in the output to display the design matrix for the pseudo or the observed efficacy responses.

Y

(numeric)
is a vector that either contains the pseudo efficacy responses or observed efficacy responses (without DLT).

mu

(numeric)
a vector of the prior or the posterior modal estimates of the intercept (theta1) and the slope (theta2). This slot is used in output to display as the mean of the prior or posterior bivariate normal distribution for theta1 and theta2.

Q

(matrix)
is the prior or posterior (given that observed, no DLT data is available) precision matrix. It is specified as Q = X0^T * X0 + X^T * X, where X0 is a design matrix that is based on pseudo dose levels only, and X is a design matrix that is based on dose levels corresponding to the observed, no DLT efficacy values only (if any).

const

(number)
a non-negative number (default to 0), leading to the model form described above. In general, the model has the form y_i = theta1 + theta2 * log(log(x_i + const)) + epsilon_i, such that dose levels greater than 1 - const can be considered as described in Yeung et al. (2015).

Note

Typically, end users will not use the .DefaultEffloglog() function.

References

Yeung WY, Whitehead J, Reigner B, Beyer U, Diack C, Jaki T (2015). “Bayesian adaptive dose-escalation procedure for binary and continuous responses utilizing a gain function.” Pharmaceutical Statistics. doi:10.1002/pst.1706, Published online ahead of print.

Examples

# Obtain prior modal estimates given the pseudo data.
# First we use an empty data set such that only the dose levels under
# investigations are given. In total, 12 dose levels are under investigation
# ranging from 25 to 300 mg with increments of 25 (i.e 25, 50, 75, ..., 300).
emptydata <- DataDual(doseGrid = seq(25, 300, 25), placebo = FALSE)

# Define the pseudo data as first by fixing two dose levels 25 and 300 mg (`eff_dose`).
# Then, the efficacy responses observed at these two dose levels are 1.223 and 2.513 (`eff`).
# We specify the prior precision of the pseudo efficacy responses (`nu`) as a vector
# with the shape (a) and the rate (b) parameters for the gamma distribution.
# Obtain modal estimates and other estimates from the model (no observations,
# only pseudo data).
my_model1 <- Effloglog(
  eff = c(1.223, 2.513),
  eff_dose = c(25, 300),
  nu = c(a = 1, b = 0.025),
  data = emptydata
)

# Observed data.
my_data <- DataDual(
  x = c(25, 50, 50, 75, 100, 100, 225, 300),
  y = c(0, 0, 0, 0, 1, 1, 1, 1),
  w = c(0.31, 0.42, 0.59, 0.45, 0.6, 0.7, 0.6, 0.52),
  doseGrid = emptydata@doseGrid
)

# Obtain posterior modal estimates and other estimates from the model given some
# observed data.
my_model2 <- Effloglog(
  eff = c(1.223, 2.513),
  eff_dose = c(25, 300),
  nu = c(a = 1, b = 0.025),
  data = my_data
)

FractionalCRM

Description

FractionalCRM is the class for a fractional CRM model based on a one parameter CRM (with normal prior on the log-power parameter) as well as Kaplan-Meier based estimation of the conditional probability to experience a DLT for non-complete observations.

This fractional CRM model follows the paper and code by Yin et al. (2013).

Usage

FractionalCRM(...)

.DefaultFractionalCRM()

Arguments

Note

Typically, end users will not use the .DefaultTITELogisticLogNormal() function.

References

Yin G, Zheng S, Xu J (2013). “Fractional dose-finding methods with late-onset toxicity in phase I clinical trials.” Journal of Biopharmaceutical Statistics, 23(4), 856–870. doi:10.1080/10543406.2013.789892.

See Also

TITELogisticLogNormal.

Examples

my_model <- FractionalCRM(
  skel_probs = c(0.1, 0.2, 0.3, 0.4),
  dose_grid = c(10, 30, 50, 100),
  sigma2 = 2
)

GeneralData

Description

GeneralData is a class for general data input.

Usage

.DefaultDataGeneral()

Slots

ID

(integer)
unique patient IDs.

cohort

(integer)
the cohort (non-negative sorted) indices.

nObs

(integer)
number of observations, a single value.

Note

Typically, end users will not use the .DefaultDataGeneral() function.

GeneralModel

Description

GeneralModel is a general model class, from which all other specific model-like classes inherit.

Usage

.DefaultGeneralModel()

Slots

datamodel

(function)
a function representing the JAGS data model specification.

priormodel

(function)
a function representing the JAGS prior specification.

modelspecs

(function)
a function computing the list of the data model and prior model specifications that are required to be specified completely (e.g. prior parameters, reference dose, etc.), based on the data slots that are required as arguments of this function. Apart of data arguments, this function can be specified with one additional (optional) argument from_prior of type logical and length one. This from_prior flag can be used to differentiate the output of the modelspecs, as its value is taken directly from the from_prior argument of the mcmc method that invokes modelspecs function. That is, when from_prior is TRUE, then only priormodel JAGS model is used (datamodel is not used) by the mcmc, and hence modelspecs function should return all the parameters that are required by the priormodel only. If the value of from_prior is FALSE, then both JAGS models datamodel and priormodel are used in the MCMC sampler, and hence modelspecs function should return all the parameters required by both datamodel and priormodel.

init

(function)
a function computing the list of starting values for parameters required to be initialized in the MCMC sampler, based on the data slots that are required as arguments of this function.

datanames

(character)
the names of all data slots that are used by datamodel JAGS function. No other names should be specified here.

datanames_prior

(character)
the names of all data slots that are used by priormodel JAGS function. No other names should be specified here.

sample

(character)
names of all parameters from which you would like to save the MCMC samples.

Note

The datamodel must obey the convention that the data input is called exactly in the same way as in the corresponding data class. All prior distributions for parameters should be contained in the model function priormodel. The background is that this can be used to simulate from the prior distribution, before obtaining any data.

Typically, end users will not use the .DefaultGeneralModel() function.

See Also

ModelPseudo.

GeneralSimulations

Description

This class captures trial simulations. Here also the random generator state before starting the simulation is saved, in order to be able to reproduce the outcome. For this just use set.seed with the seed as argument before running simulate,Design-method.

Usage

GeneralSimulations(data, doses, seed)

.DefaultGeneralSimulations()

Arguments

Slots

data

(list)
produced Data objects.

doses

(numeric)
final dose recommendations.

seed

(integer)
random generator state before starting the simulation.

Note

Typically, end users will not use the .DefaultGeneralSimulations() function.

Examples

data <- list(
  Data(x = 1:3, y = c(0, 1, 0), doseGrid = 1:3, ID = 1L:3L, cohort = 1L:3L),
  Data(x = 4:6, y = c(0, 1, 0), doseGrid = 4:6, ID = 1L:3L, cohort = 1L:3L)
)

doses <- c(1, 2)

seed <- 123L

simulations <- GeneralSimulations(data, doses, seed)

GeneralSimulationsSummary

Description

This class captures the summary of general simulations output. Note that objects should not be created by users, therefore no initialization function is provided for this class.

Usage

.DefaultGeneralSimulationsSummary()

Slots

target

(numeric)
target toxicity interval

target_dose_interval

(numeric)
corresponding target dose interval

nsim

(integer)
number of simulations

prop_dlts

(ANY)
A numeric array (multi-dimensional) or list representing proportions of DLTs in the trials

mean_tox_risk

(numeric)
mean toxicity risks for the patients

dose_selected

(numeric)
doses selected as MTD

tox_at_doses_selected

(numeric)
true toxicity at doses selected

prop_at_target

(numeric)
Proportion of trials selecting target MTD

dose_most_selected

(numeric)
dose most often selected as MTD

obs_tox_rate_at_dose_most_selected

(numeric)
observed toxicity rate at dose most often selected

n_obs

(ANY)
A numeric array (multi-dimensional) or list representing number of patients overall.

n_above_target

(integer)
number of patients treated above target tox interval

dose_grid

(numeric)
the dose grid that has been used

placebo

(logical)
set to TRUE (default is FALSE) for a design with placebo

Note

Typically, end users will not use the .DefaultGeneralSimulationsSummary() function.

Increments

Description

Increments is a virtual class for controlling increments, from which all other specific increments classes inherit.

Usage

.DefaultIncrements()

Note

Typically, end users will not use the .DefaultIncrements() function.

See Also

IncrementsRelative, IncrementsRelativeDLT, IncrementsDoseLevels, IncrementsHSRBeta, IncrementsMin.

IncrementsDoseLevels

Description

IncrementsDoseLevels is the class for increments control based on the number of dose levels.

Usage

IncrementsDoseLevels(levels = 1L, basis_level = "last")

.DefaultIncrementsDoseLevels()

Arguments

Slots

levels

(count)
maximum number of dose levels to increment for the next dose. It defaults to 1, which means that no dose skipping is allowed, i.e. the next dose can be maximum one level higher than the current base dose. The current base dose level is the dose level used to increment from (see basis_level parameter).

basis_level

(string)
defines the current base dose level. It can take one out of two possible values: last or max. If last is specified (default), the current base dose level is set to the last dose given. If max is specified, then the current base dose level is set to the maximum dose level given.

Note

Typically, end users will not use the .DefaultIncrementsDoseLevels() function.

Examples

# The rule for dose increments which allows for maximum skip one dose level,
# that is 2 dose levels higher than the last dose given.
my_increments <- IncrementsDoseLevels(levels = 2, basis_level = "last")

IncrementsHSRBeta

Description

IncrementsHSRBeta is a class for limiting further increments using a Hard Safety Rule based on the Bin-Beta model. Increment control is based on the number of observed DLTs and number of subjects at each dose level. The probability of toxicity is calculated using a Bin-Beta model with prior (a,b). If the probability exceeds the threshold for a given dose, that dose and all doses above are excluded from further escalation. This is a hard safety rule that limits further escalation based on the observed data per dose level, independent from the underlying model.

Usage

IncrementsHSRBeta(target = 0.3, prob = 0.95, a = 1, b = 1)

.DefaultIncrementsHSRBeta()

Arguments

Slots

target

(proportion)
the target toxicity, except 0 or 1.

prob

(proportion)
the threshold probability (except 0 or 1) for a dose being toxic.

a

(number)
shape parameter a > 0 of probability distribution Beta (a,b).

b

(number)
shape parameter b > 0 of probability distribution Beta (a,b).

Note

Typically, end users will not use the .DefaultIncrementsHSRBeta() function.

Examples

# Limit the escalation with a hard safety criteria to the doses that are below
# the first dose that is toxic with a probability of 0.95.
my_increments <- IncrementsHSRBeta(target = 0.3, prob = 0.95)

IncrementsMaxToxProb

Description

IncrementsMaxToxProb is the class for increments control based on probability of toxicity

Usage

IncrementsMaxToxProb(prob)

.DefaultIncrementsMaxToxProb()

Arguments

Slots

prob

(numeric)
See Usage Notes below.

Usage Notes

For binary models, prob should be a scalar probability.

For ordinal models, prob should be a named vector containing the maximum permissible probability of toxicity by grade. The names should match the names of the yCategories slot of the associated DataOrdinal object.

Note

Typically, end users will not use the .DefaultIncrementsMaxToxProb() function.

Examples

# For use with binary models and data
IncrementsMaxToxProb(prob = 0.35)

# For use with ordinal models and data
IncrementsMaxToxProb(prob = c("DLAE" = 0.2, "DLT" = 0.05))

IncrementsMin

Description

IncrementsMin is the class that combines multiple increment rules with the minimum operation. Slot increments_list contains all increment rules, which are itself the objects of class Increments. The minimum of these individual increments is taken to give the final maximum increment.

Usage

IncrementsMin(increments_list)

.DefaultIncrementsMin()

Arguments

Slots

increments_list

(list)
list with increment rules.

Note

Typically, end users will not use the .DefaultIncrementsMin() function.

Examples

# As example, here we are combining 2 different increment rules.

# The first rule is the following:
# maximum doubling the dose if no DLTs were observed at the current dose
# or maximum increasing the dose by 1.33 if 1 or 2 DLTs were observed at the current dose
# or maximum increasing the dose by 1.22 if 3 or more DLTs were observed.
my_increments_1 <- IncrementsRelativeDLT(
  intervals = c(0, 1, 3),
  increments = c(1, 0.33, 0.2)
)

# The second rule is the following:
# maximum doubling the dose if the current dose is <20
# or only maximum increasing the dose by 1.33 if the current dose is >=20.
my_increments_2 <- IncrementsRelative(
  intervals = c(0, 20),
  increments = c(1, 0.33)
)

# Now we combine the 2 rules.
comb_increments <- IncrementsMin(
  increments_list = list(my_increments_1, my_increments_2)
)

IncrementsOrdinal

Description

IncrementsOrdinal is the class for applying a standard Increments rule to the results of an ordinal CRM trial.

Usage

IncrementsOrdinal(grade, rule)

.DefaultIncrementsOrdinal()

Arguments

Slots

grade

(integer)
the toxicity grade to which the rule should be applied.

rule

(Increments)
the standard Increments rule to be applied

Note

Typically, end users will not use the .DefaultIncrementsOrdinal() function.

Examples

IncrementsOrdinal(
  grade = 1L,
  rule = IncrementsRelative(
    intervals = c(0, 20),
    increments = c(1, 0.33)
  )
)

IncrementsRelative

Description

IncrementsRelative is the class for increments control based on relative differences in intervals.

Usage

IncrementsRelative(intervals, increments)

.DefaultIncrementsRelative()

Arguments

Slots

intervals

(numeric)
a vector with the left bounds of the relevant intervals. For example, intervals = c(0, 50, 100) specifies three intervals: (0, 50), [50, 100) and [100, +Inf). That means, the right bound of the intervals are exclusive to the interval and the last interval goes from the last value to infinity.

increments

(numeric)
a vector of the same length with the maximum allowable relative increments in the intervals.

Note

Typically, end users will not use the .DefaultIncrementsRelative() function.

Examples

# This is the example of a rule for:
# maximum doubling the dose if the current dose is <20
# or only maximum increasing the dose by 1.33 if the current dose is >=20.
my_increments <- IncrementsRelative(
  intervals = c(0, 20),
  increments = c(1, 0.33)
)

IncrementsRelativeDLT

Description

IncrementsRelativeDLT is the class for increments control based on relative differences in terms of DLTs.

Usage

IncrementsRelativeDLT(intervals, increments)

.DefaultIncrementsRelativeDLT()

Arguments

Slots

intervals

(integer)
a vector with the left bounds of the relevant DLT intervals. For example, intervals = c(0, 1, 3) specifies three intervals (sets of DLTs: first, 0 DLT; second 1 or 2 DLTs; and the third one, at least 3 DLTs. That means, the right bound of the intervals are exclusive to the interval and the last interval goes from the last value to infinity.

increments

(numeric)
a vector of maximum allowable relative increments corresponding to intervals. IT must be of the same length as the length of intervals.

Note

This considers all DLTs across all cohorts observed so far.

Typically, end users will not use the .DefaultIncrementsRelativeDLT() function.

See Also

IncrementsRelativeDLTCurrent which only considers the DLTs in the current cohort.

Examples

# This is the example of a rule for:
# maximum doubling the dose if no DLTs were observed in the whole study so far
# or maximum increasing the dose by 1.33 if 1 or 2 DLTs were observed so far
# or maximum increasing the dose by 1.22 if 3 or more DLTs were observed so far.
my_increments <- IncrementsRelativeDLT(
  intervals = c(0, 1, 3),
  increments = c(1, 0.33, 0.2)
)

IncrementsRelativeDLTCurrent

Description

IncrementsRelativeDLTCurrent is the class for increments control based on relative differences and current DLTs. The class is based on the number of DLTs observed in the current cohort, but not cumulatively over all cohorts so far.

Usage

IncrementsRelativeDLTCurrent(intervals = c(0L, 1L), increments = c(2L, 1L))

.DefaultIncrementsRelativeDLTCurrent()

Arguments

Note

Typically, end users will not use the .DefaultIncrementsRelativeDLTCurrent() function.

See Also

IncrementsRelativeDLT.

Examples

# As example, here is the rule for:
# maximum doubling the dose if no DLTs were observed at the current dose
# or maximum increasing the dose by 1.33 if 1 or 2 DLTs were observed at the current dose
# or maximum increasing the dose by 1.22 if 3 or more DLTs were observed.

my_increments <- IncrementsRelativeDLTCurrent(
  intervals = c(0, 1, 3),
  increments = c(1, 0.33, 0.2)
)

IncrementsRelativeParts

Description

IncrementsRelativeParts is the class for increments control based on relative differences in intervals, with special rules for part 1 and beginning of part 2.

Usage

IncrementsRelativeParts(dlt_start, clean_start, ...)

.DefaultIncrementsRelativeParts()

Arguments

Details

This class works only in conjunction with DataParts objects. If part 2 will just be started in the next cohort, then the next maximum dose will be either dlt_start (e.g. -1) shift of the last part 1 dose in case of a DLT in part 1, or clean_start shift (e.g. -1) in case of no DLTs in part 1, given that clean_start <= 0 (see description of clean_start slot for more details). If part 1 will still be on in the next cohort, then the next dose level will be the next higher dose level in the part1Ladder slot of the data object. If part 2 has been started before, the usual relative increment rules apply, see IncrementsRelative.

Slots

dlt_start

(integer)
a scalar, the dose level increment for starting part 2 in case of at least one DLT event in part 1.

clean_start

(integer)
a scalar, the dose level increment for starting part 2 in case of no DLTs in part 1. If clean_start <= 0, then the part 1 ladder will be used to find the maximum next dose. Otherwise, the relative increment rules will be applied to find the next maximum dose level.

Note

We require that clean_start >= dlt_start. However, this precondition is not a prerequisite for any function (except of the class' validation function) that works with objects of this class. It is rather motivated by the semantics. That is, if we observe a DLT in part 1, we cannot be more aggressive than in case of a clean part 1 without DLT.

Typically, end users will not use the .DefaultIncrementsRelativeParts() function.

Examples

my_increments <- IncrementsRelativeParts(dlt_start = 0, clean_start = 1)

LogisticIndepBeta

Description

LogisticIndepBeta is the class for the two-parameters logistic regression dose-limiting events (DLE) model with prior expressed in form of pseudo data. This model describes the relationship between the binary DLE responses and the dose levels. More specifically, it represents the relationship of the probabilities of the occurrence of a DLE for corresponding dose levels in log scale. This model is specified as

p(x) = exp(phi1 + phi2 * log(x)) / (1 + exp(phi1 + phi2 * log(x)))

where p(x) is the probability of the occurrence of a DLE at dose x. The two parameters of this model are the intercept phi1 and the slope phi2. The LogisticIndepBeta inherits all slots from ModelTox class.

In the context of pseudo data, the following three arguments are used, binDLE, DLEdose and DLEweights. The DLEdose represents fixed dose levels at which the pseudo DLE responses binDLE are observed. DLEweights represents total number of subjects treated per each dose level in DLEdose. The binDLE represents the number of subjects observed with DLE per each dose level in DLEdose. Hence, all these three vectors must be of the same length and the order of the elements in any of the vectors binDLE, DLEdose and DLEweights must be kept, so that an element of a given vector corresponds to the elements of the remaining two vectors (see the example for more insight). Finally, since at least two DLE pseudo responses are needed to obtain prior modal estimates (same as the maximum likelihood estimates) for the model parameters, the binDLE, DLEdose and DLEweights must all be vectors of at least length 2.

Usage

LogisticIndepBeta(binDLE, DLEdose, DLEweights, data)

.DefaultLogisticIndepBeta()

Arguments

Details

The pseudo data can be interpreted as if we obtain some observations before the trial starts. It can be used to express our prior, i.e. the initial beliefs for the model parameters. The pseudo data is expressed in the following way. First, fix at least two dose levels, then ask for experts' opinion on how many subjects are to be treated at each of these dose levels and on the number of subjects observed with a DLE. At each dose level, the number of subjects observed with a DLE, divided by the total number of subjects treated, is the probability of the occurrence of a DLE at that particular dose level. The probabilities of the occurrence of a DLE based on this pseudo data are independent and they follow Beta distributions. Therefore, the joint prior probability density function of all these probabilities can be obtained. Hence, by a change of variable, the joint prior probability density function of the two parameters in this model can also be obtained. In addition, a conjugate joint prior density function of the two parameters in the model is used. For details about the form of all these joint prior and posterior probability density functions, please refer to Whitehead and Williamson (1998).

Slots

binDLE

(numeric)
a vector of total numbers of DLE responses. It must be at least of length 2 and the order of its elements must correspond to values specified in DLEdose and DLEweights.

DLEdose

(numeric)
a vector of the dose levels corresponding to It must be at least of length 2 and the order of its elements must correspond to values specified in binDLE and DLEweights.

DLEweights

(integer)
total number of subjects treated at each of the pseudo dose level DLEdose. It must be at least of length 2 and the order of its elements must correspond to values specified in binDLE and DLEdose.

phi1

(number)
the intercept of the model. This slot is used in output to display the resulting prior or posterior modal estimate of the intercept obtained based on the pseudo data and (if any) observed data/responses.

phi2

(number)
the slope of the model. This slot is used in output to display the resulting prior or posterior modal estimate of the slope obtained based on the pseudo data and (if any) the observed data/responses.

Pcov

(matrix)
refers to the 2x2 covariance matrix of the intercept (phi1) and the slope parameters (phi2) of the model. This is used in output to display the resulting prior and posterior covariance matrix of phi1 and phi2 obtained, based on the pseudo data and (if any) the observed data and responses. This slot is needed for internal purposes.

Note

Typically, end users will not use the .DefaultLogisticIndepBeta() function.

References

Whitehead J, Williamson D (1998). “Bayesian decision procedures based on logistic regression models for dose-finding studies.” Journal of Biopharmaceutical Statistics, 8(3), 445–467.

Examples

# Obtain prior modal estimates given the pseudo data.
# First we used an empty data set such that only the dose levels under
# investigations are given. In total, 12 dose levels are under investigation
# ranging from 25 to 300 mg with increments of 25 (i.e 25, 50, 75, ..., 300).
emptydata <- Data(doseGrid = seq(25, 300, 25))

# Fix two dose levels 25 and 300 mg (DLEdose).
# Total number of subjects treated in each of these levels is 3, (DLEweights).
# The number of subjects observed with a DLE is 1.05 at dose 25 mg and 1.8 at dose 300 mg (binDLE).
my_model1 <- LogisticIndepBeta(
  binDLE = c(1.05, 1.8),
  DLEdose = c(25, 300),
  DLEweights = c(3, 3),
  data = emptydata
)

# Use observed DLE responses to obtain posterior modal estimates.
my_data <- Data(
  x = c(25, 50, 50, 75, 100, 100, 225, 300),
  y = c(0, 0, 0, 0, 1, 1, 1, 1),
  doseGrid = emptydata@doseGrid
)

my_model2 <- LogisticIndepBeta(
  binDLE = c(1.05, 1.8),
  DLEdose = c(25, 300),
  DLEweights = c(3, 3),
  data = my_data
)

LogisticKadane

Description

LogisticKadane is the class for the logistic model in the parametrization of Kadane et al. (1980).

Usage

LogisticKadane(theta, xmin, xmax)

.DefaultLogisticKadane()

Arguments

Details

Let rho0 = p(xmin) be the probability of a DLT at the minimum dose xmin, and let gamma be the dose with target toxicity probability theta, i.e. p(gamma) = theta. Then it can easily be shown that the logistic regression model has intercept

[gamma * logit(rho0) - xmin * logit(theta)] / [gamma - xmin]

and slope

[logit(theta) - logit(rho0)] / [gamma - xmin].

The priors are

gamma ~ Unif(xmin, xmax).

and

rho0 ~ Unif(0, theta).

Slots

theta

(proportion)
the target toxicity probability.

xmin

(number)
the minimum of the dose range.

xmax

(number)
the maximum of the dose range.

Note

The slots of this class, required for creating the model, are the target toxicity, as well as the minimum and maximum of the dose range. Note that these can be different from the minimum and maximum of the dose grid in the data later on.

Typically, end-users will not use the .DefaultLogisticKadane() function.

References

Kadane JB, Dickey JM, Winkler RL, Smith WS, Peters SC (1980). “Interactive Elicitation of Opinion for a Normal Linear Model.” Journal of the American Statistical Association, 75(372), 845–854. ISSN 01621459, 1537274X, doi:10.2307/2287171, http://www.jstor.org/stable/2287171.

See Also

ModelLogNormal

Examples

my_model <- LogisticKadane(theta = 0.33, xmin = 1, xmax = 200)

LogisticKadaneBetaGamma

Description

LogisticKadaneBetaGamma is the class for the logistic model in the parametrization of Kadane et al. (1980), using a beta and a gamma distribution as the model priors.

Usage

LogisticKadaneBetaGamma(theta, xmin, xmax, alpha, beta, shape, rate)

.DefaultLogisticKadaneBetaGamma()

Arguments

Details

Let rho0 = p(xmin) be the probability of a DLT at the minimum dose xmin, and let gamma be the dose with target toxicity probability theta, i.e. p(gamma) = theta. Then it can easily be shown that the logistic regression model has intercept

[gamma * logit(rho0) - xmin * logit(theta)] / [gamma - xmin]

and slope

[logit(theta) - logit(rho0)] / [gamma - xmin].

The prior for gamma, is

gamma ~ Gamma(shape, rate).

. The prior for rho0 = p(xmin), is

rho0 ~ Beta(alpha, beta).

Slots

theta

(proportion)
the target toxicity probability.

xmin

(number)
the minimum of the dose range.

xmax

(number)
the maximum of the dose range.

alpha

(number)
the first shape parameter of the Beta prior distribution of rho0 = p(xmin) the probability of a DLT at the minimum dose xmin.

beta

(number)
the second shape parameter of the Beta prior distribution of rho0 = p(xmin) the probability of a DLT at the minimum dose xmin.

shape

(number)
the shape parameter of the Gamma prior distribution of gamma the dose with target toxicity probability theta.

rate

(number)
the rate parameter of the Gamma prior distribution of gamma the dose with target toxicity probability theta.

Note

The slots of this class, required for creating the model, are the same as in the LogisticKadane class. In addition, the shape parameters of the Beta prior distribution of rho0 and the shape and rate parameters of the Gamma prior distribution of gamma, are required for creating the prior model.

Typically, end users will not use the .Default() function.

References

Kadane JB, Dickey JM, Winkler RL, Smith WS, Peters SC (1980). “Interactive Elicitation of Opinion for a Normal Linear Model.” Journal of the American Statistical Association, 75(372), 845–854. ISSN 01621459, 1537274X, doi:10.2307/2287171, http://www.jstor.org/stable/2287171.

See Also

ModelLogNormal, LogisticKadane.

Examples

my_model <- LogisticKadaneBetaGamma(
  theta = 0.3,
  xmin = 0,
  xmax = 7,
  alpha = 1,
  beta = 19,
  shape = 0.5625,
  rate = 0.125
)

LogisticLogNormal

Description

LogisticLogNormal is the class for the usual logistic regression model with a bivariate normal prior on the intercept and log slope.

Usage

LogisticLogNormal(mean, cov, ref_dose = 1)

.DefaultLogisticLogNormal()

Arguments

Details

The covariate is the natural logarithm of the dose x divided by the reference dose x*, i.e.:

logit[p(x)] = alpha0 + alpha1 * log(x/x*),

where p(x) is the probability of observing a DLT for a given dose x. The prior

(alpha0, log(alpha1)) ~ Normal(mean, cov).

Note

Typically, end users will not use the .DefaultLogisticLogNormal() function.

See Also

ModelLogNormal, LogisticNormal, LogisticLogNormalSub, ProbitLogNormal, ProbitLogNormalRel, LogisticLogNormalMixture, DALogisticLogNormal.

Examples

my_model <- LogisticLogNormal(
  mean = c(-0.85, 1),
  cov = matrix(c(1, -0.5, -0.5, 1), nrow = 2),
  ref_dose = 50
)
my_model

LogisticLogNormalGrouped

Description

LogisticLogNormalGrouped is the class for a logistic regression model for both the mono and the combo arms of the simultaneous dose escalation design.

Usage

LogisticLogNormalGrouped(mean, cov, ref_dose = 1)

.DefaultLogisticLogNormalGrouped()

Arguments

Details

The continuous covariate is the natural logarithm of the dose x divided by the reference dose x* as in LogisticLogNormal. In addition, I_c is a binary indicator covariate which is 1 for the combo arm and 0 for the mono arm. The model is then defined as:

logit[p(x)] = (alpha0 + I_c * delta0) + (alpha1 + I_c * delta1) * log(x / x*),

where p(x) is the probability of observing a DLT for a given dose x, and delta0 and delta1 are the differences in the combo arm compared to the mono intercept and slope parameters alpha0 and alpha1. The prior is defined as

(alpha0, log(delta0), log(alpha1), log(delta1)) ~ Normal(mean, cov).

Note

Typically, end users will not use the .DefaultLogisticLogNormalGrouped() function.

See Also

ModelLogNormal, LogisticLogNormal.

Examples

my_model <- LogisticLogNormalGrouped(
  mean = c(-0.85, 0, 1, 0),
  cov = diag(1, 4),
  ref_dose = 50
)
my_model

LogisticLogNormalMixture

Description

LogisticLogNormalMixture is the class for standard logistic model with online mixture of two bivariate log normal priors.

Usage

LogisticLogNormalMixture(mean, cov, ref_dose, share_weight)

.DefaultLogisticLogNormalMixture()

Arguments

Details

This model can be used when data is arising online from the informative component of the prior, at the same time with the data of the trial of main interest. Formally, this is achieved by assuming that the probability of a DLT at dose x is given by

p(x) = \pi * p1(x) + (1 - \pi) * p2(x)

where \pi is the probability for the model p(x) being the same as the model p1(x), which is the informative component of the prior. From this model data arises in parallel: at doses xshare, DLT information yshare is observed, in total nObsshare data points (see DataMixture). On the other hand, 1 - \pi, is the probability of a separate model p2(x). Both components have the same log normal prior distribution, which can be specified by the user, and which is inherited from the LogisticLogNormal class.

Slots

share_weight

(proportion)
the prior weight for the share component p_{1}(x).

Note

Typically, end users will not use the .DefaultLogNormalMixture() function.

See Also

ModelLogNormal, LogisticNormalMixture, LogisticNormalFixedMixture.

Examples

# Decide on the dose grid and MCMC options.
dose_grid <- 1:80
my_options <- McmcOptions()

# Classic model.
my_model <- LogisticLogNormal(
  mean = c(-0.85, 1),
  cov = matrix(c(1, -0.5, -0.5, 1), nrow = 2),
  ref_dose = 50
)

empty_data <- Data(doseGrid = dose_grid)
prior_samples <- mcmc(empty_data, my_model, my_options)
plot(prior_samples, my_model, empty_data)

# Set up the mixture model and data share object.
model_share <- LogisticLogNormalMixture(
  share_weight = 0.1,
  mean = c(-0.85, 1),
  cov = matrix(c(1, -0.5, -0.5, 1), nrow = 2),
  ref_dose = 50
)

empty_data_share <- DataMixture(
  doseGrid = dose_grid,
  xshare = rep(c(10, 20, 40), each = 4),
  yshare = rep(0L, 12),
)

# Compare with the resulting prior model.
prior_samples_share <- mcmc(empty_data_share, model_share, my_options)
plot(prior_samples_share, model_share, empty_data_share)

LogisticLogNormalOrdinal

Description

LogisticLogNormalOrdinal is the class for a logistic lognormal CRM model using an ordinal toxicity scale.

Usage

LogisticLogNormalOrdinal(mean, cov, ref_dose)

.DefaultLogisticLogNormalOrdinal()

Arguments

Note

Typically, end users will not use the .DefaultLogisticLogNormalOrdinal() function.

Examples

LogisticLogNormalOrdinal(
  mean = c(3, 4, 0),
  cov = diag(c(4, 3, 1)),
  ref_dose = 1
)

LogisticLogNormalSub

Description

LogisticLogNormalSub is the class for a standard logistic model with bivariate (log) normal prior with subtractive dose standardization.

Usage

LogisticLogNormalSub(mean, cov, ref_dose = 0)

.DefaultLogisticLogNormalSub()

Arguments

Details

The covariate is the dose x minus the reference dose x*, i.e.:

logit[p(x)] = alpha0 + alpha1 * (x - x*),

where p(x) is the probability of observing a DLT for a given dose x. The prior

(alpha0, log(alpha1)) ~ Normal(mean, cov).

Slots

params

(ModelParamsNormal)
bivariate normal prior parameters.

ref_dose

(number)
the reference dose x*.

Note

Typically, end-users will not use the .DefaultLogisticLogNormalSub() function.

See Also

LogisticNormal, LogisticLogNormal, ProbitLogNormal, ProbitLogNormalRel.

Examples

my_model <- LogisticLogNormalSub(
  mean = c(-0.85, 1),
  cov = matrix(c(1, -0.5, -0.5, 1), nrow = 2),
  ref_dose = 50
)

LogisticNormal

Description

LogisticNormal is the class for the usual logistic regression model with a bivariate normal prior on the intercept and slope.

Usage

LogisticNormal(mean, cov, ref_dose = 1)

.DefaultLogisticNormal()

Arguments

Details

The covariate is the natural logarithm of the dose x divided by the reference dose x*, i.e.:

logit[p(x)] = alpha0 + alpha1 * log(x/x*),

where p(x) is the probability of observing a DLT for a given dose x. The prior

(alpha0, alpha1) ~ Normal(mean, cov).

Note

Typically, end users will not use the .DefaultLogisticNormal() function.

See Also

ModelLogNormal, LogisticLogNormal, LogisticLogNormalSub, ProbitLogNormal, ProbitLogNormalRel, LogisticNormalMixture.

Examples

# Define the dose-grid.
empty_data <- Data(doseGrid = c(1, 3, 5, 10, 15, 20, 25, 40, 50, 80, 100))

my_model <- LogisticNormal(
  mean = c(-0.85, 1),
  cov = matrix(c(1, -0.5, -0.5, 1), nrow = 2)
)

my_options <- McmcOptions(burnin = 10, step = 2, samples = 100)

samples <- mcmc(empty_data, my_model, my_options)
samples

LogisticNormalFixedMixture

Description

LogisticNormalFixedMixture is the class for standard logistic regression model with fixed mixture of multiple bivariate (log) normal priors on the intercept and slope parameters. The weights of the normal priors are fixed, hence no additional model parameters are introduced. This type of prior is often used to better approximate a given posterior distribution, or when the information is given in terms of a mixture.

Usage

LogisticNormalFixedMixture(components, weights, ref_dose, log_normal = FALSE)

.DefaultLogisticNormalFixedMixture()

Arguments

Details

The covariate is the natural logarithm of the dose x divided by the reference dose x*, i.e.:

logit[p(x)] = alpha0 + alpha1 * log(x/x*),

where p(x) is the probability of observing a DLT for a given dose x. The prior

(alpha0, alpha1) ~ w1 * Normal(mean1, cov1) + ... + wK * Normal(meanK, covK),

if a normal prior is used and

(alpha0, log(alpha1)) ~ w1 * Normal(mean1, cov1) + ... + wK * Normal(meanK, covK),

if a log normal prior is used. The weights w1, ..., wK of the components are fixed and sum to 1.

The slots of this class comprise a list with components parameters. Every single component contains the mean vector and the covariance matrix of bivariate normal distributions. Remaining slots are the weights of the components as well as the reference dose. Moreover, a special indicator slot specifies whether a log normal prior is used.

Slots

components

(list)
the specifications of the mixture components, a list with ModelParamsNormal objects for each bivariate (log) normal prior.

weights

(numeric)
the weights of the components; these must be positive and must sum to 1.

ref_dose

(positive_number)
the reference dose.

log_normal

(flag)
should a log normal prior be used, such that the mean vectors and covariance matrices are valid for the intercept and log slope?

Note

Typically, end-users will not use the .DefaultLogisticNormalFixedMixture() function.

See Also

ModelParamsNormal, ModelLogNormal, LogisticNormalMixture, LogisticLogNormalMixture.

Examples

my_model <- LogisticNormalFixedMixture(
  components = list(
    comp1 = ModelParamsNormal(
      mean = c(-0.85, 1),
      cov = matrix(c(1, -0.5, -0.5, 1), nrow = 2)
    ),
    comp2 = ModelParamsNormal(
      mean = c(1, 1.5),
      cov = matrix(c(1.2, -0.45, -0.45, 0.6), nrow = 2)
    )
  ),
  weights = c(0.3, 0.7),
  ref_dose = 50
)

LogisticNormalMixture

Description

LogisticNormalMixture is the class for standard logistic regression model with a mixture of two bivariate normal priors on the intercept and slope parameters.

Usage

LogisticNormalMixture(comp1, comp2, weightpar, ref_dose)

.DefaultLogisticNormalMixture()

Arguments

Details

The covariate is the natural logarithm of the dose x divided by the reference dose x*, i.e.:

logit[p(x)] = alpha0 + alpha1 * log(x/x*),

where p(x) is the probability of observing a DLT for a given dose x. The prior

(alpha0, alpha1) ~ w * Normal(mean1, cov1) + (1 - w) * Normal(mean2, cov2).

The weight w for the first component is assigned a beta prior B(a, b).

Slots

comp1

(ModelParamsNormal)
bivariate normal prior specification of the first component.

comp2

(ModelParamsNormal)
bivariate normal prior specification of the second component.

weightpar

(numeric)
the beta parameters for the weight of the first component. It must a be a named vector of length 2 with names a and b and with strictly positive values.

ref_dose

(positive_number)
the reference dose.

Note

The weight of the two normal priors is a model parameter, hence it is a flexible mixture. This type of prior is often used with a mixture of a minimal informative and an informative component, in order to make the CRM more robust to data deviations from the informative component.

Typically, end-users will not use the .DefaultLogisticNormalMixture() function.

See Also

ModelParamsNormal, ModelLogNormal, LogisticNormalFixedMixture, LogisticLogNormalMixture.

Examples

my_model <- LogisticNormalMixture(
  comp1 = ModelParamsNormal(
    mean = c(-0.85, 1),
    cov = matrix(c(1, -0.5, -0.5, 1), nrow = 2)
  ),
  comp2 = ModelParamsNormal(
    mean = c(1, 1.5),
    cov = matrix(c(1.2, -0.45, -0.45, 0.6), nrow = 2)
  ),
  weightpar = c(a = 1, b = 1),
  ref_dose = 50
)

McmcOptions

Description

McmcOptions is a class for the three canonical MCMC options as well as Random Number Generator settings.

Usage

McmcOptions(
  burnin = 10000L,
  step = 2L,
  samples = 10000L,
  rng_kind = NA_character_,
  rng_seed = NA_integer_
)

.DefaultMcmcOptions()

Arguments

Slots

iterations

(count)
number of MCMC iterations.

burnin

(count)
number of burn-in iterations which are not saved.

step

(count)
only every step-th iteration is saved after the burnin. In other words, a sample from iteration ⁠i = 1,...,iterations⁠, is saved if and only if ⁠(i - burnin) mod step = 0⁠.
For example, for iterations = 6, burnin = 0 and step = 2, only samples from iterations ⁠2,4,6⁠ will be saved.

rng_kind

(string)
a Random Number Generator (RNG) type used by rjags::rjags. It must be one out of the following four values: base::Wichmann-Hill, base::Marsaglia-Multicarry, base::Super-Duper, base::Mersenne-Twister, or NA_character_. If it is NA_character_ (default), then the RNG kind will be chosen by rjags::rjags.

rng_seed

(number)
a Random Number Generator (RNG) seed used by rjags::rjags for a chosen rng_kind. It must be an integer scalar or NA_integer_, which means that the seed will be chosen by rjags::rjags.

Note

Typically, end users will not use the .DefaultMcmcOptions() function.

Examples

# Set up MCMC option in order to have a burn-in of 10000 iterations and
# then take every other iteration up to a collection of 10000 samples.
McmcOptions(burnin = 10000, step = 2, samples = 10000)

Construct a Minimally Informative Prior

Description

This function constructs a minimally informative prior, which is captured in a LogisticNormal (or LogisticLogNormal) object.

Based on the proposal by Neuenschwander et al. (2008), a minimally informative prior distribution is constructed. The required key input is the minimum (d_{1} in the notation of the Appendix A.1 of that paper) and the maximum value (d_{J}) of the dose grid supplied to this function. Then threshmin is the probability threshold q_{1}, such that any probability of DLT larger than q_{1} has only 5% probability. Therefore q_{1} is the 95% quantile of the beta distribution and hence p_{1} = 0.95. Likewise, threshmax is the probability threshold q_{J}, such that any probability of DLT smaller than q_{J} has only 5% probability (p_{J} = 0.05). The probabilities 1 - p_{1} and p_{J} can be controlled with the arguments probmin and probmax, respectively. Subsequently, for all doses supplied in the dosegrid argument, beta distributions are set up from the assumption that the prior medians are linear in log-dose on the logit scale, and Quantiles2LogisticNormal() is used to transform the resulting quantiles into an approximating LogisticNormal (or LogisticLogNormal) model. Note that the reference dose is not required for these computations.

Usage

MinimalInformative(
  dosegrid,
  refDose,
  threshmin = 0.2,
  threshmax = 0.3,
  probmin = 0.05,
  probmax = 0.05,
  ...
)

Arguments

Value

See Quantiles2LogisticNormal().

References

Neuenschwander B, Branson M, Gsponer T (2008). “Critical aspects of the Bayesian approach to phase I cancer trials.” Statistics in Medicine, 27(13), 2420–2439. https://onlinelibrary.wiley.com/doi/10.1002/sim.3230.

Examples

# Setting up a minimal informative prior 
# max.time is quite small only for the purpose of showing the example. They 
# should be increased for a real case.
set.seed(132)
coarseGrid <- c(0.1, 10, 30, 60, 100)
minInfModel <- MinimalInformative(dosegrid = coarseGrid,
                                  refDose=50,
                                  threshmin=0.2,
                                  threshmax=0.3,
                                  control=## for real case: leave out control 
                                    list(max.time=0.1)) 

# Plotting the result
matplot(x=coarseGrid,
        y=minInfModel$required,
        type="b", pch=19, col="blue", lty=1,
        xlab="dose",
        ylab="prior probability of DLT")
matlines(x=coarseGrid,
         y=minInfModel$quantiles,
         type="b", pch=19, col="red", lty=1)
legend("right",
       legend=c("quantiles", "approximation"),
       col=c("blue", "red"),
       lty=1,
       bty="n")

ModelEff

Description

ModelEff is the parent class for efficacy models using pseudo data prior. It is dedicated all efficacy models that have their prior specified in the form of pseudo data (as if there is some data before the trial starts).

The data must obey the convention of the DataDual class. This refers to any observed efficacy/biomarker responses (w in DataDual), the dose levels at which these responses are observed (x in DataDual), all dose levels considered in the study (doseGrid in DataDual), and finally other specifications in DataDual class that can be used to generate prior or posterior modal estimates or samples estimates for model parameter(s). If no responses are observed, at least doseGrid has to be specified in data for which prior modal estimates or samples can be obtained for model parameters based on the specified pseudo data.

Usage

.DefaultModelEff()

Slots

data

(DataDual)
observed data that is used to obtain model parameters estimates or samples (see details above).

Note

Typically, end users will not use the .DefaultModelEff() function.

See Also

ModelTox.

ModelLogNormal

Description

ModelLogNormal is the class for a model with a reference dose and bivariate normal prior on the model parameters alpha0 and natural logarithm of alpha1, i.e.:

(alpha0, log(alpha1)) ~ Normal(mean, cov),

. Transformations other than log, e.g. identity, can be specified too in priormodel slot. The parameter alpha1 has a log-normal distribution by default to ensure positivity of alpha1 which further guarantees exp(alpha1) > 1. The slots of this class contain the mean vector, the covariance and precision matrices of the bivariate normal distribution, as well as the reference dose. Note that the precision matrix is an inverse of the covariance matrix in the JAGS. All ("normal") model specific classes inherit from this class.

Usage

ModelLogNormal(mean, cov, ref_dose = 1)

.DefaultModelLogNormal()

Arguments

Slots

params

(ModelParamsNormal)
bivariate normal prior parameters.

ref_dose

(positive_number)
the reference dose.

Note

Typically, end users will not use the .DefaultModelLogNormal() function.

See Also

ModelParamsNormal, LogisticNormal, LogisticLogNormal, LogisticLogNormalSub, ProbitLogNormal, ProbitLogNormalRel.

ModelParamsNormal

Description

ModelParamsNormal is the class for a bivariate normal model parameters, i.e. the mean vector, covariance matrix and precision matrix. The precision matrix is an inverse of the covariance matrix in the JAGS and it is computed internally by the object constructor function.

Usage

ModelParamsNormal(mean, cov)

.DefaultModelParamsNormal()

Arguments

Slots

mean

(numeric)
the mean vector.

cov

(matrix)
the covariance matrix.

prec

(matrix)
the precision matrix, which is an inverse matrix of the cov.

Note

Typically, end users will not use the .ModelPAramsNormal() function.

See Also

ModelLogNormal, LogisticNormalMixture.

Examples

ModelParamsNormal(mean = c(1, 6), cov = diag(2))

ModelPseudo

Description

ModelPseudo is the parent class for models that express their prior in the form of pseudo data (as if there is some data before the trial starts).

Usage

.DefaultModelPseudo()

Note

Typically, end users will not use the .DefaultModelPseudo() function.

See Also

GeneralModel.

ModelTox

Description

ModelTox is the parent class for DLE (dose-limiting events) models using pseudo data prior. It is dedicated for DLE models or toxicity models that have their prior specified in the form of pseudo data (as if there is some data before the trial starts).

The data must obey the convention of the Data class. This refers to any observed DLE responses (y in Data), the dose levels (x in Data) at which these responses are observed, all dose levels considered in the study (doseGrid in Data), and finally other specifications in Data class that can be used to generate prior or posterior modal estimates or samples estimates for model parameter(s). If no responses are observed, at least doseGrid has to be specified in data for which prior modal estimates or samples can be obtained for model parameters based on the specified pseudo data.

Usage

.DefaultModelTox()

Slots

data

(Data)
observed data that is used to obtain model parameters estimates or samples (see details above).

Note

Typically, end users will not use the .DefaultModelTox() function.

See Also

ModelEff.

NextBest

Description

NextBest is a virtual class for finding next best dose, from which all other specific next best dose classes inherit.

Usage

.DefaultNextBest()

Note

Typically, end users will not use the DefaultNextBest() function.

See Also

NextBestEWOC, NextBestMTD, NextBestNCRM, NextBestNCRMLoss, NextBestThreePlusThree, NextBestDualEndpoint, NextBestMinDist, NextBestInfTheory, NextBestTD, NextBestTDsamples, NextBestMaxGain, NextBestMaxGainSamples, NextBestProbMTDLTE, NextBestProbMTDMinDist, NextBestOrdinal.

NextBestDualEndpoint

Description

NextBestDualEndpoint is the class for next best dose that is based on the dual endpoint model.

Usage

NextBestDualEndpoint(
  target,
  overdose,
  max_overdose_prob,
  target_relative = TRUE,
  target_thresh = 0.01
)

.DefaultNextBestDualEndpoint()

Arguments

Details

Under this rule, at first admissible doses are found, which are those with toxicity probability to fall in overdose category and being below max_overdose_prob. Next, it picks (from the remaining admissible doses) the one that maximizes the probability to be in the target biomarker range. By default (target_relative = TRUE) the target is specified as relative to the maximum biomarker level across the dose grid or relative to the Emax parameter in case a parametric model was selected (i.e. DualEndpointBeta, DualEndpointEmax). However, if target_relative = FALSE, then the absolute biomarker range can be used as a target.

Slots

target

(numeric)
the biomarker target range that needs to be reached. For example, the target range (0.8, 1.0) and target_relative = TRUE means that we target a dose with at least 80\% of maximum biomarker level. As an other example, (0.5, 0.8) would mean that we target a dose between 50\% and 80\% of the maximum biomarker level.

overdose

(numeric)
the overdose toxicity interval (lower limit excluded, upper limit included).

max_overdose_prob

(proportion)
maximum overdose probability that is allowed.

target_relative

(flag)
is target specified as relative? If TRUE, then the target is interpreted relative to the maximum, so it must be a probability range. Otherwise, the target is interpreted as absolute biomarker range.

target_thresh

(proportion)
a target probability threshold that needs to be fulfilled before the target probability will be used for deriving the next best dose (default to 0.01).

Note

Typically, end users will not use the .DefaultNextBestDualEndpoint() function.

Examples

# Target a dose achieving at least 0.9 of maximum biomarker level (efficacy)
# and with a probability below 0.25 that prob(DLT) > 0.35 (safety).
my_next_best <- NextBestDualEndpoint(
  target = c(0.9, 1),
  overdose = c(0.35, 1),
  max_overdose_prob = 0.25
)

# Now, using absolute target on the natural biomarker scale.
my_next_best_absolute <- NextBestDualEndpoint(
  target = c(200, 300),
  overdose = c(0.35, 1),
  max_overdose_prob = 0.25,
  target_relative = FALSE
)

NextBestEWOC

Description

NextBestEWOC is the class implementing Escalation With Overdose Control (EWOC). It recommends the highest possible dose subject to a probabilistic constraint that the posterior probability of overdosing does not exceed max_overdose_prob. Overdosing is defined as the model-based toxicity probability lying inside the interval given by overdose.

Usage

NextBestEWOC(target, overdose, max_overdose_prob)

.DefaultNextBestEWOC()

Arguments

Slots

target

(proportion)
target toxicity probability to be achieved, below overdose[1]; only used for simulation reporting purposes.

overdose

(numeric)
the (exclusive) lower and (inclusive) upper boundaries of the toxicity probability interval considered an overdose region. The prototype uses c(0.35, 1) meaning probabilities > 0.35 are treated as overly toxic.

max_overdose_prob

(proportion)
maximum acceptable posterior probability that the next recommended dose is in the overdose interval.

Note

Typically, end users will not use the .DefaultNextBestEWOC() function.

See Also

NextBest, other next-best classes listed in its documentation.

Examples

# Example: Define EWOC next best dose rule.
# Target toxicity probability is 0.30. Overdose region is any probability > 0.35.
# We restrict posterior probability of recommending an overdosing dose to <= 0.25.
next_best_ewoc <- NextBestEWOC(
  target = 0.30,
  overdose = c(0.35, 1),
  max_overdose_prob = 0.25
)

NextBestInfTheory

Description

NextBestInfTheory is the class for next best dose that is based on information theory as proposed in https://doi.org/10.1002/sim.8450.

Usage

NextBestInfTheory(target, asymmetry)

.DefaultNextBestInfTheory()

Arguments

Slots

target

(proportion)
target toxicity probability, except 0 or 1.

asymmetry

(number)
value of the asymmetry exponent in the divergence function that describes the rate of penalization for overly toxic does. It must be a value from (0, 2) interval.

Note

Typically, end users will not use the .DefaultNextBestInfTheory() function.

NextBestMTD

Description

NextBestMTD is the class for next best dose based on MTD estimate.

Usage

NextBestMTD(target, derive)

.DefaultNextBestMTD()

Arguments

Slots

target

(proportion)
target toxicity probability, except 0 or 1.

derive

(function)
a function which derives the final next best MTD estimate, based on vector of posterior MTD samples. It must therefore accept one and only one argument, which is a numeric vector, and return a number.

Note

Typically, end users will not use the .DefaultNextBestMTD() function.

Examples

# In the example below, the MTD is defined as the dose for which prob(DLE) = 0.33
# and we will use the 25th quantile of the posterior of MTD as our next best dose.
next_best_mtd <- NextBestMTD(
  target = 0.33,
  derive = function(mtd_samples) {
    quantile(mtd_samples, probs = 0.25)
  }
)

NextBestMaxGain

Description

NextBestMaxGain is the class to find a next best dose with maximum gain value based on a pseudo DLT and efficacy models without samples. It is based solely on the probabilities of the occurrence of a DLT and the values of the mean efficacy responses obtained by using the modal estimates of the DLT and efficacy model parameters. There are two target probabilities of the occurrence of a DLT that must be specified: target probability to be used during the trial and target probability to be used at the end of the trial. It is suitable to use it only with the ModelTox model and ModelEff classes (except EffFlexi).

Usage

NextBestMaxGain(prob_target_drt, prob_target_eot)

.DefaultNextBestMaxGain()

Arguments

Slots

prob_target_drt

(proportion)
the target probability of the occurrence of a DLT to be used during the trial.

prob_target_eot

(proportion)
the target probability of the occurrence of a DLT to be used at the end of the trial.

Note

Typically, end users will not use the .DefaultNextBestMaxGain() function.

Examples

my_next_best <- NextBestMaxGain(0.35, 0.3)

NextBestMaxGainSamples

Description

NextBestMaxGainSamples is the class to find a next best dose with maximum gain value based on a pseudo DLT and efficacy models and DLT and efficacy samples. There are two target probabilities of the occurrence of a DLT that must be specified: target probability to be used during the trial and target probability to be used at the end of the trial. It is suitable to use it only with the ModelTox model and ModelEff classes.

Usage

NextBestMaxGainSamples(prob_target_drt, prob_target_eot, derive, mg_derive)

.DefaultNextBestMaxGainSamples()

Arguments

Slots

derive

(function)
derives, based on a vector of posterior dose samples, the target dose that has the probability of the occurrence of DLT equals to either the prob_target_drt or prob_target_eot. It must therefore accept one and only one argument, which is a numeric vector, and return a number.

mg_derive

(function)
derives, based on a vector of posterior dose samples that give the maximum gain value, the final next best estimate of the dose that gives the maximum gain value. It must therefore accept one and only one argument, which is a numeric vector, and return a number.

Note

Typically, end users will not use the .DefaultNextBestMaxGainSamples() function.

Examples

# Target probability of the occurrence of a DLT during the trial is set to 0.35.
# Target probability of the occurrence of a DLT at the end of the trial is set to 0.3.
# We want the use the 30% posterior quantile (the 30th percentile) of the TD35
# (the dose level with probability of the DLT equals 0.35) and TD30 samples.
# For `mg_derive` function (which takes the sample of doses which give the maximum
# gain), we will use the 50% posterior quantile (the median or th 50th percentile)
# of the sample.
my_next_best <- NextBestMaxGainSamples(
  prob_target_drt = 0.35,
  prob_target_eot = 0.3,
  derive = function(samples) {
    as.numeric(quantile(samples, prob = 0.3))
  },
  mg_derive = function(mg_samples) {
    as.numeric(quantile(mg_samples, prob = 0.5))
  }
)

NextBestMinDist

Description

NextBestMinDist is the class for next best dose that is based on minimum distance to target probability.

Usage

NextBestMinDist(target)

.DefaultNextBestMinDist()

Arguments

Slots

target

(proportion)
single target toxicity probability, except 0 or 1.

Note

Typically, end users will not use the .DefaultNextBestMinDist() function.

Examples

# In the example below, the MTD is defined as the dose with the toxicity rate
# with minimal distance to the target of 30%.
next_best_min_dist <- NextBestMinDist(target = 0.3)

NextBestNCRM

Description

NextBestNCRM is the class for next best dose that finds the next dose with high posterior probability to be in the target toxicity interval.

Usage

NextBestNCRM(target, overdose, max_overdose_prob)

.DefaultNextBestNCRM()

Arguments

Details

To avoid numerical problems, the dose selection algorithm has been implemented as follows: First admissible doses are found, which are those with probability to fall in overdose category being below max_overdose_prob. Next, within the admissible doses, the maximum probability to fall in the target category is calculated. If that is above 5% (i.e. it is not just numerical error), then the corresponding dose is the next recommended dose. Otherwise, the highest admissible dose is the next recommended dose.

Slots

target

(numeric)
the target toxicity interval (limits included).

overdose

(numeric)
the overdose toxicity interval (lower limit excluded, upper limit included). It is used to filter probability samples.

max_overdose_prob

(proportion)
maximum overdose posterior probability that is allowed, except 0 or 1.

Note

Typically, end users will not use the .DefaultNextBestNCRM() function.

Examples

# In the example below, the target toxicity interval [0.2, 0.35] while the
# overdose interval is (0.35,1]. Finally we would like to constrain the
# probability of overdosing below 25%.
my_next_best <- NextBestNCRM(
  target = c(0.2, 0.35),
  overdose = c(0.35, 1),
  max_overdose_prob = 0.25
)

NextBestNCRMLoss

Description

NextBestNCRMLoss is the class based on NCRM rule and loss function. This class is similar to NextBestNCRM class, but differences are the addition of loss function and re-defined toxicity intervals, see each toxicity interval documentation and the note for details. As in NCRM rule, first admissible doses are found, which are those with probability to fall in overdose category being below max_overdose_prob. Next, within the admissible doses, the loss function is calculated, i.e. losses %*% target. Finally, the corresponding dose with lowest loss function (Bayes risk) is recommended for the next dose.

Usage

NextBestNCRMLoss(
  target,
  overdose,
  unacceptable = c(1, 1),
  max_overdose_prob,
  losses
)

.DefaultNextBestNCRMLoss()

Arguments

Slots

target

(numeric)
the target toxicity interval (limits included). It has to be a probability range excluding 0 and 1.

overdose

(numeric)
the overdose toxicity interval (lower limit excluded, upper limit included) or the excessive toxicity interval (lower limit excluded, upper limit included) if unacceptable is not provided. It has to be a probability range. It is used to filter probability samples.

unacceptable

(numeric)
an unacceptable toxicity interval (lower limit excluded, upper limit included). This must be specified if the overdose does not include 1. Otherwise, it is c(1, 1) (default), which is essentially a scalar equals 1. It has to be a probability range.

losses

(numeric)
a vector specifying the loss function. If the unacceptable is provided, the vector length must be 4, otherwise 3.

Note

The loss function should be a vector of either 3 or 4 values. This is because the loss function values must be specified for each interval, that is under-dosing, target toxicity, and overdosing toxicity or under-dosing, target toxicity, overdosing (excessive) toxicity, and unacceptable toxicity intervals.

Typically, end users will not use the .DefaultNextBestnCRMLoss() function.

Examples

# In the example below, the target toxicity interval [0.2, 0.35] while the
# overdose interval is (0.35, 1]. We would like to constrain the probability
# of overdosing below 25%. The loss function is c(1, 0, 1, 2).
my_next_best <- NextBestNCRMLoss(
  target = c(0.2, 0.35),
  overdose = c(0.35, 0.6),
  unacceptable = c(0.6, 1),
  max_overdose_prob = 0.25,
  losses = c(1, 0, 1, 2)
)

NextBestOrdinal

Description

NextBestOrdinal is the class for applying a standard NextBest rule to the results of an ordinal CRM trial.

Usage

NextBestOrdinal(grade, rule)

.DefaultNextBestOrdinal()

Arguments

Slots

grade

(integer)
the toxicity grade to which the rule should be applied.

rule

(NextBest)
the standard NextBest rule to be applied

Note

Typically, end users will not use the .DefaultNextBestOrdinal() function.

Examples

NextBestOrdinal(
  grade = 1L,
  rule = NextBestMTD(
    0.25,
    function(mtd_samples) {
      quantile(mtd_samples, probs = 0.25)
    }
  )
)

NextBestProbMTDLTE

Description

NextBestProbMTDLTE is the class of finding a next best dose that selects the dose with the highest probability of having a toxicity rate less or equal to the toxicity target. The dose is determined by calculating the posterior toxicity probability for each dose per iteration and select the maximum dose that has a toxicity probability below or equal to the target. The dose with the highest frequency of being selected as MTD across iterations is the next best dose. Placebo is not considered in the calculation and removed from the dose grid for any calculations.

Usage

NextBestProbMTDLTE(target)

.DefaultNextBestProbMTDLTE()

Arguments

Slots

target

(numeric)
the target toxicity probability.

Note

Typically, end users will not use the .DefaultNextBestProbMTDLTE() function.

Examples

# In the example below, the MTD is defined as the dose with the highest
# probability of having a toxicity rate below 30%.
next_best_prob_mtd_lte <- NextBestProbMTDLTE(target = 0.3)

NextBestProbMTDMinDist

Description

NextBestProbMTDMinDist is the class of finding a next best dose that selects the dose with the highest probability of having a toxicity rate with the smallest distance to the toxicity target. The dose is determined by calculating the posterior toxicity probability for each dose per iteration and select the dose that has the smallest toxicity probability distance to the target. The dose with the highest frequency of being selected as MTD across iterations is the next best dose. Placebo is not considered as the next dose and for that reason not used in calculations. I.e. for placebo the toxicity probability distance to target is not calculated and taken into account for determination of the next dose.

Usage

NextBestProbMTDMinDist(target)

.DefaultNextBestProbMTDMinDist()

Arguments

Slots

target

(numeric)
the target toxicity probability.

Note

Typically, end users will not use the .DefaultNextBestProbMTDMinDist() function.

Examples

# In the example below, the MTD is defined as the dose with the highest
# probability of having a toxicity rate with minimal distance
# to the target of 30%.
next_best_prob_mtd_min_dist <- NextBestProbMTDMinDist(target = 0.3)

NextBestTD

Description

NextBestTD is the class to find a next best dose based on pseudo DLT model without samples. Namely, it is to find two next best doses, one for allocation during the trial and the second for final recommendation at the end of a trial without involving any samples, i.e. only DLT responses will be incorporated for the dose-allocation. This is based solely on the probabilities of the occurrence of a DLT obtained by using the modal estimates of the model parameters. There are two target probabilities of the occurrence of a DLT that must be specified: target probability to be used during the trial and target probability to be used at the end of the trial. It is suitable to use it only with the ModelTox model class.

Usage

.DefaultNextBestTD()

NextBestTD(prob_target_drt, prob_target_eot)

Arguments

Slots

prob_target_drt

(proportion)
the target probability (except 0 or 1) of the occurrence of a DLT to be used during the trial.

prob_target_eot

(proportion)
the target probability (except 0 or 1) of the occurrence of a DLT to be used at the end of the trial.

Note

Typically, end users will not use the .DefaultNextBestTD() function.

Examples

my_next_best <- NextBestTD(0.35, 0.3)

NextBestTDsamples

Description

NextBestTDsamples is the class to find a next best dose based on Pseudo DLT model with samples. Namely, it is to find two next best doses, one for allocation during the trial and the second for final recommendation at the end of a trial. Hence, there are two target probabilities of the occurrence of a DLT that must be specified: target probability to be used during the trial and target probability to be used at the end of the trial.

Usage

NextBestTDsamples(prob_target_drt, prob_target_eot, derive)

.DefaultNextBestTDsamples()

Arguments

Slots

derive

(function)
derives, based on a vector of posterior dose samples, the target dose that has the probability of the occurrence of DLT equals to either the prob_target_drt or prob_target_eot. It must therefore accept one and only one argument, which is a numeric vector, and return a number.

Note

Typically, end users will not use the .DefaultNextBestTDsamples() function.

Examples

# Target probability of the occurrence of a DLT during the trial is set to 0.35.
# Target probability of the occurrence of a DLT at the end of the trial is set to 0.3.
# We want the use the 30% posterior quantile (the 30th percentile) of the TD35
# (the dose level with probability of the DLT equals 0.35) and TD30 samples.
my_next_best <- NextBestTDsamples(
  prob_target_drt = 0.35,
  prob_target_eot = 0.3,
  derive = function(samples) {
    as.numeric(quantile(samples, probs = 0.3))
  }
)

NextBestThreePlusThree

Description

NextBestThreePlusThree is the class for next best dose that implements the classical 3+3 dose recommendation. No input is required, hence this class has no slots.

Usage

NextBestThreePlusThree()

.DefaultNextBestThreePlusThree()

Note

Typically, end users will not use the .DefaultNextBestThreePlusThree() function.

Examples

# Next best dose class object using the classical 3+3 design.
my_next_best <- NextBestThreePlusThree()

OneParExpPrior

Description

OneParExpPrior is the class for a standard CRM with an exponential prior on the power parameter for the skeleton prior probabilities. It is an implementation of a version of the one-parameter CRM (O'Quigley et al. 1990).

Usage

OneParExpPrior(skel_probs, dose_grid, lambda)

.DefaultOneParExpPrior()

Arguments

Slots

skel_fun

(function)
function to calculate the prior DLT probabilities.

skel_fun_inv

(function)
inverse function of skel_fun.

skel_probs

(numeric)
skeleton prior probabilities. This is a vector of unique and sorted probability values between 0 and 1.

lambda

(number)
rate parameter of prior exponential distribution for theta.

Note

Typically, end users will not use the .DefaultOneparExpPrior() function.

Typically, end users will not use the .DefaultOneParLogNormalPrior() function.

References

O'Quigley J, Pepe M, Fisher L (1990). “Continual reassessment method: a practical design for phase 1 clinical trials in cancer.” Biometrics, 46(1). doi:10.2307/2531628.

Examples

my_model <- OneParExpPrior(
  skel_probs = c(0.1, 0.3, 0.5, 0.7, 0.9),
  dose_grid = 1:5,
  lambda = 2
)

OneParLogNormalPrior

Description

OneParLogNormalPrior is the class for a standard CRM with a normal prior on the log power parameter for the skeleton prior probabilities.

Usage

OneParLogNormalPrior(skel_probs, dose_grid, sigma2)

.DefaultOneParLogNormalPrior()

Arguments

Value

an instance of the OneParLogNormalPrior class

Slots

skel_fun

(function)
function to calculate the prior DLT probabilities.

skel_fun_inv

(function)
inverse function of skel_fun.

skel_probs

(numeric)
skeleton prior probabilities. This is a vector of unique and sorted probability values between 0 and 1.

sigma2

(number)
prior variance of log power parameter alpha.

See Also

ModelLogNormal.

Examples

my_model <- OneParLogNormalPrior(
  skel_probs = seq(from = 0.1, to = 0.9, length = 5),
  dose_grid = 1:5,
  sigma2 = 2
)

ProbitLogNormal

Description

ProbitLogNormal is the class for probit regression model with a bivariate normal prior on the intercept and log slope.

Usage

ProbitLogNormal(mean, cov, ref_dose = 1)

.DefaultProbitLogNormal()

Arguments

Details

The covariate is the natural logarithm of dose x divided by a reference dose x*, i.e.:

probit[p(x)] = alpha0 + alpha1 * log(x/x*),

where p(x) is the probability of observing a DLT for a given dose x. The prior

(alpha0, log(alpha1)) ~ Normal(mean, cov).

Note

The model used in the DualEndpoint classes is an extension of this model: DualEndpoint supports both ProbitNormal (which is not implemented yet) and ProbitLogNormal models through its use_log_dose slot. ProbitLogNormal has no such flag, so always uses ⁠log(x/x*)⁠as a covariate in its model. Therefore this class can be used to check the prior assumptions on the dose-toxicity model, even when sampling from the prior distribution of the dual endpoint model is not possible, when use_log_dose = TRUE is used.

Typically, end users will not use the .DefaultProbitLogNormal() function.

See Also

ModelLogNormal, LogisticNormal, LogisticLogNormal, LogisticLogNormalSub, ProbitLogNormalRel.

Examples

my_model <- ProbitLogNormal(
  mean = c(-0.85, 1),
  cov = matrix(c(1, -0.5, -0.5, 1), nrow = 2),
  ref_dose = 7.2
)

ProbitLogNormalRel

Description

ProbitLogNormalRel is the class for probit regression model with a bivariate normal prior on the intercept and log slope.

Usage

ProbitLogNormalRel(mean, cov, ref_dose = 1)

.DefaultProbitLogNormalRel()

Arguments

Details

The covariate is the dose x divided by a reference dose x*, i.e.:

probit[p(x)] = alpha0 + alpha1 * x/x*,

where p(x) is the probability of observing a DLT for a given dose x. The prior

(alpha0, log(alpha1)) ~ Normal(mean, cov).

Note

This model is also used in the DualEndpoint classes, so this class can be used to check the prior assumptions on the dose-toxicity model, even when sampling from the prior distribution of the dual endpoint model is not possible.

Typically, end users will not use the .DefaultProbitLogNormalRel() function.

See Also

ModelLogNormal, LogisticNormal, LogisticLogNormal, LogisticLogNormalSub, ProbitLogNormal.

Examples

my_model <- ProbitLogNormalRel(
  mean = c(-0.85, 1),
  cov = matrix(c(1, -0.5, -0.5, 1), nrow = 2)
)

PseudoDualFlexiSimulations

Description

This class captures the trial simulations design using both the DLE and efficacy responses using EffFlexi efficacy model. It extends PseudoDualSimulations by adding the capability to capture the sigma2betaW estimates.

Usage

PseudoDualFlexiSimulations(sigma2_beta_w_est, ...)

.DefaultPseudoDualFlexiSimulations()

Arguments

Slots

sigma2_beta_w_est

(numeric)
the vector of the final posterior mean sigma2betaW estimates

Note

Typically, end users will not use the .DefaultPseudoFlexiSimulations() function.

PseudoDualSimulations

Description

This class conducts trial simulations for designs using both the DLE and efficacy responses. It defines final values for efficacy fit and DLE, estimates of Gstar, optimal dose and sigma2.

Usage

PseudoDualSimulations(
  fit_eff,
  final_gstar_estimates,
  final_gstar_at_dose_grid,
  final_gstar_cis,
  final_gstar_ratios,
  final_optimal_dose,
  final_optimal_dose_at_dose_grid,
  sigma2_est,
  ...
)

.DefaultPseudoDualSimulations()

Arguments

Slots

fit_eff

(list)
final values of efficacy fit.

final_gstar_estimates

(numeric)
final Gstar estimates.

final_gstar_at_dose_grid

(numeric)
final Gstar estimates at dose grid.

final_gstar_cis

(list)
list of 95% confidence interval for Gstar estimates.

final_gstar_ratios

(numeric)
ratios of confidence intervals for Gstar estimates.

final_optimal_dose

(numeric)
final optimal dose.

final_optimal_dose_at_dose_grid

(numeric)
final optimal dose at dose grid.

sigma2_est

(numeric)
final sigma2 estimates.

Note

Do not use the .DefaultPseudoDualSimulations() function.

PseudoDualSimulationsSummary

Description

This class captures the summary of the dual responses simulations using pseudo models. It contains all slots from PseudoSimulationsSummary object. In addition to the slots in the parent class PseudoSimulationsSummary, it contains additional slots for the efficacy model fit information.

Note that objects should not be created by users, therefore no initialization function is provided for this class.

Usage

.DefaultPseudoDualSimulationsSummary()

Slots

target_gstar

(numeric)
the target dose level such that its gain value is at maximum

target_gstar_at_dose_grid

(numeric)
the dose level at dose Grid closest and below Gstar

gstar_summary

(table)
the six-number table summary (lowest, 25th, 50th (median), 75th percentile, mean and highest value) of the final Gstar values obtained across all simulations

ratio_gstar_summary

(table)
the six-number summary table of the ratios of the upper to the lower 95% credibility intervals of the final Gstar across all simulations

eff_fit_at_dose_most_selected

(numeric)
fitted expected mean efficacy value at dose most often selected

mean_eff_fit

(list)
list with mean, lower (2.5%) and upper (97.5%) quantiles of the fitted expected efficacy value at each dose level.

Note

Typically, end users will not use the .DefaultPseudoDualSimulationsSummary() function.

PseudoSimulations

Description

This class captures trial simulations from designs using pseudo model. It has additional slots fit and stop_reasons compared to the general class GeneralSimulations.

Usage

PseudoSimulations(
  fit,
  final_td_target_during_trial_estimates,
  final_td_target_end_of_trial_estimates,
  final_td_target_during_trial_at_dose_grid,
  final_td_target_end_of_trial_at_dose_grid,
  final_tdeot_cis,
  final_tdeot_ratios,
  final_cis,
  final_ratios,
  stop_report,
  stop_reasons,
  ...
)

.DefaultPseudoSimulations()

Arguments

Slots

fit

(list)
final fit values.

final_td_target_during_trial_estimates

(numeric)
final estimates of the td_target_during_trial.

final_td_target_end_of_trial_estimates

(numeric)
final estimates of the td_target_end_of_trial.

final_td_target_during_trial_at_dose_grid

(numeric)
dose levels at dose grid closest below the final td_target_during_trial estimates.

final_td_target_end_of_trial_at_dose_grid

(numeric)
dose levels at dose grid closest below the final td_target_end_of_trial estimates.

final_tdeot_cis

(list)
95% credibility intervals of the final estimates for td_target_end_of_trial.

final_tdeot_ratios

(numeric)
ratio of the upper to the lower 95% credibility intervals for td_target_end_of_trial.

final_cis

(list)
final 95% credibility intervals for td_target_end_of_trial estimates.

final_ratios

(numeric)
final ratios of the upper to the lower 95% credibility interval for td_target_end_of_trial.

stop_report

(matrix)
outcomes of stopping rules.

stop_reasons

(list)
reasons for stopping each simulation run.

Note

Typically, end users will not use the .DefaultPseudoSimulations() function.

PseudoSimulationsSummary

Description

This class captures the summary of pseudo-models simulations output. Note that objects should not be created by users, therefore no initialization function is provided for this class.

Usage

.DefaultPseudoSimulationsSummary()

Slots

target_end_of_trial

(numeric)
the target probability of DLE wanted at the end of a trial

target_dose_end_of_trial

(numeric)
the dose level corresponds to the target probability of DLE wanted at the end of a trial, TDEOT

target_dose_end_of_trial_at_dose_grid

(numeric)
the dose level at dose grid corresponds to the target probability of DLE wanted at the end of a trial

target_during_trial

(numeric)
the target probability of DLE wanted during a trial

target_dose_during_trial

(numeric)
the dose level corresponds to the target probability of DLE wanted during the trial. TDDT

target_dose_during_trial_at_dose_grid

(numeric)
the dose level at dose grid corresponds to the target probability of DLE wanted during a trial

tdeot_summary

(table)
the six-number table summary, include the lowest, the 25th percentile (lower quartile), the 50th percentile (median), the mean, the 75th percentile and the highest values of the final dose levels obtained corresponds to the target probability of DLE want at the end of a trial across all simulations

tddt_summary

(table)
the six-number table summary, include the lowest, the 25th percentile (lower quartile), the 50th percentile (median), the mean, the 75th percentile and the highest values of the final dose levels obtained corresponds to the target probability of DLE want during a trial across all simulations

final_dose_rec_summary

(table)
the six-number table summary, include the lowest, the 25th percentile (lower quartile), the 50th percentile (median), the mean, the 75th percentile and the highest values of the final optimal doses, which is either the TDEOT when only DLE response are incorporated into the escalation procedure or the minimum of the TDEOT and Gstar when DLE and efficacy responses are incorporated, across all simulations

ratio_tdeot_summary

(table)
the six-number summary table of the final ratios of the upper to the lower 95% credibility intervals of the final TDEOTs across all simulations

final_ratio_summary

(table)
the six-number summary table of the final ratios of the upper to the lower 95% credibility intervals of the final optimal doses across all simulations

nsim

(integer)
number of simulations

prop_dle

(numeric)
proportions of DLE in the trials

mean_tox_risk

(numeric)
mean toxicity risks for the patients

dose_selected

(numeric)
doses selected as MTD (target_dose_end_of_trial)

tox_at_doses_selected

(numeric)
true toxicity at doses selected

prop_at_target_end_of_trial

(numeric)
Proportion of trials selecting at the dose_grid closest below the MTD, the target_dose_end_of_trial

prop_at_target_during_trial

(numeric)
Proportion of trials selecting at the dose_grid closest below the target_dose_during_trial

dose_most_selected

(numeric)
dose most often selected as MTD

obs_tox_rate_at_dose_most_selected

(numeric)
observed toxicity rate at dose most often selected

n_obs

(integer)
number of patients overall

n_above_target_end_of_trial

(integer)
number of patients treated above target_dose_end_of_trial

n_above_target_during_trial

(integer)
number of patients treated above target_dose_during_trial

dose_grid

(numeric)
the dose grid that has been used

fit_at_dose_most_selected

(numeric)
fitted toxicity rate at dose most often selected

mean_fit

(list)
list with the average, lower (2.5%) and upper (97.5%) quantiles of the mean fitted toxicity at each dose level

stop_report

(matrix)
matrix of stopping rule outcomes

Note

Typically, end users will not use the .DefaultPseudoSimulationsSummary() function.

Convert Prior Quantiles to Logistic (Log) Normal Model

Description

This function uses generalized simulated annealing to optimize a LogisticNormal model to be as close as possible to the given prior quantiles.

Usage

Quantiles2LogisticNormal(
  dosegrid,
  refDose,
  lower,
  median,
  upper,
  level = 0.95,
  logNormal = FALSE,
  parstart = NULL,
  parlower = c(-10, -10, 0, 0, -0.95),
  parupper = c(10, 10, 10, 10, 0.95),
  seed = 12345,
  verbose = TRUE,
  control = list(threshold.stop = 0.01, maxit = 50000, temperature = 50000, max.time =
    600)
)

Arguments

Value

A list with the best approximating model (LogisticNormal or LogisticLogNormal), the resulting quantiles, the required quantiles and the distance to the required quantiles, as well as the final parameters (which could be used for running the algorithm a second time).

RuleDesign

Description

RuleDesign is the class for rule-based designs. The difference between this class and the Design class is that RuleDesign does not contain model, stopping and increments slots.

Usage

RuleDesign(nextBest, cohort_size, data, startingDose)

.DefaultRuleDesign()

ThreePlusThreeDesign(doseGrid)

Arguments

Functions

• ThreePlusThreeDesign(): creates a new 3+3 design object from a dose grid.

Slots

nextBest

(NextBest)
how to find the next best dose.

cohort_size

(CohortSize)
rules for the cohort sizes.

data

(Data)
specifies dose grid, any previous data, etc.

startingDose

(number)
the starting dose, it must lie on the dose grid in data.

Note

Typically, end users will not use the .DefaultRuleDesign() function.

Examples

# Specify the design to run simulations. The design comprises a model,
# the escalation rule, starting data, a cohort size and a starting dose.

# Initialing a 3+3 design with constant cohort size of 3 and starting dose equal 5.
my_design <- RuleDesign(
  nextBest = NextBestThreePlusThree(),
  cohort_size = CohortSizeConst(size = 3L),
  data = Data(doseGrid = c(5, 10, 15, 25, 35, 50, 80)),
  startingDose = 5
)
# Initialing a 3+3 design with constant cohort size of 3 and starting dose equal 8.
my_design <- ThreePlusThreeDesign(doseGrid = c(8, 10, 15, 25, 35, 50, 80))

RuleDesignOrdinal

Description

RuleDesignOrdinal is the class for rule-based designs. The difference between this class and the DesignOrdinal class is that RuleDesignOrdinal does not contain model, stopping and increments slots.

Usage

RuleDesignOrdinal(next_best, cohort_size, data, starting_dose)

.DefaultRuleDesignOrdinal()

Arguments

Details

Please note that the cohort size rules need to be wrapped into the corresponding CohortSizeOrdinal class, before a successful evaluation of the corresponding methods can take place. Note also that these wrappers cannot be nested, i.e., you cannot have a CohortSizeOrdinal inside another CohortSizeOrdinal (which also would not make sense) because it would not be clear which event grade to use for the methods calculation. However, multiple rules can be combined using the operators defined, e.g., CohortSizeMin(list(CohortSizeOrdinal(1L, rule1), CohortSizeOrdinal(2L, rule2))).

Slots

next_best

(NextBestOrdinal)
how to find the next best dose.

cohort_size

(CohortSize)
rules for the cohort sizes.

data

(DataOrdinal)
specifies dose grid, any previous data, etc.

starting_dose

(number)
the starting dose, it must lie on the dose grid in data.

Note