Implement IncrementsMaxToxProb

NAMESPACE

@@ -141,6 +141,7 @@ export(.DefaultGeneralSimulationsSummary)
 export(.DefaultIncrements)
 export(.DefaultIncrementsDoseLevels)
 export(.DefaultIncrementsHSRBeta)
+export(.DefaultIncrementsMaxToxProb)
 export(.DefaultIncrementsMin)
 export(.DefaultIncrementsOrdinal)
 export(.DefaultIncrementsRelative)
@@ -239,6 +240,7 @@ export(.GeneralSimulations)
 export(.GeneralSimulationsSummary)
 export(.IncrementsDoseLevels)
 export(.IncrementsHSRBeta)
+export(.IncrementsMaxToxProb)
 export(.IncrementsMin)
 export(.IncrementsOrdinal)
 export(.IncrementsRelative)
@@ -348,6 +350,7 @@ export(FractionalCRM)
 export(GeneralSimulations)
 export(IncrementsDoseLevels)
 export(IncrementsHSRBeta)
+export(IncrementsMaxToxProb)
 export(IncrementsMin)
 export(IncrementsOrdinal)
 export(IncrementsRelative)
@@ -558,6 +561,7 @@ exportClasses(GeneralSimulationsSummary)
 exportClasses(Increments)
 exportClasses(IncrementsDoseLevels)
 exportClasses(IncrementsHSRBeta)
+exportClasses(IncrementsMaxToxProb)
 exportClasses(IncrementsMin)
 exportClasses(IncrementsOrdinal)
 exportClasses(IncrementsRelative)

NEWS.md

@@ -1,5 +1,6 @@
 # Version 2.0.0.9158
 * **Note: This release (1.0 -> 2.0) signifies a major breaking revamp of the package.** Users are advised to carefully review the release notes and documentation for detailed information on the changes and any necessary updates to their existing code.
+* Implemented the `IncrementsMaxToxProb` class
 * Implemented `knit_print` methods for almost all `crmPack` classes to improve rendering in Markdown and Quarto documents.  See the vignette for more details.
 * Provided basic support for ordinal CRM models.  See the vignette for more details.
 * Implemented `broom`-like `tidy` methods for all concrete `crmPack` classes.  See the vignette for more details.

R/Rules-class.R

@@ -1539,6 +1539,65 @@ IncrementsOrdinal <- function(grade, rule) {
   )
 }
 
+# IncrementsMaxToxProb ----
+
+## class ----
+
+#' `IncrementsMaxToxProb`
+#'
+#' @description `r lifecycle::badge("experimental")`
+#'
+#' [`IncrementsMaxToxProb`] is the class for increments control based on
+#' probability of toxicity
+#'
+#' @slot prob (`numeric`)\cr See Usage Notes below.
+#'
+#' @section 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.
+#'
+#' @aliases IncrementsMaxToxProb
+#' @export
+#'
+.IncrementsMaxToxProb <- setClass(
+  Class = "IncrementsMaxToxProb",
+  slots = c(
+    prob = "numeric"
+  ),
+  prototype = prototype(
+    prob = c("DLAE" = 0.2, "DLT" = 0.05)
+  ),
+  contains = "Increments",
+  validity = v_increments_maxtoxprob
+)
+
+## constructor ----
+
+#' @rdname IncrementsMaxToxProb-class
+#'
+#' @param prob (`numeric`)\cr see slot definition.
+#'
+#' @export
+#' @example examples/Rules-class-IncrementsMaxToxProb.R
+#'
+IncrementsMaxToxProb <- function(prob) {
+  .IncrementsMaxToxProb(
+    prob = prob
+  )
+}
+
+## default constructor ----
+
+#' @rdname IncrementsMaxToxProb-class
+#' @note Typically, end users will not use the `.DefaultIncrementsMaxToxProb()` function.
+#' @export
+.DefaultIncrementsMaxToxProb <- function() {
+  IncrementsMaxToxProb(prob = c("DLAE" = 0.2, "DLT" = 0.05))
+}
+
 # Stopping ----
 
 ## class ----

R/Rules-methods.R

@@ -1725,6 +1725,92 @@ setMethod(
   }
 )
 
