Updated function documentation

Populated function documentations for all functions except
-edge_pairs.R
-test_power_input_val.R

Changed the citation format

Added/changes examples

Changed some names of example graphs

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", , "[email protected]", role = c("aut", "cre")),
     person("Ethan", "Brockmann", , "[email protected]", role = "aut"),
@@ -19,7 +19,8 @@ Depends:
     R (>= 4.1.0)
 Imports: 
     matrixStats,
-    mvtnorm
+    mvtnorm,
+    Rdpack
 Suggests: 
     bench,
     dplyr,
@@ -42,6 +43,8 @@ Suggests:
     xfun
 VignetteBuilder: 
     knitr
+RdMacros:
+    Rdpack
 Config/testthat/edition: 3
 Encoding: UTF-8
 LazyData: true

NAMESPACE

@@ -16,16 +16,21 @@ 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)
 export(graph_generate_weights)
 export(graph_rejection_orderings)
 export(graph_test_closure)
+export(graph_test_closure_fast)
 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)
+importFrom(Rdpack,reprompt)

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 reference and added the dependency package Rdpack

R/adjust_p.R

@@ -1,36 +1,59 @@
 #' 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 \insertCite{xi-2017-unified}{graphicalMCP} for
+#'   `graphicalMCP:::adjust_p_parametric()`,
+#'     - Note that one-sided tests are required for parametric tests.
+#' * Simes tests \insertCite{lu-2016-graphical}{graphicalMCP} 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`.
+#'
+#' @return A single adjusted p-value for the intersection hypothesis.
+#'
+#' @family graphical tests
 #'
 #' @rdname adjust_p
 #'
+#' @importFrom Rdpack reprompt
+#'
 #' @keywords internal
 #'
-#' @template references
+#' @references
+#'  * \insertRef{bretz-2009-graphical}{graphicalMCP}
+#'  * \insertRef{lu-2016-graphical}{graphicalMCP}
+#'  * \insertRef{xi-2017-unified}{graphicalMCP}
 #'
 #' @examples
 #' set.seed(22723)
 #'
-#' w <- c("H1" = .75, "H2" = .25, "H3" = 0)
-#' p <- c("H1" = .019, "H2" = .025, "H3" = .05)
-#'
-#' graphicalMCP:::adjust_p_bonferroni(p, w)
-#' graphicalMCP:::adjust_p_simes(p, w)
+#' hypotheses <- c(H1 = 0.5, H2 = 0.25, H3 = 0.25)
+#' p <- c(0.019, 0.025, 0.05)
 #'
-#' corr1 <- diag(3)
-#' corr2 <- corr1
-#' corr2[lower.tri(corr2)] <- corr2[upper.tri(corr2)] <- runif(3, -1, 1)
+#' # Bonferroni test
+#' graphicalMCP:::adjust_p_bonferroni(p, hypotheses)
 #'
-#' # No correlation
-#' graphicalMCP:::adjust_p_parametric(p, w, corr1)
+#' # Simes test
+#' graphicalMCP:::adjust_p_simes(p, hypotheses)
 #'
-#' # Uniform random pairwise correlations
-#' graphicalMCP:::adjust_p_parametric(p, w, corr2)
+#' # Parametric test
+#' # Using the `mvtnorm::GenzBretz` algorithm with `abseps = 1e-6`
+#' 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)

R/adjust_weights.R

@@ -1,58 +1,84 @@
-#' Calculate updated hypothesis weights for the closure of a graph
+#' Calculate adjusted hypothesis weights
 #'
-#' The weights created by [graph_generate_weights()] work immediately for
-#' Bonferroni testing, but parametric and Simes testing require additional
-#' calculations. The `adjust_weights_*()` functions apply parametric or Simes
-#' weight increases to get updated weights for testing. They also subset the
-#' weights columns by the appropriate groups
+#' @description
+#' An intersection hypothesis can be rejected if its p-values are less than or
+#' equal to their adjusted significance levels, which are their adjusted
+#' hypothesis weights times \eqn{\alpha}. For Bonferroni tests, their adjusted
+#' hypothesis weights are their hypothesis weights of the intersection
+#' hypothesis. Additional adjustment is needed for parametric and Simes tests:
+#' * Parametric tests \insertCite{xi-2017-unified}{graphicalMCP} for
+#'   `graphicalMCP:::adjust_weights_parametric()`,
+#'     - Note that one-sided tests are required for parametric tests.
+#' * Simes tests \insertCite{lu-2016-graphical}{graphicalMCP} for
+#'   `graphicalMCP:::adjust_weights_simes()`.
 #'
-#' @param matrix_weights The second half of columns from
-#'   [graph_generate_weights()] output, indicating the weights of each
-#'   intersection
-#' @param matrix_intersections The first half of columns from
-#'   [graph_generate_weights()] output, indicating which hypotheses are
-#'   contained in each intersection
-#' @param test_corr A numeric matrix of correlations between hypotheses' test
-#'   statistics
-#' @param alpha A numeric scalar specifying the global significance level for
-#'   testing
-#' @param test_groups A list of numeric vectors specifying hypotheses to test
-#'   together
-#' @param p A numeric vector of p-values
-#' @param hypotheses A numeric vector of hypothesis weights
-#' @param x The root to solve for with [stats::uniroot()]
+#' @param matrix_weights A matrix of hypothesis weights of all intersection
+#'   hypotheses. This can be obtained as the second half of columns from the
+#'   output of [graph_generate_weights()].
+#' @param matrix_intersections A matrix of hypothesis indicators of all
+#'   intersection hypotheses. This can be obtained as the first half of columns
+#'   from the output of [graph_generate_weights()].
+#' @inheritParams graph_test_closure
+#' @inheritParams graph_create
+#' @param x The root to solve for with [stats::uniroot()].
 #'
