Merge pull request #79 from Gilead-BioStats/documentation

Documentation

DESCRIPTION

@@ -1,7 +1,7 @@
 Type: Package
 Package: graphicalMCP
 Title: Graphical Multiple Comparison Procedures
-Version: 0.1.1
+Version: 0.1.2
 Authors@R: c(
     person("Dong", "Xi", , "dong.xi1@gilead.com", role = c("aut", "cre")),
     person("Ethan", "Brockmann", , "ethan.brockmann@atorusresearch.com", role = "aut"),

NAMESPACE

@@ -16,6 +16,8 @@ export(as_initial_graph)
 export(bonferroni)
 export(bonferroni_holm)
 export(fallback)
+export(fallback_improved_1)
+export(fallback_improved_2)
 export(fixed_sequence)
 export(graph_calculate_power)
 export(graph_create)
@@ -24,8 +26,9 @@ export(graph_rejection_orderings)
 export(graph_test_closure)
 export(graph_test_shortcut)
 export(graph_update)
-export(huque_alosh_bhore_2011)
+export(huque_etal)
 export(random_graph)
 export(simple_successive_1)
 export(simple_successive_2)
-export(wiens_dmitrienko_2005)
+export(three_doses_two_primary_two_secondary)
+export(two_doses_two_primary_two_secondary)

NEWS.md

@@ -6,3 +6,8 @@
 
 * Added compilation of vignettes (#73)
 * Removed duplicated columns of "*" in test values (#75)
+
+# graphicalMCP 0.1.2
+
+* Updated function documentation
+* Updated references

R/adjust_p.R

@@ -1,36 +1,75 @@
 #' Calculate adjusted p-values
 #'
-#' @param p A numeric vector of p-values
-#' @param hypotheses A numeric vector of hypothesis weights
-#' @param test_corr (Optional) A numeric matrix of correlations between
-#'   hypotheses' test statistics
+#' @description
+#' For an intersection hypothesis, an adjusted p-value is the smallest
+#' significance level at which the intersection hypothesis can be rejected.
+#' The intersection hypothesis can be rejected if its adjusted p-value is less
+#' than or equal to \eqn{\alpha}. Currently, there are three test types
+#' supported:
+#' * Bonferroni tests for `graphicalMCP:::adjust_p_bonferroni()`,
+#' * Parametric tests for `graphicalMCP:::adjust_p_parametric()`,
+#'     - Note that one-sided tests are required for parametric tests.
+#' * Simes tests for `graphicalMCP:::adjust_p_simes()`.
 #'
-#' @return A single adjusted p-value for the given group
+#' @param p A numeric vector of p-values (unadjusted, raw), whose values should
+#'   be between 0 & 1. The length should match the length of `hypotheses`.
+#' @param hypotheses A numeric vector of hypothesis weights. Must be a vector of
+#'   values between 0 & 1 (inclusive). The length should match the length of
+#'   `p`. The sum of hypothesis weights should not exceed 1.
+#' @param test_corr (Optional) A numeric matrix of correlations between test
+#'   statistics, which is needed to perform parametric tests using
+#'   `graphicalMCP:::adjust_p_parametric()`. The number of rows and columns of
+#'   this correlation matrix should match the length of `p`.
+#' @param maxpts (Optional) An integer scalar for the maximum number of function
+#'   values, which is needed to perform parametric tests using the
+#'   `mvtnorm::GenzBretz` algorithm. The default is 25000.
+#' @param abseps (Optional) A numeric scalar for the absolute error tolerance,
+#'   which is needed to perform parametric tests using the `mvtnorm::GenzBretz`
+#'   algorithm. The default is 1e-6.
+#' @param releps (Optional) A numeric scalar for the relative error tolerance
+#'   as double, which is needed to perform parametric tests using the
+#'   `mvtnorm::GenzBretz` algorithm. The default is 0.
+#'
+#' @return A single adjusted p-value for the intersection hypothesis.
+#'
+#' @seealso
+#'   `graphicalMCP:::adjust_weights_parametric()` for adjusted hypothesis
+#'   weights using parametric tests, `graphicalMCP:::adjust_weights_simes()`
+#'   for adjusted hypothesis weights using Simes tests.
 #'
 #' @rdname adjust_p
 #'
 #' @keywords internal
 #'
-#' @template references
+#' @references
+#'   Bretz, F., Maurer, W., Brannath, W., and Posch, M. (2009). A graphical
+#'   approach to sequentially rejective multiple test procedures.
+#'   \emph{Statistics in Medicine}, 28(4), 586-604.
 #'
-#' @examples
-#' set.seed(22723)
+#'   Lu, K. (2016). Graphical approaches using a Bonferroni mixture of weighted
+#'   Simes tests. \emph{Statistics in Medicine}, 35(22), 4041-4055.
 #'
-#' w <- c("H1" = .75, "H2" = .25, "H3" = 0)
-#' p <- c("H1" = .019, "H2" = .025, "H3" = .05)
+#'   Xi, D., Glimm, E., Maurer, W., and Bretz, F. (2017). A unified framework
+#'   for weighted parametric multiple test procedures.
+#'   \emph{Biometrical Journal}, 59(5), 918-931.
 #'
-#' graphicalMCP:::adjust_p_bonferroni(p, w)
-#' graphicalMCP:::adjust_p_simes(p, w)
+#' @examples
+#' set.seed(1234)
 #'
-#' corr1 <- diag(3)
-#' corr2 <- corr1
-#' corr2[lower.tri(corr2)] <- corr2[upper.tri(corr2)] <- runif(3, -1, 1)
+#' hypotheses <- c(H1 = 0.5, H2 = 0.25, H3 = 0.25)
+#' p <- c(0.019, 0.025, 0.05)
 #'
-#' # No correlation
-#' graphicalMCP:::adjust_p_parametric(p, w, corr1)
+#' # Bonferroni test
+#' graphicalMCP:::adjust_p_bonferroni(p, hypotheses)
 #'
-#' # Uniform random pairwise correlations
-#' graphicalMCP:::adjust_p_parametric(p, w, corr2)
+#' # Simes test
+#' graphicalMCP:::adjust_p_simes(p, hypotheses)
+#'
+#' # Parametric test
+#' # Using the `mvtnorm::GenzBretz` algorithm
+#' corr <- matrix(0.5, nrow = 3, ncol = 3)
+#' diag(corr) <- 1
+#' graphicalMCP:::adjust_p_parametric(p, hypotheses, corr)
 adjust_p_bonferroni <- function(p, hypotheses) {
   if (sum(hypotheses) == 0) {
     return(Inf)
@@ -45,7 +84,13 @@ adjust_p_bonferroni <- function(p, hypotheses) {
 }
 
 #' @rdname adjust_p
-adjust_p_parametric <- function(p, hypotheses, test_corr = NULL) {
+#' @keywords internal
+adjust_p_parametric <- function(p,
+                                hypotheses,
+                                test_corr = NULL,
+                                maxpts = 25000,
+                                abseps = 1e-6,
+                                releps = 0) {
   if (sum(hypotheses) == 0) {
     return(Inf)
   }
@@ -61,7 +106,11 @@ adjust_p_parametric <- function(p, hypotheses, test_corr = NULL) {
       lower = -Inf,
       upper = z,
       corr = test_corr[w_nonzero, w_nonzero, drop = FALSE],
-      algorithm = mvtnorm::GenzBretz(maxpts = 25000, abseps = 1e-6, releps = 0)
+      algorithm = mvtnorm::GenzBretz(
+        maxpts = maxpts,
+        abseps = abseps,
+        releps = releps
+      )
     )[[1]]
   )
 
@@ -72,6 +121,7 @@ adjust_p_parametric <- function(p, hypotheses, test_corr = NULL) {
 }
 
 #' @rdname adjust_p
+#' @keywords internal
 adjust_p_simes <- function(p, hypotheses) {
   if (sum(hypotheses) == 0) {
     return(Inf)