+## IncrementsMaxToxProb ----
+
+#' @describeIn maxDose determine the maximum possible next dose based on the
+#' probability of toxicity
+#' @param model (`GeneralModel`)\cr The model on which probabilities will be based
+#' @param `samples` (`Samples`)\cr The MCMC samples to which `model` will be applied
+#'
+#' @aliases maxDose-IncrementsMaxToxProb
+#'
+#' @export
+#' @example examples/Rules-method-maxDose-IncrementsMaxToxProb.R
+#'
+setMethod(
+  f = "maxDose",
+  signature = signature(
+    increments = "IncrementsMaxToxProb",
+    data = "DataOrdinal"
+  ),
+  definition = function(increments, data, model, samples, ...) {
+    assert_class(samples, "Samples")
+    assert_true(length(increments@prob) == length(data@yCategories) - 1)
+    nm <- names(data@yCategories)[2:length(data@yCategories)]
+    assert_set_equal(names(increments@prob), nm)
+
+    probs <- lapply(
+      seq_along(increments@prob),
+      function(g) {
+        fit(samples, model, data, grade = g, ...) %>%
+          dplyr::filter(middle < increments@prob[nm[g]]) %>%
+          utils::tail(1)
+      }
+    ) %>%
+      dplyr::bind_rows()
+    return(min(probs$dose))
+  }
+)
+#' @describeIn maxDose determine the maximum possible next dose based on the
+#' probability of toxicity
+#' @param model (`GeneralModel`)\cr The model on which probabilities will be based
+#' @param samples (`Samples`)\cr The MCMC samples to which `model` will be applied
+#'
+#' @aliases maxDose-IncrementsMaxToxProb
+#'
+#' @export
+#' @example examples/Rules-method-maxDose-IncrementsMaxToxProb.R
+#'
+setMethod(
+  f = "maxDose",
+  signature = signature(
+    increments = "IncrementsMaxToxProb",
+    data = "Data"
+  ),
+  definition = function(increments, data, model, samples, ...) {
+    assert_class(samples, "Samples")
+    assert_true(length(increments@prob) == 1)
+
+    prob <- fit(samples, model, data, ...) %>%
+      dplyr::filter(middle < increments@prob) %>%
+      utils::tail(1) %>%
+      dplyr::pull(dose)
+    return(prob)
+  }
+)
+
+## tidy-IncrementsMaxToxProb ----
+
+#' @rdname tidy
+#' @aliases tidy-IncrementsMaxToxProb
+#' @example examples/Rules-method-tidyIncrementsMaxToxProb.R
+#' @export
+setMethod(
+  f = "tidy",
+  signature = signature(x = "IncrementsMaxToxProb"),
+  definition = function(x, ...) {
+    grades <- names(x@prob)
+    if (is.null(grades)) {
+      grades <- "1"
+    }
+    tibble(
+      Grade = grades,
+      Prob = x@prob
+    ) %>%
+      crmPack:::h_tidy_class(x)
+  }
+)
+
 # nolint start
 
 ## ============================================================

R/Rules-validity.R

@@ -330,6 +330,20 @@ v_increments_min <- function(object) {
   v$result()
 }
 
+#' @describeIn v_increments validates the [`IncrementsMaxToxProb`]
+v_increments_maxtoxprob <- function(object) {
+  v <- crmPack:::Validate()
+  v$check(
+    test_probabilities(object@prob),
+    "prob must be a vector of probabilities with minimum length 1 and no missing values"
+  )
+  v$check(
+    test_numeric(object@prob, any.missing = FALSE, min.len = 1),
+    "prob must be a vector of probabilities with minimum length 1 and no missing values"
+  )
+  v$result()
+}
+
 # Stopping ----
 
 #' Internal Helper Functions for Validation of [`Stopping`] Objects

examples/Rules-class-IncrementsMaxToxProb.R

@@ -0,0 +1,5 @@
+# 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))

examples/Rules-method-maxDose-IncrementsMaxToxProb.R

@@ -0,0 +1,17 @@
+model <- LogisticLogNormalOrdinal(
+  mean = c(0.25, 0.15, 0.5),
+  cov = matrix(c(1.5, 0, 0, 0, 2, 0, 0, 0, 1), nrow = 3),
+  ref_dose = 30
+)
+
+emptyData <- DataOrdinal(
+  doseGrid = c(1, 3, 9, 25, 50, 75, 100),
+  yCategories = c("No tox" = 0L, "DLAE" = 1L, "CRS" = 2L)
+)
+
+# For warning regarding tox, see issue #748 https://github.com/openpharma/crmPack/issues/748
+suppressWarnings({
+  samples <- mcmc(emptyData, model, .DefaultMcmcOptions())
+})
+toxIncrements <- IncrementsMaxToxProb(probs = c("DLAE" = 0.2, "CRS" = 0.05))
+maxDose(toxIncrements, emptyData, model, samples)

examples/Rules-method-tidyIncrementsMaxToxProb.R

@@ -0,0 +1 @@
+IncrementsMaxToxProb(prob = c("DLAE" = 0.2, "CRS" = 0.05)) %>% tidy()