-#' @return Outputs:
-#' * For `adjust_weights_*()`, a matrix with the same shape as
-#'   `weighting_strategy`, where the weights have been adjusted according to the
-#'   specified adjustment method
-#' * For `c_value_function()`, the \eqn{c_{J_h}} value for the given group,
-#'   according to Formula 6 of Xi et al. (2017).
+#' @return
+#' * `adjust_weights_parametric()` returns a matrix with the same dimensions
+#'   as `weighting_strategy`, whose hypothesis weights have been adjusted
+#'   according to parametric tests.
+#' * `adjust_weights_simes()` returns a matrix with the same dimensions
+#'   as `weighting_strategy`, whose hypothesis weights have been adjusted
+#'   according to Simes tests.
+#' * `c_value_function()` returns the difference between \eqn{\alpha} and the
+#'   Type I error of the parametric test with the c value of `x`, adjusted for
+#'   the correlation between test statistics using parametric tests based on
+#'   equation (6) of \insertCite{xi-2017-unified}{graphicalMCP}.
+#' * `solve_c_parametric()` returns the c value adjusted for the correlation
+#'   between test statistics using parametric tests based on equation (6) of
+#'   \insertCite{xi-2017-unified}{graphicalMCP}.
 #'
-#' @rdname adjusted-weights
+#' @family graphical tests
 #'
-#' @keywords internal
+#' @rdname adjusted_weights
 #'
-#' @template references
+#' @importFrom Rdpack reprompt
 #'
-#' @examples
-#' p <- 1:6 / 200
+#' @keywords internal
 #'
-#' g <- bonferroni_holm(6)
-#' gw_large <- graph_generate_weights(g)
+#' @references
+#'  * \insertRef{lu-2016-graphical}{graphicalMCP}
+#'  * \insertRef{xi-2017-unified}{graphicalMCP}
 #'
-#' gw_0 <- gw_large[, 7:12]
-#' gw <- ifelse(gw_large[, 1:6], gw_0, NA)
+#' @examples
+#' set.seed(1234)
+#' alpha <- 0.025
+#' p <- c(0.018, 0.01, 0.105, 0.006)
+#' num_hyps <- length(p)
+#' g <- bonferroni_holm(rep(1 / 4, 4))
+#' weighting_strategy <- graph_generate_weights(g)
+#' matrix_intersections <- weighting_strategy[, seq_len(num_hyps)]
+#' matrix_weights <- weighting_strategy[, -seq_len(num_hyps)]
 #'
+#' set.seed(1234)
 #' graphicalMCP:::adjust_weights_parametric(
-#'   gw_0,
-#'   gw_large[, 1:6],
-#'   diag(6),
-#'   .05,
-#'   list(1:3)
+#'   matrix_weights = matrix_weights,
+#'   matrix_intersections = matrix_intersections,
+#'   test_corr = diag(4),
+#'   alpha = alpha,
+#'   test_groups = list(1:4)
 #' )
 #'
-#' graphicalMCP:::adjust_weights_simes(gw_0, p, list(4:6))
+#' graphicalMCP:::adjust_weights_simes(
+#'   matrix_weights = matrix_weights,
+#'   p = p,
+#'   test_groups = list(1:4)
+#' )
+#'
+#' graphicalMCP:::solve_c_parametric(
+#'   hypotheses = matrix_weights[1, ],
+#'   test_corr = diag(4),
+#'   alpha = alpha
+#' )
 adjust_weights_parametric <- function(matrix_weights,
                                       matrix_intersections,
                                       test_corr,
@@ -85,25 +111,24 @@ adjust_weights_parametric <- function(matrix_weights,
   adjusted_weights[, unlist(test_groups), drop = FALSE]
 }
 
-#' @rdname adjusted-weights
-adjust_weights_simes <- function(matrix_weights, p, groups) {
+#' @rdname adjusted_weights
+adjust_weights_simes <- function(matrix_weights, p, test_groups) {
   ordered_p <- order(p)
 
   matrix_weights <- matrix_weights[, ordered_p, drop = FALSE]
 
-  group_adjusted_weights <- vector("list", length(groups))
-
-  for (i in seq_along(groups)) {
+  group_adjusted_weights <- vector("list", length(test_groups))
+  for (i in seq_along(test_groups)) {
     group_adjusted_weights[[i]] <- matrixStats::rowCumsums(
-      matrix_weights[, ordered_p %in% groups[[i]], drop = FALSE],
+      matrix_weights[, ordered_p %in% test_groups[[i]], drop = FALSE],
       useNames = TRUE
     )
   }
 
   do.call(cbind, group_adjusted_weights)
 }
 
-#' @rdname adjusted-weights
+#' @rdname adjusted_weights
 c_value_function <- function(x, hypotheses, test_corr, alpha) {
   hyps_nonzero <- which(hypotheses > 0)
   z <- stats::qnorm(x * hypotheses[hyps_nonzero] * alpha, lower.tail = FALSE)
@@ -121,7 +146,7 @@ c_value_function <- function(x, hypotheses, test_corr, alpha) {
   y - alpha * sum(hypotheses)
 }
 
-#' @rdname adjusted-weights
+#' @rdname adjusted_weights
 solve_c_parametric <- function(hypotheses, test_corr, alpha) {
   num_hyps <- seq_along(hypotheses)
   c_value <- ifelse(