14 oc post prob

NAMESPACE

@@ -7,10 +7,6 @@ export(dbetabinom)
 export(dbetabinomMix)
 export(dbetadiff)
 export(getBetamixPost)
-export(get_decision)
-export(get_distance)
-export(get_looks)
-export(get_oc)
 export(logit)
 export(myPlot)
 export(myPlotDiff)

R/ocPostprob.R

@@ -1,22 +1,19 @@
 #' @include postprob.R
 NULL
 
-#' Generating random distance in given looks for sample sizes for efficacy and futility.
-#'
-#' @description `r lifecycle::badge("experimental")`
+#' Generating random distance in given looks for sample sizes for Efficacy and Futility.
 #'
 #' A helper function for `ocPostprob` to generate random distance's wiggle room around looks `nn`.
 #' Numeric looks `nn` must be of minimum two elements and will generate `length(nn)-1` distances.
 #'
-#' @param nn : number or numeric
-#' the union of `nnE` and `nnF` (if futility analysis or looks exists) supplied
+#' @typed nn : number or numeric
+#'  the union of `nnE` and `nnF` (if futility analysis or looks exists) supplied.
 #'
 #' @return A numeric with `length(nn)-1` elements.
 #'
-#' @export
+#' @keywords internal
 #'
-#' @examples examples / ocPostprob.R
-get_distance <- function(nn) {
+h_get_distance <- function(nn) {
   assert_numeric(nn, unique = TRUE, sorted = TRUE, min.len = 1)
   dist0 <- floor(min(nn - c(0, nn[-length(nn)])) / 2)
   assert_numeric(dist0, sorted = TRUE)
@@ -27,31 +24,27 @@ get_distance <- function(nn) {
   )
 }
 
-
-#' Generating looks
-#'
-#' @description `r lifecycle::badge("experimental")`
+#' Generating looks from random distance
 #'
 #' A helper function for `ocPostprob` that applies the numeric element of `dist` to looks `nn`.
 #'
 #' @typed dist : numeric or logical
-#' Distance for random looks around the look locations in `nn`,
-#' where `dist`is generated from `get_distance` in a numeric of at least one element.
-#' If `NULL`, only one location look will be set at `nnE` or `nnF`.
+#'  distance for random looks around the look locations in `nn`,
+#'  where `dist`is generated from `h_get_distance` in a numeric of at least one element.
+#'  If `NULL`, only one location look will be set at `nnE` or `nnF`.
 #' @typed nnE : numeric
-#' Sample size or sizes where study can be stopped for efficacy decision. If different for futility decision,
-#' specify in `nnF`.
+#'  sample size or sizes where study can be stopped for Efficacy decision. If different for Futility decision,
+#'  specify in `nnF`.
 #' @typed nnF : numeric
-#' Sample size or sizes where study can be stopped for futility decision if different from efficacy decision.
+#'  sample size or sizes where study can be stopped for Futility decision if different from Efficacy decision.
 #'
-#' @return Uses distance from `get_distance` to add to looks, creating wiggled looks:
-#' `nnrE`is the result for efficacy looks with random distance added.
-#' `nnrF`is the result for futility looks with random distance added.
+#' @return Uses distance from `h_get_distance` to add to looks, creating wiggled looks:
+#'  `nnrE`is the result for Efficacy looks with random distance added.
+#'  `nnrF`is the result for Futility looks with random distance added.
 #'
-#' @export
+#' @keywords internal
 #'
-#' @examples examples / ocPostProb.R
-get_looks <- function(dist, nnE, nnF) {
+h_get_looks <- function(dist, nnE, nnF) {
   assert_numeric(nnE)
   assert_numeric(nnF)
   nn <- unique(c(nnE, nnF))
@@ -66,38 +59,35 @@ get_looks <- function(dist, nnE, nnF) {
 
 #' Generating random decision and sample size looks.
 #'
-#' @description `r lifecycle::badge("experimental")`
-#'
 #' A helper function for `ocPostprob` to generate numeric of decisions `decisions` and random looks `all_sizes`.
 #'
-#' @inheritParams get_looks
+#' @inheritParams h_get_looks
 #' @typed nnr : numeric
 #' union of `nnE`and `nnF`.
 #' @typed response : numeric
-#' A numeric of Bernoulli successes based on `size_look`
+#' A numeric of Bernoulli successes based on `size_look`.
 #' @typed truep : number
 #'  assumed true response rate or true rate (scenario).
 #' @typed p0 : number
-#'  lower efficacy threshold of response rate.
+#'  lower Futility threshold of response rate.
 #' @typed p1 : number
-#'  upper efficacy threshold of response rate.
+#'  upper Efficacy threshold of response rate.
 #' @typed tL : number
-#'  posterior probability threshold for being below `p0`.
+#'  posterior probability threshold for being below `p0`..
 #' @typed tU : number
 #'  posterior probability threshold for being above `p1`.
 #' @typed parE : numeric
-#'  Alpha and beta parameters for the prior on the treatment proportion.
+#'  alpha and beta parameters for the prior on the treatment proportion.
 #'  Default set at alpha = 1, beta = 1, or uniform prior.
 #'
 #' @return A list of the following objects :
-#'  - `decision` : resulting numeric of decision, one of `TRUE` for GO, `FALSE`for STOP, `NA` for Gray zone
+#'  - `decision` : resulting numeric of decision, one of `TRUE` for Go, `FALSE`for Stop, `NA` for Gray zone.
 #'  - `all_sizes` : resulting numeric of look size, anything below maximum
-#'                  look size is an indicated interim, futility or efficacy or both
+#'                  look size is an indicated interim, Futility or Efficacy or both.
 #'
-#' @export
+#' @keywords internal
 #'
-#' @examples
-get_decision <- function(nnr, response, truep, p0, p1, parE = c(1, 1), nnE, nnF, tL, tU) {
+h_get_decision <- function(nnr, response, truep, p0, p1, parE = c(1, 1), nnE, nnF, tL, tU) {
   index_look <- 1
   assert_numeric(nnr)
   size_look <- nnr[index_look]
@@ -127,35 +117,33 @@ get_decision <- function(nnr, response, truep, p0, p1, parE = c(1, 1), nnE, nnF,
 
 #' Creating list for operating characteristics.
 #'
-#' @description `r lifecycle::badge("experimental")`
-#'
 #' Generates operating characteristics.
 #'
-#' @inheritParams get_looks
-#' @inheritParams get_decision
+#' @inheritParams h_get_looks
+#' @inheritParams h_get_decision
 #' @typed nnrE : numeric
-#' Looks with random distance, if applied on `nnE`.
+#'  looks with random distance, if applied on `nnE`.
 #' @typed nnrF : numeric
-#' Looks with random distance, if applied on `nnF`.
+#'  looks with random distance, if applied on `nnF`.
 #' @typed all_sizes : numeric
-#' Sample sizes of all looks simulated `length(sim)` times if `dist` applied.
+#'  sample sizes of all looks simulated `length(sim)` times if `dist` applied.
 #' @typed decision : numeric
-#' Go, Stop or Gray Zone decisions of all looks simulated `length(sim)` times.
+#'  Go, Stop or Gray Zone decisions of all looks simulated `length(sim)` times.
 #'
 #' @return A list of results containing :
 #'
 #' - `ExpectedN`: expected number of patients in the trials
 #' - `PrStopEarly`: probability to stop the trial early (before reaching the
 #' maximum sample size)
 #' - `PrEarlyEff`: probability of Early Go decision
-#' - `PrEarlyFut`: probability to decide for Futility early
+#' - `PrEarlyFut`: probability of for Early Stop decision
 #' - `PrEfficacy`: probability of Go decision
-#' - `PrFutility`: Probability of Stop decision
+#' - `PrFutility`: probability of Stop decision
 #' - `PrGrayZone`: probability between Go and Stop ,"Evaluate" or Gray decision zone
-#' @export
 #'
-#' @examples examples / ocPostprob.R
-get_oc <- function(all_sizes, nnr, decision, nnrE, nnrF) {
+#' @keywords internal
+#'
+h_get_oc <- function(all_sizes, nnr, decision, nnrE, nnrF) {
   sim <- length(all_sizes)
   assert_logical(decision, len = sim)
   assert_numeric(all_sizes)
@@ -179,8 +167,8 @@ get_oc <- function(all_sizes, nnr, decision, nnrE, nnrF) {
 #' Calculate operating characteristics for posterior probability method.
 #'
 #' It is assumed that the true response rate is `truep`.
-#' The trial is stopped for efficacy if the posterior probability to be
-#' above `p1` is larger than `tU`, and stopped for futility if the posterior
+#' The trial is stopped for Efficacy if the posterior probability to be
+#' above `p1` is larger than `tU`, and stopped for Futility if the posterior
 #' probability to be below `p0` is larger than `tL`:
 #'
 #' Stop criteria for Efficacy :
@@ -197,18 +185,18 @@ get_oc <- function(all_sizes, nnr, decision, nnrE, nnrF) {
 #' - `PrStopEarly`: probability to stop the trial early (before reaching the
 #' maximum sample size)
 #' - `PrEarlyEff`: probability of Early Go decision
-#' - `PrEarlyFut`: probability of for Early Futility decision
+#' - `PrEarlyFut`: probability of for Early Stop decision
 #' - `PrEfficacy`: probability of Go decision
-#' - `PrFutility`: Probability of Stop decision
+#' - `PrFutility`: probability of Stop decision
 #' - `PrGrayZone`: probability between Go and Stop ,"Evaluate" or Gray decision zone
 #'
-#' @inheritParams get_looks
-#' @inheritParams get_decision
+#' @inheritParams h_get_looks
+#' @inheritParams h_get_decision
 #' @typed sim : number
-#'  number of simulations
+#'  number of simulations.
 #' @typed wiggle : logical
-#'  generate random look locations (not default)
-#'  if `TRUE`, optional to specify `dist` (see @details)
+#'  generate random look locations (not default).
+#'  if `TRUE`, optional to specify `dist` (see @details).
 #' @typed randomdist : logical
 #'  Random distance added to looks. if `NULL`, and `wiggle = TRUE`, function will
 #'  generate and add a random distance within range of the closest looks.
@@ -217,9 +205,9 @@ get_oc <- function(all_sizes, nnr, decision, nnrE, nnrF) {
 #'
 #' - `oc`: matrix with operating characteristics (see @details section)
 #' - `nn`: vector of look locations that was supplied
-#' - `nnE`: vector of efficacy look locations
-#' - `nnF`: vector of futility look locations # TODO
-#' - `params`: multiple parameters# TODOs
+#' - `nnE`: vector of Efficacy look locations
+#' - `nnF`: vector of Futility look locations
+#' - `params`: multiple parameters
 #'
 #' @details
 #' `ExpectedN` is an average of the simulated sample sizes.
@@ -233,22 +221,24 @@ get_oc <- function(all_sizes, nnr, decision, nnrE, nnrF) {
 ocPostprob <- function(nnE, truep, p0, p1, tL, tU, parE = c(1, 1),
                        sim = 50000, wiggle = FALSE, randomdist = NULL, nnF = nnE) {
   nn <- sort(unique(c(nnF, nnE)))
+  assert_number(sim, lower = 1, finite = TRUE)
+  if (sim < 50000) {
+    warning("Advise to use sim >= 50000 to achieve convergence")
+  }
   decision <- vector(length = sim)
   all_sizes <- vector(length = sim)
-  assert_logical(decision)
-  assert_logical(all_sizes)
   for (k in seq_len(sim)) {
     if (length(nn) != 1 && wiggle && is.null(randomdist)) {
-      dist <- get_distance(nn = nn)
-      nnr <- get_looks(dist = dist, nnE = nnE, nnF = nnF)
+      dist <- h_get_distance(nn = nn)
+      nnr <- h_get_looks(dist = dist, nnE = nnE, nnF = nnF)
       nnrE <- nnr$nnrE
       nnrF <- nnr$nnrF
     } else {
       nnrE <- nnE
       nnrF <- nnF
     }
     nnr <- unique(c(nnrE, nnrF))
-    tmp <- get_decision(
+    tmp <- h_get_decision(
       nnr = nnr, response = response,
       truep = truep, p0 = p0, p1 = p1,
       parE = c(1, 1), nnE = nnrE,
@@ -257,7 +247,7 @@ ocPostprob <- function(nnE, truep, p0, p1, tL, tU, parE = c(1, 1),
     decision[k] <- tmp$decision
     all_sizes[k] <- tmp$all_sizes
   }
-  oc <- get_oc(all_sizes = all_sizes, nnr = nnr, decision = decision, nnrE = nnrE, nnrF = nnrF)
+  oc <- h_get_oc(all_sizes = all_sizes, nnr = nnr, decision = decision, nnrE = nnrE, nnrF = nnrF)
   list(
     oc = oc,
     Decision = decision,

R/postprob.R

@@ -27,7 +27,6 @@ postprobOld <- function(x, n, p, a = 1, b = 1) {
   stats::pbeta(p, a + x, b + n - x, lower.tail = FALSE)
 }
 
-
 #' Compute the posterior probability to be above threshold,
 #' with a beta mixture prior on the response rate.
 #'
@@ -63,20 +62,19 @@ postprobOld <- function(x, n, p, a = 1, b = 1) {
 #' @export
 postprob <- function(x, n, p, parE = c(1, 1), weights, betamixPost, log.p = FALSE) {
   if (missing(betamixPost)) {
-    ## if parE is a vector => situation where there is only one component
+    # If betamixPost is missing, then we would use the default parE
     if (is.vector(parE)) {
-      # Here there is only one component.
+      # Here there is only one component in the parE vector.
       assert_true(identical(length(parE), 2L))
-      # To get matrix with one row.
+      # To get matrix with one row, we transpose parE.
       parE <- t(parE)
     }
 
-    ## if prior weights of the beta mixture are not supplied
+    # If prior weights of the beta mixture are not supplied, weights are given
     if (missing(weights)) {
       weights <- rep(1, nrow(parE))
     }
 
-    ## now compute updated parameters
     betamixPost <- getBetamixPost(
       x = x,
       n = n,
@@ -85,7 +83,7 @@ postprob <- function(x, n, p, parE = c(1, 1), weights, betamixPost, log.p = FALS
     )
   }
 
-  ## now compute the survival function at p, i.e. 1 - cdf at p:
+  # Here, we compute the survival function at p, i.e. 1 - cdf at p as lower.tail = FALSE:
   ret <- with(
     betamixPost,
     pbetaMix(q = p, par = par, weights = weights, lower.tail = FALSE)