11_postprob

NAMESPACE

@@ -24,8 +24,8 @@ export(plotBounds)
 export(plotDecision)
 export(plotOc)
 export(postprob)
+export(postprobBeta)
 export(postprobDist)
-export(postprobOld)
 export(predprob)
 export(predprobDist)
 export(qbetaMix)
@@ -53,7 +53,6 @@ importFrom(stats,dbeta)
 importFrom(stats,dbinom)
 importFrom(stats,integrate)
 importFrom(stats,optimize)
-importFrom(stats,pbeta)
 importFrom(stats,quantile)
 importFrom(stats,rbeta)
 importFrom(stats,rbinom)

R/dbetabinom.R

@@ -1,4 +1,4 @@
-#' Beta-binomial density function
+#' Beta-Binomial Density Function
 #'
 #' @description `r lifecycle::badge("experimental")`
 #'
@@ -38,7 +38,7 @@ dbetabinom <- function(x, m, a, b, log = FALSE) {
 }
 
 
-#' Beta-mixture-binomial density function
+#' Beta-Mixture-Binomial Density Function
 #'
 #' @description `r lifecycle::badge("experimental")`
 #'
@@ -56,6 +56,7 @@ dbetabinom <- function(x, m, a, b, log = FALSE) {
 #' @typed log : flag
 #'  whether to return the log density value (not default).
 #' @return The (log) density values of the mixture of beta-binomial distributions at `x`.
+#'
 #' @note `x` can be a vector.
 #'
 #' @example examples/dbetabinomMix.R
@@ -73,7 +74,9 @@ dbetabinomMix <- function(x, m, par, weights, log = FALSE) {
 dbetabinomMix <- Vectorize(dbetabinomMix, vectorize.args = "x")
 
 
-#' Computes the posterior parameters of a beta mixture
+#' Compute Beta-Mixture-Binomial Posterior Distribution
+#'
+#' Computes the posterior parameters of a beta-mixture-binomial distribution.
 #'
 #' @param x number of successes
 #' @param n number of patients
@@ -177,14 +180,14 @@ pbetaMix <- function(q, par, weights, lower.tail = TRUE) {
 pbetaMix <- Vectorize(pbetaMix, vectorize.args = "q")
 
 
-#' Beta-Mixture Quantile function
+#' Beta-Mixture Quantile Function
 #'
 #' @description `r lifecycle::badge("experimental")`
 #'
 #' Calculates the quantile of the Beta-Mixture distribution for a given probability.
 #'
 #' @typed p : numeric
-#'  the required probability
+#'  the required probability.
 #' @typed par : number
 #'  the beta parameters matrix, with K rows and 2 columns,
 #'  corresponding to the beta parameters of the K components.

R/postprob.R

@@ -1,95 +1,109 @@
 #' @include dbetabinom.R
 NULL
 
-#' Compute the posterior probability to be above threshold assuming a beta prior
-#' on the response rate
+#' Posterior Probability of Efficacy Given Beta Prior
+#'
+#' @description `r lifecycle::badge("experimental")`
 #'
-#' Computes the posterior probability Pr(P_E > p | data). Prior is P_E ~ beta(a, b),
+#' Compute the posterior probability to be above threshold assuming a beta prior
+#' on the response rate such that  `Pr(P_E > p | data)`. Prior is `P_E ~ beta(a, b)`,
 #' with default set to be a uniform or beta(1,1).
 #'
-#' We observed x successes in n trials and so the posterior is
-#' P_E | data  ~ beta(a + x, b + n - x).
+#' We observed `x` successes in n trials and so the posterior is
+#' `P_E | data  ~ beta(a + x, b + n - x)`.
 #'
-#' @param x number of successes
-#' @param n number of patients
-#' @param p threshold
-#' @param a first parameter of the beta prior (successes)
-#' @param b second parameter of the beta prior (failures)
+#' @typed x : numeric
+#'  number of successes.
+#' @typed n : number
+#'  number of patients.
+#' @typed p : number
+#'  threshold set to compute posterior probability.
+#' @typed a : matrix
+#'  first parameter `alpha` of the beta prior (successes).
+#' @typed b : matrix
+#'  second parameter `beta` of the beta prior (failures).
 #' @return The posterior probability that the response rate P_E is above a threshold p.
 #'
-#' @importFrom stats pbeta
-#'
-#' @example examples/postprobOld.R
+#' @example examples/postprobBeta.R
 #' @export
-postprobOld <- function(x, n, p, a = 1, b = 1) {
+postprobBeta <- function(x, n, p, a = 1, b = 1) {
+  assert_number(n, lower = 0, finite = TRUE)
+  assert_numeric(x, lower = 0, upper = n, finite = TRUE)
+  assert_number(a, finite = TRUE)
+  assert_number(b, finite = TRUE)
+  assert_number(p, lower = 0, upper = 1, finite = TRUE)
   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.
+#' Posterior Probability of Efficacy Given Beta-Mixture Prior
+#'
+#' @description `r lifecycle::badge("experimental")`
 #'
-#' Computes the posterior probability `Pr(P_E > p | data)`. Prior is
+#' Compute the posterior probability that the response probability `P_E`is above a threshold.
+#' such that this posterior probability can be expressed as `Pr(P_E > p | data)`. Prior is
 #' `P_E ~ sum(weights * beta(parE[, 1], parE[, 2]))`, i.e., a mixture of beta priors.
 #' Default is one component only with uniform or `beta(1,1)`.
 #'
-#' We observed x successes in n trials. Note that \code{x} can be a vector.
+#' We observed `x` successes in n trials.
 #'
 #' Posterior is again a mixture of beta priors, with updated mixture weights
 #' and beta parameters.
 #'
-#' @param x number of successes
-#' @param n number of patients
-#' @param p threshold
-#' @param parE the beta parameters matrix, with K rows and 2 columns,
-#' corresponding to the beta parameters of the K components. Default is a
-#' uniform prior.
-#' @param weights the mixture weights of the beta mixture prior. Default are
-#' uniform weights across mixture components.
-#' @param betamixPost optional result of \code{\link{getBetamixPost}} in order
-#' to speed up the computations. If supplied, this is directly used, bypassing
-#' the other arguments (except \code{p} and \code{log.p} of course)
-#' @param log.p Return the log of the probability? (default: FALSE)
-#' @return The posterior probability that the response rate P_E is above p.
+#' @typed x : numeric
+#'  number of successes.
+#' @typed n : number
+#'  number of patients.
+#' @typed p : number
+#'  threshold that `P_E` is measured.
+#' @typed parE : matrix
+#'  the beta parameters matrix, with `K` rows and 2 columns,
+#'  corresponding to the beta parameters of the `K` components.
+#'  Default is a uniform prior.
+#' @typed weights : vector
+#'  The mixture weights of the beta mixture prior. Default are
+#'  uniform weights across mixture components.
+#' @typed betamixPost : matrix
+#'  optional result of `[getBetamixPost()]` in order
+#'  to speed up the computations. If supplied, this is directly used, bypassing
+#'  the other arguments (except `p` and `log.p` of course).
+#' @typed log.p : number
+#'  whether to return the log of the probability
+#' @return The posterior probability that the response rate `P_E` is above `p`.
 #'
 #' @example examples/postprob.R
 #' @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
+    assert_flag(log.p)
     if (is.vector(parE)) {
-      ## check that it has exactly two entries
-      stopifnot(identical(length(parE), 2L))
-
-      ## and transpose to matrix with one row
+      # Here there is only one component.
+      assert_true(identical(length(parE), 2L))
+      # To get matrix with one row.
       parE <- t(parE)
     }
-
-    ## if prior weights of the beta mixture are not supplied
+    assert_matrix(parE)
     if (missing(weights)) {
       weights <- rep(1, nrow(parE))
-      ## (don't need to be normalized, this is done in getBetamixPost)
     }
-
-    ## now compute updated parameters
     betamixPost <- getBetamixPost(
       x = x,
       n = n,
       par = parE,
       weights = weights
     )
   }
-
-  ## now compute the survival function at p, i.e. 1 - cdf at p:
+  assert_list(betamixPost)
+  assert_names(names(betamixPost), identical.to = c("par", "weights"))
   ret <- with(
     betamixPost,
     pbetaMix(q = p, par = par, weights = weights, lower.tail = FALSE)
   )
 
   if (log.p) {
-    return(log(ret))
+    log(ret)
   } else {
-    return(ret)
+    ret
   }
 }
 postprob <- Vectorize(postprob, vectorize.args = "x")

examples/postprob.R

@@ -1,19 +1,14 @@
-## Example taken from Lee and Liu
-##
-## We observed 16 successes out of 23 patients
-## We set a threshold of 0.60
-## Assume a beta(0.6,0.4) prior for P_E
-## Posterior will be a beta(16.6, 7.4), Pr(P_E > p | data) = 0.836
-##
-##
+# Example taken from Lee and Liu (2006)
+#
+# We observed 16 successes out of 23 patients
+# We set a threshold of 0.60
+# Assume a beta(0.6,0.4) prior for P_E
+# Posterior will be a beta(16.6, 7.4), Pr(P_E > p | data) = 0.836
 
 postprob(x = 16, n = 23, p = 0.60, par = c(0.6, 0.4))
 
-## We could instead specify a mixture prior
-## 2 component beta mixture prior, i.e., P_E ~ 0.6*beta(0.6,0.4) + 0.4*beta(1,1) and Pr(P_E > p | data) = 0.823
-##
-##
-##
+# We could instead specify a mixture prior
+# 2 component beta mixture prior, i.e., P_E ~ 0.6*beta(0.6,0.4) + 0.4*beta(1,1) and Pr(P_E > p | data) = 0.823
 
 postprob(
   x = 16, n = 23, p = 0.60,

examples/postprobOld.R

@@ -1,10 +1,10 @@
-## Example taken from Lee and Liu (????)
-##
-## We observed 16 successes out of 23 patients
-## We set a threshold of 0.60
-## Assume a beta(0.6,0.4) prior for P_E
-## Posterior will be a beta(16.6,22.8), Pr(P_E > p | data) = 0.8358808
-##
-##
+# Example taken from Lee & Liu (2006)
+# We observed 16 successes out of 23 patients # should we write this in the documentation
+# We set a threshold of 0.60
+# Assume a beta(0.6,0.4) prior for P_E
+# Posterior will be a beta(16.6,22.8), Pr(P_E > p | data) = 0.8358808
 
-postprobOld(x = 16, n = 23, p = 0.60, a = 0.6, b = 0.4)
+
+# Example taken from Lee and Liu (2006)
+postprobBeta(x = 16, n = 23, p = 0.60, a = 0.6, b = 0.4)
+# Interpretation : The probability 16 of 23 successes is greater than 60 % threshold is approximately 84 %