Package {graphicalMCP}

graphicalMCP: Graphical Multiple Comparison Procedures

Description

Multiple comparison procedures (MCPs) control the familywise error rate in clinical trials. Graphical MCPs include many commonly used procedures as special cases; see Bretz et al. (2011) doi:10.1002/bimj.201000239, Lu (2016) doi:10.1002/sim.6985, and Xi et al. (2017) doi:10.1002/bimj.201600233. This package is a low-dependency implementation of graphical MCPs which allow mixed types of tests. It also includes power simulations and visualization of graphical MCPs.

Author(s)

Maintainer: Dong Xi dong.xi1@gilead.com

Authors:

• Ethan Brockmann ethan.brockmann@atorusresearch.com

Other contributors:

• Gilead Sciences, Inc. [copyright holder, funder]

See Also

Useful links:

• https://openpharma.github.io/graphicalMCP/

• https://github.com/openpharma/graphicalMCP

• Report bugs at https://github.com/openpharma/graphicalMCP/issues

Calculate adjusted p-values

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 \alpha. Currently, there are three test types supported:

• Bonferroni tests for adjust_p_bonferroni(),

• Parametric tests for adjust_p_parametric(),

  • Note that one-sided tests are required for parametric tests.

• Simes tests for adjust_p_simes(),

• Hochberg tests for adjust_p_hochberg().

Usage

adjust_p_bonferroni(p, hypotheses)

adjust_p_parametric(
  p,
  hypotheses,
  test_corr = NULL,
  maxpts = 25000,
  abseps = 1e-06,
  releps = 0
)

adjust_p_simes(p, hypotheses)

adjust_p_hochberg(p, hypotheses)

Arguments

Value

A single adjusted p-value for the intersection hypothesis.

References

Bretz, F., Maurer, W., Brannath, W., and Posch, M. (2009). A graphical approach to sequentially rejective multiple test procedures. Statistics in Medicine, 28(4), 586-604.

Lu, K. (2016). Graphical approaches using a Bonferroni mixture of weighted Simes tests. Statistics in Medicine, 35(22), 4041-4055.

Xi, D., Glimm, E., Maurer, W., and Bretz, F. (2017). A unified framework for weighted parametric multiple test procedures. Biometrical Journal, 59(5), 918-931.

Xi, D., and Bretz, F. (2019). Symmetric graphs for equally weighted tests, with application to the Hochberg procedure. Statistics in Medicine, 38(27), 5268-5282.

See Also

adjust_weights_parametric() for adjusted hypothesis weights using parametric tests, adjust_weights_simes() for adjusted hypothesis weights using Simes tests, adjust_weights_hochberg() for adjusted hypothesis weights using Hochberg tests.

Examples

hypotheses <- c(H1 = 0.5, H2 = 0.25, H3 = 0.25)
p <- c(0.019, 0.025, 0.05)
adjust_p_bonferroni(p, hypotheses)
set.seed(1234)
hypotheses <- c(H1 = 0.5, H2 = 0.25, H3 = 0.25)
p <- c(0.019, 0.025, 0.05)
# Using the `mvtnorm::GenzBretz` algorithm
corr <- matrix(0.5, nrow = 3, ncol = 3)
diag(corr) <- 1
adjust_p_parametric(p, hypotheses, corr)
hypotheses <- c(H1 = 0.5, H2 = 0.25, H3 = 0.25)
p <- c(0.019, 0.025, 0.05)
adjust_p_simes(p, hypotheses)
hypotheses <- c(H1 = .25, H2 = .25, H3 = 0.25, H4 = 0.25)
p <- c(0.019, 0.025, 0.05, .05)
adjust_p_hochberg(p, hypotheses)

Calculate adjusted hypothesis weights

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 \alpha. For Bonferroni tests, their adjusted hypothesis weights are their hypothesis weights of the intersection hypothesis. Additional adjustment is needed for parametric, Simes, and Hochberg tests:

• Parametric tests for adjust_weights_parametric(),

  • Note that one-sided tests are required for parametric tests.

• Simes tests for adjust_weights_simes(),

• Hochberg tests for adjust_weights_hochberg().

Usage

adjust_weights_parametric(
  matrix_weights,
  matrix_intersections,
  test_corr,
  alpha,
  test_groups,
  ...
)

adjust_weights_simes(matrix_weights, p, test_groups)

adjust_weights_hochberg(matrix_weights, matrix_intersections, p, test_groups)

Arguments

Value

• adjust_weights_parametric() returns a matrix with the same dimensions as matrix_weights, whose hypothesis weights have been adjusted according to parametric tests.

• adjust_weights_simes() returns a matrix with the same dimensions as matrix_weights, whose hypothesis weights have been adjusted according to Simes tests.

• adjust_weights_hochberg() returns a matrix with the same dimensions as matrix_weights, whose hypothesis weights have been adjusted according to Hochberg tests.

References

Lu, K. (2016). Graphical approaches using a Bonferroni mixture of weighted Simes tests. Statistics in Medicine, 35(22), 4041-4055.

Xi, D., Glimm, E., Maurer, W., and Bretz, F. (2017). A unified framework for weighted parametric multiple test procedures. Biometrical Journal, 59(5), 918-931.

Xi, D., and Bretz, F. (2019). Symmetric graphs for equally weighted tests, with application to the Hochberg procedure. Statistics in Medicine, 38(27), 5268-5282.

See Also

adjust_p_parametric() for adjusted p-values using parametric tests, adjust_p_simes() for adjusted p-values using Simes tests, adjust_p_hochberg() for adjusted p-values using Hochberg tests.

Examples

alpha <- 0.025
num_hyps <- 4
g <- bonferroni_holm(num_hyps)
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)
adjust_weights_parametric(
  matrix_weights = matrix_weights,
  matrix_intersections = matrix_intersections,
  test_corr = list(diag(2), diag(2)),
  alpha = alpha,
  test_groups = list(1:2, 3:4)
)
alpha <- 0.025
p <- c(0.018, 0.01, 0.105, 0.006)
num_hyps <- length(p)
g <- bonferroni_holm(num_hyps)
weighting_strategy <- graph_generate_weights(g)
matrix_intersections <- weighting_strategy[, seq_len(num_hyps)]
matrix_weights <- weighting_strategy[, -seq_len(num_hyps)]

adjust_weights_simes(
  matrix_weights = matrix_weights,
  p = p,
  test_groups = list(1:2, 3:4)
)
alpha <- 0.025
p <- c(0.018, 0.01, 0.105, 0.006)
num_hyps <- length(p)
g <- bonferroni_holm(num_hyps)
weighting_strategy <- graph_generate_weights(g)
matrix_intersections <- weighting_strategy[, seq_len(num_hyps)]
matrix_weights <- weighting_strategy[, -seq_len(num_hyps)]

adjust_weights_hochberg(
  matrix_weights = matrix_weights,
  matrix_intersections = matrix_intersections,
  p = p,
  test_groups = list(1:2, 3:4)
)

Convert between graphicalMCP, gMCP, and igraph graph classes

Description

Graph objects have different structures and attributes in graphicalMCP, gMCP, and igraph R packages. These functions convert between different classes to increase compatibility.

Note that igraph and gMCP have additional attributes for vertices, edges, or a graph itself. These conversion functions only handle attributes related to hypothesis names, hypothesis weights and transition weights. Other attributes will be dropped when converting.

Usage

as_initial_graph(graph)

## S3 method for class 'graphMCP'
as_initial_graph(graph)

## S3 method for class 'igraph'
as_initial_graph(graph)

as_graphMCP(graph)

## S3 method for class 'initial_graph'
as_graphMCP(graph)

as_igraph(graph)

## S3 method for class 'initial_graph'
as_igraph(graph)

Arguments

Value

• as_graphMCP() returns a graphMCP object for the gMCP package.

• as_igraph() returns an igraph object for the igraph package.

• as_initial_graph() returns an initial_graph object for the graphicalMCP package.

References

Csardi, G., Nepusz, T., Traag, V., Horvat, S., Zanini, F., Noom, D., and Mueller, K. (2024). igraph: Network analysis and visualization in R. R package version 2.0.3. https://CRAN.R-project.org/package=igraph.

Rohmeyer, K., and Klinglmueller, K. (2024). gMCP: Graph based multiple test procedures. R package version 0.8-17. https://cran.r-project.org/package=gMCP.

See Also

graph_create() for the initial graph used in the graphicalMCP package.

Examples

g_graphicalMCP <- random_graph(5)

if (requireNamespace("gMCP", quietly = TRUE)) {
  g_gMCP <- as_graphMCP(g_graphicalMCP)

  all.equal(g_graphicalMCP, as_initial_graph(g_gMCP))
}

if (requireNamespace("igraph", quietly = TRUE)) {
  g_igraph <- as_igraph(g_graphicalMCP)

  all.equal(g_graphicalMCP, as_initial_graph(g_igraph))
}

Example graphs of commonly used multiple comparison procedures

Description

Built-in functions to quickly generate select graphical multiple comparison procedures.

Usage

bonferroni(num_hyps, hyp_names = NULL)

bonferroni_weighted(hypotheses, hyp_names = NULL)

bonferroni_holm(num_hyps, hyp_names = NULL)

bonferroni_holm_weighted(hypotheses, hyp_names = NULL)

dunnett_single_step(num_hyps, hyp_names = NULL)

dunnett_single_step_weighted(hypotheses, hyp_names = NULL)

dunnett_closure_weighted(hypotheses, hyp_names = NULL)

hochberg(num_hyps, hyp_names = NULL)

hommel(num_hyps, hyp_names = NULL)

huque_etal(hyp_names = NULL)

fallback(hypotheses, hyp_names = NULL)

fallback_improved_1(hypotheses, hyp_names = NULL)

fallback_improved_2(hypotheses, epsilon = 1e-04, hyp_names = NULL)

fixed_sequence(num_hyps, hyp_names = NULL)

sidak(num_hyps, hyp_names = NULL)

simple_successive_1(hyp_names = NULL)

simple_successive_2(hyp_names = NULL)

two_doses_two_primary_two_secondary(hyp_names = NULL)

three_doses_two_primary_two_secondary(hyp_names = NULL)

random_graph(num_hyps, hyp_names = NULL)

Arguments

Value

An S3 object as returned by graph_create().

References

Bretz, F., Maurer, W., Brannath, W., and Posch, M. (2009). A graphical approach to sequentially rejective multiple test procedures. Statistics in Medicine, 28(4), 586-604.

Bretz, F., Posch, M., Glimm, E., Klinglmueller, F., Maurer, W., and Rohmeyer, K. (2011). Graphical approaches for multiple comparison procedures using weighted Bonferroni, Simes, or parametric tests. Biometrical Journal, 53(6), 894-913.

Hochberg, Y. (1988). A sharper Bonferroni procedure for multiple tests of significance. Biometrika, 75(4), 800-802.

Hommel, G. (1988). A stagewise rejective multiple test procedure based on a modified Bonferroni test. Biometrika, 75(2), 383-386.

Huque, M. F., Alosh, M., and Bhore, R. (2011). Addressing multiplicity issues of a composite endpoint and its components in clinical trials. Journal of Biopharmaceutical Statistics, 21(4), 610-634.

Maurer, W., Hothorn, L., and Lehmacher, W. (1995). Multiple comparisons in drug clinical trials and preclinical assays: a-priori ordered hypotheses. Biometrie in der chemisch-pharmazeutischen Industrie, 6, 3-18.

Šidák, Z. (1967). Rectangular confidence regions for the means of multivariate normal distributions. Journal of the American Statistical Association, 62(318), 626-633.

Westfall, P. H., and Krishen, A. (2001). Optimally weighted, fixed sequence and gatekeeper multiple testing procedures. Journal of Statistical Planning and Inference, 99(1), 25-40.

Wiens, B. L. (2003). A fixed sequence Bonferroni procedure for testing multiple endpoints. Pharmaceutical Statistics, 2(3), 211-215.

Wiens, B. L., and Dmitrienko, A. (2005). The fallback procedure for evaluating a single family of hypotheses. Journal of Biopharmaceutical Statistics, 15(6), 929-942.

Xi, D., and Bretz, F. (2019). Symmetric graphs for equally weighted tests, with application to the Hochberg procedure. Statistics in Medicine, 38(27), 5268-5282.

See Also

graph_create() for a general way to create the initial graph.

Examples

# Bretz et al. (2009)
bonferroni(num_hyps = 3)
# Bretz et al. (2009)
hypotheses <- c(0.5, 0.3, 0.2)
bonferroni_weighted(hypotheses)
# Bretz et al. (2009)
bonferroni_holm(num_hyps = 3)
# Bretz et al. (2009)
hypotheses <- c(0.5, 0.3, 0.2)
bonferroni_holm_weighted(hypotheses)
# Xi et al. (2017)
dunnett_single_step(num_hyps = 3)
# Xi et al. (2017)
hypotheses <- c(0.5, 0.3, 0.2)
dunnett_single_step_weighted(hypotheses)
# Xi et al. (2009)
hypotheses <- c(0.5, 0.3, 0.2)
dunnett_closure_weighted(hypotheses)
# Hochberg (1988)
hochberg(num_hyps = 3)
# Hommel (1988)
hommel(num_hyps = 3)
# Huque et al. (2011)
huque_etal()
# Wiens (2003)
hypotheses <- c(0.5, 0.3, 0.2)
fallback(hypotheses)
# Wiens and Dmitrienko (2005)
hypotheses <- c(0.5, 0.3, 0.2)
fallback_improved_1(hypotheses)
# Bretz et al. (2009)
hypotheses <- c(0.5, 0.3, 0.2)
fallback_improved_2(hypotheses)
# Maurer et al. (1995); Westfall and Krishen (2001)
fixed_sequence(num_hyps = 3)
# sidak (1967)
sidak(num_hyps = 3)
# Figure 1 in Bretz et al. (2011)
simple_successive_1()
# Figure 4 in Bretz et al. (2011)
simple_successive_2()
# Figure 6 in Xi and Bretz et al. (2019)
two_doses_two_primary_two_secondary()
# Add another dose to Figure 6 in Xi and Bretz et al. (2019)
three_doses_two_primary_two_secondary()
# Create a random graph with three hypotheses
random_graph(num_hyps = 3)

Calculate adjusted hypothesis weights for parametric tests

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 \alpha. For Bonferroni tests, their adjusted hypothesis weights are their hypothesis weights of the intersection hypothesis. Additional adjustment is needed for parametric tests:

• Parametric tests for adjust_weights_parametric(),

  • Note that one-sided tests are required for parametric tests.

Usage

c_value_function(
  x,
  hypotheses,
  test_corr,
  alpha,
  maxpts = 25000,
  abseps = 1e-06,
  releps = 0
)

solve_c_parametric(
  hypotheses,
  test_corr,
  alpha,
  maxpts = 25000,
  abseps = 1e-06,
  releps = 0
)

adjust_weights_parametric_util(
  matrix_weights,
  matrix_intersections,
  test_corr,
  alpha,
  test_groups,
  maxpts = 25000,
  abseps = 1e-06,
  releps = 0
)

Arguments

Value

• c_value_function() returns the difference between \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 Xi et al. (2017).

• solve_c_parametric() returns the c value adjusted for the correlation between test statistics using parametric tests based on equation (6) of Xi et al. (2017).

References

Xi, D., Glimm, E., Maurer, W., and Bretz, F. (2017). A unified framework for weighted parametric multiple test procedures. Biometrical Journal, 59(5), 918-931.

See Also

adjust_weights_parametric() for adjusted hypothesis weights using parametric tests.

Find pairs of vertices that are connected in both directions

Description

For an initial graph, find pairs of hypotheses that are connected in both directions. This is used to plot graphs using plot.initial_graph().

Usage

edge_pairs(graph)

Arguments

Value

A list of vertex pairs which are connected in both directions. NULL if no such pairs are found.

Calculate power values for a graphical multiple comparison procedure

Description

Under the alternative hypotheses, the distribution of test statistics is assumed to be a multivariate normal distribution. Given this distribution, this function calculates power values for a graphical multiple comparison procedure. By default, it calculate the local power, which is the probability to reject an individual hypothesis, the probability to reject at least one hypothesis, the probability to reject all hypotheses, the expected number of rejections, and the probability of user-defined success criteria. See vignette("shortcut-testing") and vignette("closed-testing") for more illustration of power calculation.

Usage

graph_calculate_power(
  graph,
  alpha = 0.025,
  power_marginal = rep(alpha, length(graph$hypotheses)),
  test_groups = list(seq_along(graph$hypotheses)),
  test_types = c("bonferroni"),
  test_corr = rep(list(NA), length(test_types)),
  sim_n = 1e+05,
  sim_corr = diag(length(graph$hypotheses)),
  sim_success = NULL,
  verbose = FALSE
)

Arguments

Value

A power_report object with a list of 3 elements:

• inputs - Input parameters, which is a list of:

  • graph - Initial graph,

  • alpha - Overall significance level,

  • test_groups - Groups of hypotheses for different types of tests,

  • test_types - Different types of tests,

  • test_corr - Correlation matrices for parametric tests,

  • sim_n - Number of simulations,

  • power_marginal - Marginal power of all hypotheses

  • sim_corr - Correlation matrices for simulations,

  • sim_success - User-defined success criteria.

• power - A list of power values

  • power_local - Local power of all hypotheses, which is the proportion of simulations in which each hypothesis is rejected,

  • rejection_expected - Expected (average) number of rejected hypotheses,

  • power_at_least_1 - Power to reject at least one hypothesis,

  • power_all - Power to reject all hypotheses,

  • power_success - Power of user-defined success, which is the proportion of simulations in which the user-defined success criterion

  • sim_success is met.

• details - An optional list of datasets showing simulated p-values and results for each simulation.

Simulation details

The power calculation is based on simulations. The distribution to simulate from is determined as a multivariate normal distribution by power_marginal and sim_corr. In particular, power_marginal is a vector of marginal power values for all hypotheses. The marginal power is the power to reject the null hypothesis at the significance level alpha without multiplicity adjustment. This value could be readily available from standard software and other R packages. Then we can determine the mean of the multivariate normal distribution as

\Phi^{-1}\left(1-\alpha\right)-\Phi^{-1}\left(1-d_i\right)

, which is often called the non-centrality parameter or the drift parameter. Here d_i is the marginal power power_marginal of hypothesis i. Given the correlation matrix sim_corr, we can simulate from this multivariate normal distribution using the mvtnorm R package (Genz and Bretz, 2009).

Each set simulated values can be used to calculate the corresponding one-sided p-values. Then this set of p-values are plugged into the graphical multiple comparison procedure to determine which hypotheses are rejected. This process is repeated n_sim times to produce the power values as the proportion of simulations in which a particular success criterion is met.

References

Bretz, F., Posch, M., Glimm, E., Klinglmueller, F., Maurer, W., and Rohmeyer, K. (2011a). Graphical approaches for multiple comparison procedures using weighted Bonferroni, Simes, or parametric tests. Biometrical Journal, 53(6), 894-913.

Bretz, F., Maurer, W., and Hommel, G. (2011b). Test and power considerations for multiple endpoint analyses using sequentially rejective graphical procedures. Statistics in Medicine, 30(13), 1489-1501.

Genz, A., and Bretz, F. (2009). Computation of Multivariate Normal and t Probabilities, series Lecture Notes in Statistics. Springer-Verlag, Heidelberg.

Lu, K. (2016). Graphical approaches using a Bonferroni mixture of weighted Simes tests. Statistics in Medicine, 35(22), 4041-4055.

Xi, D., Glimm, E., Maurer, W., and Bretz, F. (2017). A unified framework for weighted parametric multiple test procedures. Biometrical Journal, 59(5), 918-931.

Examples

# A graphical multiple comparison procedure with two primary hypotheses (H1
# and H2) and two secondary hypotheses (H3 and H4)
# See Figure 4 in Bretz et al. (2011a).
alpha <- 0.025
hypotheses <- c(0.5, 0.5, 0, 0)
delta <- 0.5
transitions <- rbind(
  c(0, delta, 1 - delta, 0),
  c(delta, 0, 0, 1 - delta),
  c(0, 1, 0, 0),
  c(1, 0, 0, 0)
)
g <- graph_create(hypotheses, transitions)

marginal_power <- c(0.8, 0.8, 0.7, 0.9)
corr1 <- matrix(0.5, nrow = 2, ncol = 2)
diag(corr1) <- 1
corr <- rbind(
  cbind(corr1, 0.5 * corr1),
  cbind(0.5 * corr1, corr1)
)
success_fns <- list(
  # Probability to reject both H1 and H2
  `H1andH2` = function(x) x[1] & x[2],
  # Probability to reject both (H1 and H3) or (H2 and H4)
  `(H1andH3)or(H2andH4)` = function(x) (x[1] & x[3]) | (x[2] & x[4])
)
set.seed(1234)
# Bonferroni tests
# Reduce the number of simulations to save time for package compilation
power_output <- graph_calculate_power(
  g,
  alpha,
  sim_corr = corr,
  sim_n = 1e2,
  power_marginal = marginal_power,
  sim_success = success_fns
)

# Parametric tests for H1 and H2; Simes tests for H3 and H4
# User-defined success: to reject H1 or H2; to reject H1 and H2
# Reduce the number of simulations to save time for package compilation
graph_calculate_power(
  g,
  alpha,
  test_groups = list(1:2, 3:4),
  test_types = c("parametric", "simes"),
  test_corr = list(corr1, NA),
  sim_n = 1e2,
  sim_success = list(
    function(.) .[1] || .[2],
    function(.) .[1] && .[2]
  )
)

Create the initial graph for a multiple comparison procedure

Description

A graphical multiple comparison procedure is represented by 1) a vector of initial hypothesis weights hypotheses, and 2) a matrix of initial transition weights transitions. This function creates the initial graph object using hypothesis weights and transition weights.

Usage

graph_create(hypotheses, transitions, hyp_names = NULL)

Arguments

Value

An S3 object of class initial_graph with a list of 2 elements:

• Hypothesis weights hypotheses.

• Transition weights transitions.

Validation of inputs

Inputs are also validated to make sure of the validity of the graph:

• Hypothesis weights hypotheses are numeric.

• Transition weights transitions are numeric.

• Length of hypotheses and dimensions of transitions match.

• Hypothesis weights hypotheses must be non-negative and sum to no more than 1.

• Transition weights transitions:

  • Values must be non-negative.

  • Rows must sum to no more than 1.

  • Diagonal entries must be all 0.

• Hypothesis names hyp_names override names in hypotheses or transitions.

References

Bretz, F., Maurer, W., Brannath, W., and Posch, M. (2009). A graphical approach to sequentially rejective multiple test procedures. Statistics in Medicine, 28(4), 586-604.

Bretz, F., Posch, M., Glimm, E., Klinglmueller, F., Maurer, W., and Rohmeyer, K. (2011). Graphical approaches for multiple comparison procedures using weighted Bonferroni, Simes, or parametric tests. Biometrical Journal, 53(6), 894-913.

See Also

graph_update() for the updated graph after hypotheses being deleted from the initial graph.

Examples

# A graphical multiple comparison procedure with two primary hypotheses (H1
# and H2) and two secondary hypotheses (H3 and H4)
# See Figure 1 in Bretz et al. (2011).
hypotheses <- c(0.5, 0.5, 0, 0)
transitions <- rbind(
  c(0, 0, 1, 0),
  c(0, 0, 0, 1),
  c(0, 1, 0, 0),
  c(1, 0, 0, 0)
)
hyp_names <- c("H11", "H12", "H21", "H22")
g <- graph_create(hypotheses, transitions, hyp_names)
g

# Explicit names override names in `hypotheses` (with a warning)
hypotheses <- c(h1 = 0.5, h2 = 0.5, h3 = 0, h4 = 0)
transitions <- rbind(
  c(0, 0, 1, 0),
  c(0, 0, 0, 1),
  c(0, 1, 0, 0),
  c(1, 0, 0, 0)
)
g <- graph_create(hypotheses, transitions, hyp_names)
g

# Use names in `transitions`
hypotheses <- c(0.5, 0.5, 0, 0)
transitions <- rbind(
  H1 = c(0, 0, 1, 0),
  H2 = c(0, 0, 0, 1),
  H3 = c(0, 1, 0, 0),
  H4 = c(1, 0, 0, 0)
)
g <- graph_create(hypotheses, transitions)
g

# Unmatched names in `hypotheses` and `transitions` (with an error)
hypotheses <- c(h1 = 0.5, h2 = 0.5, h3 = 0, h4 = 0)
transitions <- rbind(
  H1 = c(0, 0, 1, 0),
  H2 = c(0, 0, 0, 1),
  H3 = c(0, 1, 0, 0),
  H4 = c(1, 0, 0, 0)
)
try(
  g <- graph_create(hypotheses, transitions)
)

# When names are not specified, hypotheses are numbered sequentially as
# H1, H2, ...
hypotheses <- c(0.5, 0.5, 0, 0)
transitions <- rbind(
  c(0, 0, 1, 0),
  c(0, 0, 0, 1),
  c(0, 1, 0, 0),
  c(1, 0, 0, 0)
)
g <- graph_create(hypotheses, transitions)
g

Generate the weighting strategy based on a graphical multiple comparison procedure

Description

A graphical multiple comparison procedure defines a closed test procedure, which tests each intersection hypothesis and reject an individual hypothesis if all intersection hypotheses involving it have been rejected. An intersection hypothesis represents the parameter space where individual null hypotheses involved are true simultaneously.

The closure based on a graph consists of all updated graphs (corresponding to intersection hypotheses) after all combinations of hypotheses are deleted. For a graphical multiple comparison procedure with m hypotheses, there are 2^{m}-1 updated graphs (intersection hypotheses), including the initial graph (the overall intersection hypothesis). The weighting strategy of this graph consists of hypothesis weights from all 2^{m}-1 updated graphs (intersection hypotheses). The algorithm to derive the weighting strategy is based on Algorithm 1 in Bretz et al. (2011).

Usage

graph_generate_weights(graph)

Arguments

Value

A numeric matrix of all intersection hypotheses and their hypothesis weights. For a graphical multiple comparison procedure with m hypotheses, the number of rows is 2^{m}-1, each of which corresponds to an intersection hypothesis. The number of columns is 2\cdot m. The first m columns indicate which individual hypotheses are included in a given intersection hypothesis and the second half of columns provide hypothesis weights for each individual hypothesis for a given intersection hypothesis.

Performance

Generation of intersection hypotheses is closely related to the power set of a given set of indices. As the number of hypotheses increases, the memory and time usage can grow quickly (e.g., at a rate of O(2^n)). There are also multiple ways to implement Algorithm 1 in Bretz et al. (2011). See vignette("generate-closure") for more information about generating intersection hypotheses and comparisons of different approaches to calculate weighting strategies.

References

Bretz, F., Posch, M., Glimm, E., Klinglmueller, F., Maurer, W., and Rohmeyer, K. (2011). Graphical approaches for multiple comparison procedures using weighted Bonferroni, Simes, or parametric tests. Biometrical Journal, 53(6), 894-913.

See Also

graph_test_closure() for graphical multiple comparison procedures using the closed test.

Examples

# A graphical multiple comparison procedure with two primary hypotheses (H1
# and H2) and two secondary hypotheses (H3 and H4)
# See Figure 1 in Bretz et al. (2011).
hypotheses <- c(0.5, 0.5, 0, 0)
transitions <- rbind(
  c(0, 0, 1, 0),
  c(0, 0, 0, 1),
  c(0, 1, 0, 0),
  c(1, 0, 0, 0)
)
g <- graph_create(hypotheses, transitions)

graph_generate_weights(g)

Find alternate rejection orderings (sequences) for shortcut tests

Description

When multiple hypotheses are rejected by using graph_test_shortcut(), there may be multiple orderings or sequences in which hypotheses are rejected one by one. The default order in graph_test_shortcut() is based on the adjusted p-values, from the smallest to the largest. This function graph_rejection_orderings() provides all possible and valid orders (or sequences) of rejections. Although the order of rejection does not affect the final rejection decisions Bretz et al. (2009), different sequences could offer different ways to explain the step-by-step process of shortcut graphical multiple comparison procedures.

Usage

graph_rejection_orderings(shortcut_test_result)

Arguments

Value

A modified graph_report object containing all valid orderings of rejections of hypotheses

References

Bretz, F., Maurer, W., Brannath, W., and Posch, M. (2009). A graphical approach to sequentially rejective multiple test procedures. Statistics in Medicine, 28(4), 586-604.

Bretz, F., Posch, M., Glimm, E., Klinglmueller, F., Maurer, W., and Rohmeyer, K. (2011). Graphical approaches for multiple comparison procedures using weighted Bonferroni, Simes, or parametric tests. Biometrical Journal, 53(6), 894-913.

See Also

graph_test_shortcut() for shortcut graphical multiple comparison procedures.

Examples

# A graphical multiple comparison procedure with two primary hypotheses (H1
# and H2) and two secondary hypotheses (H3 and H4)
# See Figure 4 in Bretz et al. (2011).
hypotheses <- c(0.5, 0.5, 0, 0)
delta <- 0.5
transitions <- rbind(
  c(0, delta, 1 - delta, 0),
  c(delta, 0, 0, 1 - delta),
  c(0, 1, 0, 0),
  c(1, 0, 0, 0)
)
g <- graph_create(hypotheses, transitions)

p <- c(0.018, 0.01, 0.105, 0.006)
alpha <- 0.025

shortcut_testing <- graph_test_shortcut(g, p, alpha, verbose = TRUE)

# Reject H1, H2, and H4
shortcut_testing$outputs$rejected

# Default order of rejections: H2, H1, H4
shortcut_testing$details$del_seq

# There is another valid sequence of rejection: H2, H4, H1
graph_rejection_orderings(shortcut_testing)$valid_orderings

# Finally, intermediate updated graphs can be obtained by providing the order
# of rejections into `[graph_update()]`
graph_update(g, delete = c(2, 4, 1))

Perform closed graphical multiple comparison procedures

Description

Closed graphical multiple comparison procedures, or graphical multiple comparison procedures based on the closure, generate the closure based on a graph consisting of all intersection hypotheses. It tests each intersection hypothesis and rejects an individual hypothesis if all intersection hypotheses involving it have been rejected. An intersection hypothesis represents the parameter space where individual null hypotheses involved are true simultaneously.

For a graphical multiple comparison procedure with $m$ hypotheses, there are 2^m-1 intersection hypotheses. For each intersection hypothesis, a test type could be chosen to determine how to reject the intersection hypothesis. Current choices of test types include Bonferroni, Simes and parametric. This implementation offers a more general framework covering Bretz et al. (2011), Lu (2016), and Xi et al. (2017). See vignette("closed-testing") for more illustration of closed test procedures and interpretation of their outputs.

Usage

graph_test_closure(
  graph,
  p,
  alpha = 0.025,
  test_groups = list(seq_along(graph$hypotheses)),
  test_types = c("bonferroni"),
  test_corr = rep(list(NA), length(test_types)),
  verbose = FALSE,
  test_values = FALSE
)

Arguments

Value

A graph_report object with a list of 4 elements:

• inputs - Input parameters, which is a list of:

  • graph - Initial graph,

  • p - (Unadjusted or raw) p-values,

  • alpha - Overall significance level,

  • test_groups - Groups of hypotheses for different types of tests,

  • test_types - Different types of tests,

  • test_corr - Correlation matrices for parametric tests.

• outputs - Output parameters, which is a list of:

  • adjusted_p - Adjusted p-values,

  • rejected - Rejected hypotheses,

  • graph - Updated graph after deleting all rejected hypotheses.

• details - Verbose outputs with adjusted p-values for intersection hypotheses, if verbose = TRUE.

• test_values - Adjusted significance levels, if test_values = TRUE.

Details for test specification

Test specification includes three components: test_groups, test_types, and test_corr. Alignment among entries in these components is important for correct implementation. There are two ways to provide test specification. The first approach is the "unnamed" approach, which assumes that all 3 components are ordered the same way, i.e., the $n$-th element of test_types and test_corr should apply to the $n$-th group in test_groups. The second "named" approach uses the name of each element of each component to connect the element of test_types and test_corr with the correct element of test_groups. Consistency should be ensured for correct implementation.

References

Bretz, F., Posch, M., Glimm, E., Klinglmueller, F., Maurer, W., and Rohmeyer, K. (2011). Graphical approaches for multiple comparison procedures using weighted Bonferroni, Simes, or parametric tests. Biometrical Journal, 53(6), 894-913.

Lu, K. (2016). Graphical approaches using a Bonferroni mixture of weighted Simes tests. Statistics in Medicine, 35(22), 4041-4055.

Xi, D., Glimm, E., Maurer, W., and Bretz, F. (2017). A unified framework for weighted parametric multiple test procedures. Biometrical Journal, 59(5), 918-931.

See Also

graph_test_shortcut() for shortcut graphical multiple comparison procedures.

Examples

# A graphical multiple comparison procedure with two primary hypotheses
# (H1 and H2) and two secondary hypotheses (H3 and H4)
# See Figure 4 in Bretz et al. (2011).
hypotheses <- c(0.5, 0.5, 0, 0)
delta <- 0.5
transitions <- rbind(
  c(0, delta, 1 - delta, 0),
  c(delta, 0, 0, 1 - delta),
  c(0, 1, 0, 0),
  c(1, 0, 0, 0)
)
g <- graph_create(hypotheses, transitions)

p <- c(0.018, 0.01, 0.105, 0.006)
alpha <- 0.025

# Closed graphical multiple comparison procedure using Bonferroni tests
# Same results as `graph_test_shortcut(g, p, alpha)`
graph_test_closure(g, p, alpha)

# Closed graphical multiple comparison procedure using parametric tests for
# H1 and H2, and Bonferroni tests for H3 and H4
set.seed(1234)
corr_list <- list(matrix(c(1, 0.5, 0.5, 1), nrow = 2), NA)
graph_test_closure(
  graph = g,
  p = p,
  alpha = alpha,
  test_groups = list(1:2, 3:4),
  test_types = c("parametric", "bonferroni"),
  test_corr = corr_list
)
# The "named" approach to obtain the same results
# Note that "group2" appears before "group1" in `test_groups`
set.seed(1234)
corr_list <- list(group1 = matrix(c(1, 0.5, 0.5, 1), nrow = 2), group2 = NA)
graph_test_closure(
  graph = g,
  p = p,
  alpha = alpha,
  test_groups = list(group1 = 1:2, group2 = 3:4),
  test_types = c(group2 = "bonferroni", group1 = "parametric"),
  test_corr = corr_list
)

# Closed graphical multiple comparison procedure using parametric tests for
# H1 and H2, and Simes tests for H3 and H4
set.seed(1234)
graph_test_closure(
  graph = g,
  p = p,
  alpha = alpha,
  test_groups = list(group1 = 1:2, group2 = 3:4),
  test_types = c(group1 = "parametric", group2 = "simes"),
  test_corr = corr_list
)

Perform graphical multiple comparison procedures efficiently for power calculation

Description

These functions performs similarly to graph_test_closure() or graph_test_shortcut() but are optimized for efficiently calculating power. For example, generating weights and calculating adjusted weights can be done only once. Vectorization has been applied where possible.

Usage

graph_test_closure_fast(p, alpha, adjusted_weights, matrix_intersections)

graph_test_shortcut_fast(p, alpha, adjusted_weights)

Arguments

Value

A logical or integer vector indicating whether each hypothesis can be rejected or not.

See Also

• graph_test_closure() for closed graphical multiple comparison procedures.

• graph_test_shortcut() for shortcut graphical multiple comparison procedures.

Perform shortcut (sequentially rejective) graphical multiple comparison procedures

Description

Shortcut graphical multiple comparison procedures are sequentially rejective procedure based on Bretz et al. (2009). With $m$ hypotheses, there are at most $m$ steps to obtain all rejection decisions. These procedure are equivalent to closed graphical multiple comparison procedures using Bonferroni tests for intersection hypotheses, but shortcut procedures are faster to perform. See vignette("shortcut-testing") for more illustration of shortcut procedures and interpretation of their outputs.

Usage

graph_test_shortcut(
  graph,
  p,
  alpha = 0.025,
  verbose = FALSE,
  test_values = FALSE
)

Arguments

Value

An S3 object of class graph_report with a list of 4 elements:

• inputs - Input parameters, which is a list of:

  • graph - Initial graph, *p - (Unadjusted or raw) p-values,

  • alpha - Overall significance level,

  • test_groups - Groups of hypotheses for different types of tests, which are the list of all hypotheses for graph_test_shortcut(),

  • test_types - Different types of tests, which are "bonferroni" for graph_test_shortcut().

• Output parameters outputs, which is a list of:

  • adjusted_p - Adjusted p-values,

  • rejected - Rejected hypotheses,

  • graph - Updated graph after deleting all rejected hypotheses.

• details - Verbose outputs with intermediate updated graphs, if verbose = TRUE.

• test_values - Adjusted significance levels, if test_values = TRUE.

References

Bretz, F., Maurer, W., Brannath, W., and Posch, M. (2009). A graphical approach to sequentially rejective multiple test procedures. Statistics in Medicine, 28(4), 586-604.

Bretz, F., Posch, M., Glimm, E., Klinglmueller, F., Maurer, W., and Rohmeyer, K. (2011). Graphical approaches for multiple comparison procedures using weighted Bonferroni, Simes, or parametric tests. Biometrical Journal, 53(6), 894-913.

See Also

• graph_test_closure() for graphical multiple comparison procedures using the closed test,

• graph_rejection_orderings() for all possible rejection orderings.

Examples

# A graphical multiple comparison procedure with two primary hypotheses (H1
# and H2) and two secondary hypotheses (H3 and H4)
# See Figure 1 in Bretz et al. (2011).
hypotheses <- c(0.5, 0.5, 0, 0)
transitions <- rbind(
  c(0, 0, 1, 0),
  c(0, 0, 0, 1),
  c(0, 1, 0, 0),
  c(1, 0, 0, 0)
)
g <- graph_create(hypotheses, transitions)

p <- c(0.018, 0.01, 0.105, 0.006)
alpha <- 0.025
graph_test_shortcut(g, p, alpha)

Perform shortcut graphical multiple comparison procedures with group sequential designs

Description

Extends graph_test_shortcut() to group sequential designs where hypotheses can be tested at multiple analyses (interim and final). At each analysis, the significance level available for each hypothesis is determined by a spending function evaluated at the information fraction. The group sequential boundaries (critical values) are computed from the spending using the joint distribution of test statistics across analyses.

The procedure supports two modes controlled by the look_back parameter:

• look_back = FALSE (default): At each analysis, rejection decisions are based on repeated p-values at the current analysis only. A repeated p-value at analysis k is the minimum significance level at which the group sequential boundary at analysis k would be crossed. The graphical shortcut procedure (graph_test_shortcut()) is applied at each analysis using repeated p-values, and the graph is updated before proceeding to the next analysis.

• look_back = TRUE: Rejection decisions are based on sequential p-values, which consider all analyses up to the current one. A sequential p-value is the minimum of repeated p-values across all analyses conducted so far. Like the default mode, the procedure processes analyses sequentially, applying graph_test_shortcut() at each analysis using sequential p-values and updating the graph before proceeding. When a hypothesis becomes testable at a later analysis (via graph update), its first_rejected_at is set to the earliest analysis where its boundary was crossed, while decision_at records the analysis where the rejection was operationally processed.

Usage

graph_test_shortcut_gsd(
  graph,
  p,
  alpha = 0.025,
  info_frac,
  spending_fn,
  look_back = FALSE,
  verbose = FALSE,
  test_values = FALSE
)

Arguments

Value

An S3 object of class gsd_graph_report with a list of elements:

• inputs - Input parameters, including the initial graph, p-values, alpha, information fractions, and spending functions.

• outputs - Output parameters:

  • repeated_p - An m x K matrix of repeated p-values at each analysis,

  • sequential_p - An m x K matrix of sequential p-values (cumulative minimum of repeated p-values),

  • adjusted_p - Adjusted p-values from the shortcut procedure (adjusted repeated p-values when look_back = FALSE, adjusted sequential p-values when look_back = TRUE),

  • rejected - Logical vector of rejection decisions,

  • decision_at - Integer vector indicating the analysis at which each hypothesis's decision was made. For rejected hypotheses, this is the analysis where the rejection was operationally processed. For non-rejected hypotheses, this is the last analysis where the hypothesis was tested,

  • first_rejected_at - Integer vector indicating the earliest analysis at which each hypothesis's boundary was crossed. For non-rejected hypotheses, this is NA. When look_back = TRUE, this may be earlier than decision_at if a hypothesis crossed its boundary at a prior analysis but only became testable at a later analysis,

  • last_rejected_at - Integer vector indicating the latest analysis at which each hypothesis's boundary was crossed. For non-rejected hypotheses, this is NA. Comparing first_rejected_at and last_rejected_at shows whether the rejection is supported by data at multiple analyses or only at a single analysis,

  • rejection_sequence - Character vector giving the order in which hypotheses were rejected across all analyses,

  • graph - Updated graph after removing all rejected hypotheses.

• test_values - Per-analysis details (if test_values = TRUE). A list of length K (one entry per analysis). Each entry is a data frame containing the hypothesis name, current weight, observed p-value, nominal boundary, and rejection decision at that analysis. Entries are NULL for analyses where no hypotheses are active. When look_back = TRUE and a hypothesis is rejected at an earlier analysis, additional rows show the nominal p-value and boundary at each prior analysis, with a Look_back column indicating these rows.

• boundary_table - Boundary lookup table (if verbose = TRUE). A named list with one data frame per hypothesis. Each data frame contains the columns Weight, Alpha.Allocated, and Boundary.k for each analysis k, showing the nominal p-value boundary at each analysis for every possible weight from the graph's closure. This table is independent of observed p-values and can be used to manually verify rejection decisions.

References

Maurer, W., and Bretz, F. (2013). Multiple testing in group sequential trials using graphical approaches. Statistics in Biopharmaceutical Research, 5(4), 311-320.

Zhao, Y., Liu, Q., Sun, L. Z., and Anderson, K. M. (2025). Adjusted inference for multiple testing procedure in group-sequential designs. Biometrical Journal, 67(1), e70020. doi:10.1002/bimj.70020

See Also

graph_test_shortcut() for the fixed-sample (non-sequential) shortcut procedure, sequential_p() for computing sequential p-values, repeated_p() for computing repeated p-values, spending_of(), spending_pocock(), spending_hsd(), spending_linear() for spending functions.

Examples

# A graphical procedure with two hypotheses tested at two analyses
hypotheses <- c(0.5, 0.5)
transitions <- rbind(c(0, 1), c(1, 0))
g <- graph_create(hypotheses, transitions)

# P-values at interim (50% info) and final (100% info) analyses
p <- rbind(
  H1 = c(0.024, 0.01),
  H2 = c(0.015, 0.005)
)

graph_test_shortcut_gsd(
  graph = g,
  p = p,
  alpha = 0.025,
  info_frac = c(0.5, 1),
  spending_fn = spending_of
)

# With look_back = TRUE (sequential p-values)
graph_test_shortcut_gsd(
  graph = g,
  p = p,
  alpha = 0.025,
  info_frac = c(0.5, 1),
  spending_fn = spending_of,
  look_back = TRUE
)

# Different spending functions per hypothesis
graph_test_shortcut_gsd(
  graph = g,
  p = p,
  alpha = 0.025,
  info_frac = c(0.5, 1),
  spending_fn = list(spending_of, spending_pocock)
)

# User-defined spending functions can also be used, e.g., wrapping
# gsDesign::sfHSD(). See vignette("group-sequential-testing") for details.

# Different information fractions per hypothesis
graph_test_shortcut_gsd(
  graph = g,
  p = p,
  alpha = 0.025,
  info_frac = rbind(c(0.5, 1), c(0.6, 1)),
  spending_fn = spending_of
)

# Different numbers of analyses per hypothesis (NA padding)
# H1 at analyses 1-2, H2 at 1-3, H3 at 2-3, H4 at 1 and 3
g4 <- graph_create(
  rep(0.25, 4),
  rbind(
    c(0, 1 / 3, 1 / 3, 1 / 3),
    c(1 / 3, 0, 1 / 3, 1 / 3),
    c(1 / 3, 1 / 3, 0, 1 / 3),
    c(1 / 3, 1 / 3, 1 / 3, 0)
  )
)
p4 <- rbind(
  H1 = c(0.024, 0.01, NA),
  H2 = c(0.015, 0.005, 0.001),
  H3 = c(NA, 0.012, 0.004),
  H4 = c(0.05, NA, 0.015)
)
# info_frac must be a matrix with NA matching p
info_frac4 <- rbind(
  H1 = c(0.5, 1, NA),
  H2 = c(1 / 3, 2 / 3, 1),
  H3 = c(NA, 0.5, 1),
  H4 = c(0.4, NA, 1)
)
graph_test_shortcut_gsd(
  graph = g4,
  p = p4,
  alpha = 0.025,
  info_frac = info_frac4,
  spending_fn = spending_of
)

Obtain an updated graph by updating an initial graphical after deleting hypotheses

Description

After a hypothesis is deleted, an initial graph will be updated. The deleted hypothesis will have the hypothesis weight of 0 and the transition weight of 0. Remaining hypotheses will have updated hypothesis weights and transition weights according to Algorithm 1 of Bretz et al. (2009).

Usage

graph_update(graph, delete)

Arguments

Value

An S3 object of class updated_graph with a list of 4 elements:

• initial_graph: The initial graph object.

• updated_graph: The updated graph object with specified hypotheses deleted.

• deleted: A numeric vector indicating which hypotheses were deleted.

• intermediate_graphs: When using the ordered mode, a list of intermediate updated graphs after each hypothesis is deleted according to the sequence specified by delete.

Sequence of deletion

When there are multiple hypotheses to be deleted from a graph, there are many sequences of deletion in which an initial graph is updated to an updated graph. If the interest is in the updated graph after all hypotheses specified by delete are deleted, this updated graph is the same no matter which sequence of deletion is used. This property has been proved by Bretz et al. (2009). If the interest is in the intermediate updated graph after each hypothesis is deleted according to the sequence specified by delete, an integer vector of delete should be specified and these detailed outputs will be provided.

References

Bretz, F., Maurer, W., Brannath, W., and Posch, M. (2009). A graphical approach to sequentially rejective multiple test procedures. Statistics in Medicine, 28(4), 586-604.

Bretz, F., Posch, M., Glimm, E., Klinglmueller, F., Maurer, W., and Rohmeyer, K. (2011). Graphical approaches for multiple comparison procedures using weighted Bonferroni, Simes, or parametric tests. Biometrical Journal, 53(6), 894-913.

See Also

• graph_create() for the initial graph.

• graph_rejection_orderings() for possible sequences of rejections for a graphical multiple comparison procedure using shortcut testing.

Examples

# A graphical multiple comparison procedure with two primary hypotheses (H1
# and H2) and two secondary hypotheses (H3 and H4)
# See Figure 1 in Bretz et al. (2011).
hypotheses <- c(0.5, 0.5, 0, 0)
transitions <- rbind(
  c(0, 0, 1, 0),
  c(0, 0, 0, 1),
  c(0, 1, 0, 0),
  c(1, 0, 0, 0)
)
g <- graph_create(hypotheses, transitions)

# Delete the second and third hypotheses in the "unordered mode"
graph_update(g, delete = c(FALSE, TRUE, TRUE, FALSE))

# Equivalent way in the "ordered mode" to obtain the updated graph after
# deleting the second and third hypotheses
# Additional intermediate updated graphs are also provided
graph_update(g, delete = 2:3)

Compute group sequential boundaries from an alpha spending function

Description

Given a significance level, information fractions, and a spending function, compute the group sequential boundaries at each analysis. The boundaries are computed on the Z-scale using the recursive relationship between cumulative spending and the joint distribution of test statistics. The null hypothesis is rejected at analysis k if the test statistic Z_k \ge b_k.

At analysis k, the Z-scale boundary b_k satisfies

P(Z_1 < b_1, \ldots, Z_k < b_k) = 1 - f(\alpha, t_k),

where f(\alpha, t_k) is the cumulative spending at information fraction t_k, and (Z_1, \ldots, Z_k) follows the canonical joint distribution with mean zero and correlations given by gs_corr().

Usage

gs_boundaries(alpha, info_frac, spending_fn, maxpts = 25000, abseps = 1e-06)

Arguments

Value

A list with elements:

• bounds_z - A numeric vector of Z-scale boundaries at each analysis.

• bounds_nominal - A numeric vector of nominal p-value boundaries at each analysis, i.e., c_k = 1 - \Phi(b_k).

See Also

spending_of(), spending_pocock(), spending_hsd(), spending_linear() for spending functions, sequential_p() for sequential p-values, graph_test_shortcut_gsd() for graphical MCPs with group sequential designs, gs_corr() for the correlation matrix.

Compute the correlation matrix for group sequential test statistics

Description

In a group sequential design, test statistics Z_1, \ldots, Z_K at analyses with information fractions t_1, \ldots, t_K follow the canonical joint distribution with correlation

\text{Cor}(Z_i, Z_j) = \sqrt{t_i / t_j}, \quad i \le j.

This correlation structure arises from the independent increments property of the score process. It depends only on the information fractions, not on the specific test or endpoint.

Usage

gs_corr(info_frac)

Arguments

Value

A symmetric correlation matrix of dimension K \times K, where K is the length of info_frac. The diagonal entries are all 1.

See Also

gs_boundaries() which uses this correlation matrix for computing group sequential boundaries.

Examples

# Three equally spaced analyses
gs_corr(c(1 / 3, 2 / 3, 1))

# Two analyses at 50% and 100%
gs_corr(c(0.5, 1))

Compute boundary table for all possible hypothesis weights

Description

For each hypothesis, enumerates all unique weights from the graph's closure (via graph_generate_weights()) and computes the group sequential boundaries at each analysis for each weight. This provides a lookup table for manual verification: given a hypothesis's weight (from graph propagation), the nominal boundary at each analysis can be read directly.

Usage

gsd_boundary_table(graph, alpha, info_frac, spending_fn, num_hyps, hyp_names)

Arguments

Value

A named list of data frames, one per hypothesis. Each data frame has columns: Weight, Alpha.Allocated, and one Boundary.k column per analysis, showing the nominal p-value boundary at each analysis for each possible weight.

Validate inputs for group sequential graphical MCP

Description

Validate inputs for group sequential graphical MCP

Usage

gsd_input_val(
  graph,
  p,
  alpha,
  info_frac,
  spending_fn,
  look_back,
  verbose,
  test_values
)

Arguments

Value

Invisibly returns graph.

Unified GSD procedure supporting per-hypothesis look_back

Description

Computes repeated and sequential p-values, then processes analyses sequentially. At each analysis k, applies graph_test_shortcut() using the appropriate p-values for each hypothesis: sequential p-values for hypotheses with look_back = TRUE, repeated p-values for those with look_back = FALSE. The graph is updated after each analysis before proceeding to the next.

Usage

gsd_test(
  graph,
  p,
  alpha,
  info_frac,
  spending_fn,
  look_back,
  num_analyses,
  num_hyps,
  hyp_names,
  analysis_names,
  test_values,
  verbose
)

Compute test_values for look_back = FALSE (analysis-by-analysis)

Description

For each analysis, computes the nominal boundaries and records the rejection sequence with boundaries at which rejections occurred. Walks through the rejection sequence within each analysis, updating the graph and recomputing boundaries after each rejection.

Usage

gsd_test_values_details(
  step_graph,
  p,
  k,
  alpha,
  info_frac,
  spending_fn,
  rejection_seq_k,
  hyp_names,
  rejected_after,
  has_data_k = rep(TRUE, length(hyp_names))
)

Compute look_back rows for test_values

Description

When a hypothesis is rejected via look_back at an earlier analysis than the operational analysis, this function generates rows showing the nominal p-value and boundary at each prior analysis (in decreasing order from the operational analysis down to the attributed analysis). The weight and boundaries are computed using the hypothesis's weight at the point of rejection. The Reject column indicates whether the nominal p-value crosses the boundary at each analysis.

Usage

gsd_test_values_look_back(
  hyp_name,
  k,
  attributed_to,
  alpha,
  p,
  info_frac,
  spending_fn,
  hyp_names,
  w_at_rejection
)

Arguments

Value

A data frame with look_back rows for analyses k-1, k-2, ..., attributed_to.

S3 plot method for class initial_graph

Description

The plot of an initial_graph translates the hypotheses into vertices and transitions into edges to create a network plot. Vertices are labeled with hypothesis names and hypothesis weights, and edges are labeled with transition weights. See vignette("graph-examples") for more illustration of commonly used multiple comparison procedure using graphs.

Usage

## S3 method for class 'initial_graph'
plot(
  x,
  ...,
  v_palette = c("#6baed6", "#cccccc"),
  layout = "grid",
  nrow = NULL,
  ncol = NULL,
  edge_curves = NULL,
  precision = 4,
  eps = NULL,
  background_color = "white",
  margins = c(1, 1, 1, 1)
)

Arguments

Value

An object x of class initial_graph, after plotting the initial graph.

Customization of graphs

There are a few values for igraph::plot.igraph() that get their defaults changed for graphicalMCP. These values can still be changed by passing them as arguments to plot.initial_graph(). Here are the new defaults:

• vertex.color = "#6baed6",

• vertex.label.color = "black",

• vertex.size = 20,

• edge.arrow.size = 1,

• edge.arrow.width = 1,

• edge.label.color = "black"

• asp = 0.

Neither graphicalMCP nor igraph does anything about overlapping edge labels. If you run into this problem, and vertices can't practically be moved enough to avoid collisions of edge labels, using edge curves can help. igraph puts edge labels closer to the tail of an edge when an edge is straight, and closer to the head of an edge when it's curved. By setting an edge's curve to some very small value, an effectively straight edge can be shifted to a new position.

References

Bretz, F., Posch, M., Glimm, E., Klinglmueller, F., Maurer, W., and Rohmeyer, K. (2011). Graphical approaches for multiple comparison procedures using weighted Bonferroni, Simes, or parametric tests. Biometrical Journal, 53(6), 894-913.

Xi, D., and Bretz, F. (2019). Symmetric graphs for equally weighted tests, with application to the Hochberg procedure. Statistics in Medicine, 38(27), 5268-5282.

See Also

plot.updated_graph() for the plot method for the updated graph after hypotheses being deleted from the initial graph.

Examples

# A graphical multiple comparison procedure with two primary hypotheses (H1
# and H2) and two secondary hypotheses (H3 and H4)
# See Figure 4 in Bretz et al. (2011).
hypotheses <- c(0.5, 0.5, 0, 0)
delta <- 0.5
transitions <- rbind(
  c(0, delta, 1 - delta, 0),
  c(delta, 0, 0, 1 - delta),
  c(0, 1, 0, 0),
  c(1, 0, 0, 0)
)
g <- graph_create(hypotheses, transitions)
plot(g)

# A graphical multiple comparison procedure with two primary hypotheses (H1
# and H2) and four secondary hypotheses (H31, H32, H41, and H42)
# See Figure 6 in Xi and Bretz (2019).
hypotheses <- c(0.5, 0.5, 0, 0, 0, 0)
epsilon <- 1e-5
transitions <- rbind(
  c(0, 0.5, 0.25, 0, 0.25, 0),
  c(0.5, 0, 0, 0.25, 0, 0.25),
  c(0, 0, 0, 0, 1, 0),
  c(epsilon, 0, 0, 0, 0, 1 - epsilon),
  c(0, epsilon, 1 - epsilon, 0, 0, 0),
  c(0, 0, 0, 1, 0, 0)
)
hyp_names <- c("H1", "H2", "H31", "H32", "H41", "H42")
g <- graph_create(hypotheses, transitions, hyp_names)

plot_layout <- rbind(
  c(0.15, 0.5),
  c(0.65, 0.5),
  c(0, 0),
  c(0.5, 0),
  c(0.3, 0),
  c(0.8, 0)
)

plot(g, layout = plot_layout, eps = epsilon, edge_curves = c(pairs = .5))

S3 plot method for the class updated_graph

Description

Plotting an updated graph is a very light wrapper around plot.initial_graph(), only changing the default vertex color to use gray for deleted hypotheses.

Usage

## S3 method for class 'updated_graph'
plot(x, ...)

Arguments

Value

An object x of class updated_graph, after plotting the updated graph.

References

Bretz, F., Posch, M., Glimm, E., Klinglmueller, F., Maurer, W., and Rohmeyer, K. (2011). Graphical approaches for multiple comparison procedures using weighted Bonferroni, Simes, or parametric tests. Biometrical Journal, 53(6), 894-913.

See Also

plot.initial_graph() for the plot method for the initial graph.

Examples

# A graphical multiple comparison procedure with two primary hypotheses (H1
# and H2) and two secondary hypotheses (H3 and H4)
# See Figure 1 in Bretz et al. (2011).
hypotheses <- c(0.5, 0.5, 0, 0)
transitions <- rbind(
  c(0, 0, 1, 0),
  c(0, 0, 0, 1),
  c(0, 1, 0, 0),
  c(1, 0, 0, 0)
)
g <- graph_create(hypotheses, transitions)

# Delete the second and third hypotheses in the "unordered mode"
plot(
  graph_update(
    g,
    c(FALSE, TRUE, TRUE, FALSE)
  ),
  layout = "grid"
)

S3 print method for the class graph_report

Description

A printed graph_report displays the initial graph, p-values and significance levels, rejection decisions, and optional detailed test results.

Usage

## S3 method for class 'graph_report'
print(x, ..., precision = 4, indent = 2, rows = 10)

Arguments

Value

An object x of class graph_report, after printing the report of conducting a graphical multiple comparison procedure.

References

Bretz, F., Posch, M., Glimm, E., Klinglmueller, F., Maurer, W., and Rohmeyer, K. (2011). Graphical approaches for multiple comparison procedures using weighted Bonferroni, Simes, or parametric tests. Biometrical Journal, 53(6), 894-913.

Examples

# A graphical multiple comparison procedure with two primary hypotheses (H1
# and H2) and two secondary hypotheses (H3 and H4)
# See Figure 1 in Bretz et al. (2011).
hypotheses <- c(0.5, 0.5, 0, 0)
transitions <- rbind(
  c(0, 0, 1, 0),
  c(0, 0, 0, 1),
  c(0, 1, 0, 0),
  c(1, 0, 0, 0)
)
g <- graph_create(hypotheses, transitions)

p <- c(0.018, 0.01, 0.105, 0.006)
alpha <- 0.025
graph_test_shortcut(g, p, alpha)

S3 print method for the class gsd_graph_report

Description

A printed gsd_graph_report displays:

• Test parameters: the initial graph, alpha, information fractions, p-values, spending functions, and per-hypothesis look_back settings.

• Test summary: adjusted p-values, rejection decisions, the analysis at which each decision was made (Decision.at), the earliest analysis at which the boundary was crossed (First.Rej.at), look_back status, and the rejection sequence.

• Per-analysis details (if test_values = TRUE): nominal p-values, boundaries, and rejection decisions at each analysis. For hypotheses rejected via look_back, additional rows show the boundary crossing at earlier analyses, marked with * and a footnote.

• Boundary table (if verbose = TRUE): nominal p-value boundaries for all possible hypothesis weights from the graph's closure, enabling manual verification of rejection decisions.

Usage

## S3 method for class 'gsd_graph_report'
print(x, ..., precision = 6, indent = 2)

Arguments

Value

An object x of class gsd_graph_report, invisibly.

References

Maurer, W., and Bretz, F. (2013). Multiple testing in group sequential trials using graphical approaches. Statistics in Biopharmaceutical Research, 5(4), 311-320.

Examples

hypotheses <- c(0.5, 0.5)
transitions <- rbind(c(0, 1), c(1, 0))
g <- graph_create(hypotheses, transitions)

p <- rbind(
  H1 = c(0.024, 0.01),
  H2 = c(0.015, 0.005)
)

graph_test_shortcut_gsd(
  graph = g,
  p = p,
  alpha = 0.025,
  info_frac = c(0.5, 1),
  spending_fn = spending_of
)

S3 print method for the class initial_graph

Description

A printed initial_graph displays a header stating "Initial graph", hypothesis weights, and transition weights.

Usage

## S3 method for class 'initial_graph'
print(x, ..., precision = 4, indent = 0)

Arguments

Value

An object x of class initial_graph, after printing the initial graph.

References

Bretz, F., Posch, M., Glimm, E., Klinglmueller, F., Maurer, W., and Rohmeyer, K. (2011). Graphical approaches for multiple comparison procedures using weighted Bonferroni, Simes, or parametric tests. Biometrical Journal, 53(6), 894-913.

See Also

print.updated_graph() for the print method for the updated graph after hypotheses being deleted from the initial graph.

Examples

# A graphical multiple comparison procedure with two primary hypotheses (H1
# and H2) and two secondary hypotheses (H3 and H4)
# See Figure 1 in Bretz et al. (2011).
hypotheses <- c(0.5, 0.5, 0, 0)
transitions <- rbind(
  c(0, 0, 1, 0),
  c(0, 0, 0, 1),
  c(0, 1, 0, 0),
  c(1, 0, 0, 0)
)
hyp_names <- c("H11", "H12", "H21", "H22")
g <- graph_create(hypotheses, transitions, hyp_names)
g

S3 print method for the class power_report

Description

A printed power_report displays the initial graph, testing and simulation options, power outputs, and optional detailed simulations and test results.

Usage

## S3 method for class 'power_report'
print(x, ..., precision = 4, indent = 2, rows = 10)

Arguments

Value

An object x of the class power_report, after printing the report of conducting power simulations based on a graphical multiple comparison procedure.

References

Bretz, F., Posch, M., Glimm, E., Klinglmueller, F., Maurer, W., and Rohmeyer, K. (2011a). Graphical approaches for multiple comparison procedures using weighted Bonferroni, Simes, or parametric tests. Biometrical Journal, 53(6), 894-913.

Bretz, F., Maurer, W., and Hommel, G. (2011b). Test and power considerations for multiple endpoint analyses using sequentially rejective graphical procedures. Statistics in Medicine, 30(13), 1489-1501.

Examples

# A graphical multiple comparison procedure with two primary hypotheses (H1
# and H2) and two secondary hypotheses (H3 and H4)
# See Figure 4 in Bretz et al. (2011).
alpha <- 0.025
hypotheses <- c(0.5, 0.5, 0, 0)
delta <- 0.5
transitions <- rbind(
  c(0, delta, 1 - delta, 0),
  c(delta, 0, 0, 1 - delta),
  c(0, 1, 0, 0),
  c(1, 0, 0, 0)
)
g <- graph_create(hypotheses, transitions)

marginal_power <- c(0.8, 0.8, 0.7, 0.9)
corr1 <- matrix(0.5, nrow = 2, ncol = 2)
diag(corr1) <- 1
corr <- rbind(
  cbind(corr1, 0.5 * corr1),
  cbind(0.5 * corr1, corr1)
)
success_fns <- list(
  # Probability to reject both H1 and H2
  `H1andH2` = function(x) x[1] & x[2],
  # Probability to reject both (H1 and H3) or (H2 and H4)
  `(H1andH3)or(H2andH4)` = function(x) (x[1] & x[3]) | (x[2] & x[4])
)
set.seed(1234)
# Bonferroni tests
# Reduce the number of simulations to save time for package compilation
power_output <- graph_calculate_power(
  g,
  alpha,
  sim_corr = corr,
  sim_n = 1e2,
  power_marginal = marginal_power,
  sim_success = success_fns
)

S3 print method for the class updated_graph

Description

A printed updated_graph displays the initial graph, the (final) updated graph, and the sequence of intermediate updated graphs after hypotheses are deleted (if available).

Usage

## S3 method for class 'updated_graph'
print(x, ..., precision = 6, indent = 2)

Arguments

Value

An object x of the class updated_graph, after printing the updated graph.

References

Bretz, F., Posch, M., Glimm, E., Klinglmueller, F., Maurer, W., and Rohmeyer, K. (2011a). Graphical approaches for multiple comparison procedures using weighted Bonferroni, Simes, or parametric tests. Biometrical Journal, 53(6), 894-913.

See Also

print.initial_graph() for the print method for the initial graph.

Examples

# A graphical multiple comparison procedure with two primary hypotheses (H1
# and H2) and two secondary hypotheses (H3 and H4)
# See Figure 1 in Bretz et al. (2011).
hypotheses <- c(0.5, 0.5, 0, 0)
transitions <- rbind(
  c(0, 0, 1, 0),
  c(0, 0, 0, 1),
  c(0, 1, 0, 0),
  c(1, 0, 0, 0)
)
g <- graph_create(hypotheses, transitions)

# Delete the second and third hypotheses in the "unordered mode"
graph_update(g, delete = c(FALSE, TRUE, TRUE, FALSE))

# Equivalent way in the "ordered mode" to obtain the updated graph after
# deleting the second and third hypotheses
# Additional intermediate updated graphs are also provided
graph_update(g, delete = 2:3)

Calculate the repeated p-value for a single hypothesis at a given analysis

Description

A repeated p-value at analysis k is the minimum significance level at which the group sequential boundary at analysis k would be crossed. Unlike the sequential p-value, which considers all analyses up to k, the repeated p-value only considers the boundary at analysis k itself.

The sequential p-value equals the minimum of repeated p-values across analyses: \tilde{p}_k = \min_{l=1}^{k} \hat{p}_l, where \hat{p}_l is the repeated p-value at analysis l.

Usage

repeated_p(
  p,
  info_frac,
  spending_fn,
  tol = 1e-06,
  maxpts = 25000,
  abseps = 1e-06
)

Arguments

Details

For a hypothesis tested at analyses k = 1, \ldots, K with p-values p^{(k)} and information fractions t^{(k)}, the repeated p-value at analysis K is the minimum \hat{p} such that the observed p-value p^{(K)} crosses the group sequential boundary c_K(\hat{p}) at that analysis:

\hat{p}_K = \min\{\alpha : p^{(K)} \le c_K(\alpha)\}.

Note that computing the boundary c_K(\alpha) requires knowledge of all previous information fractions t^{(1)}, \ldots, t^{(K)} because the boundary at analysis K depends on the cumulative spending and the joint distribution of test statistics.

The repeated p-value is found using stats::uniroot() on the function g(\alpha) = z_K - b_K(\alpha), where z_K = \Phi^{-1}(1 - p^{(K)}) is the observed Z-statistic at analysis K and b_K(\alpha) is the Z-scale boundary.

Value

A numeric scalar of the repeated p-value at the last analysis in the input vectors.

References

Maurer, W., and Bretz, F. (2013). Multiple testing in group sequential trials using graphical approaches. Statistics in Biopharmaceutical Research, 5(4), 311-320.

See Also

sequential_p() for the sequential p-value (minimum repeated p-value), gs_boundaries() for computing group sequential boundaries, graph_test_shortcut_gsd() for graphical multiple comparison procedures with group sequential designs.

Examples

# Repeated p-value at the second analysis (interim at 50%, final at 100%)
repeated_p(
  p = c(0.024, 0.01),
  info_frac = c(0.5, 1),
  spending_fn = spending_of
)

# Compare with sequential p-value (which is the minimum repeated p-value)
sequential_p(
  p = c(0.024, 0.01),
  info_frac = c(0.5, 1),
  spending_fn = spending_of
)

# Repeated p-values at each analysis
# Analysis 1
repeated_p(
  p = 0.05,
  info_frac = 0.3,
  spending_fn = spending_of
)

# Analysis 2
repeated_p(
  p = c(0.05, 0.02),
  info_frac = c(0.3, 0.7),
  spending_fn = spending_of
)

Calculate the sequential p-value for a single hypothesis

Description

A sequential p-value is the minimum significance level at which a group sequential boundary would be crossed at any analysis up to and including the current one. It is computed using the group sequential boundaries derived from the spending function and the joint distribution of test statistics across analyses.

Sequential p-values are used in graphical multiple comparison procedures for group sequential designs. They allow the separation of the group sequential testing (handled by the spending function and boundaries) from the multiplicity adjustment (handled by the graph). See Maurer and Bretz (2013) for details.

Usage

sequential_p(
  p,
  info_frac,
  spending_fn,
  tol = 1e-06,
  maxpts = 25000,
  abseps = 1e-06
)

Arguments

Details

For a hypothesis tested at analyses k = 1, \ldots, K with p-values p^{(k)} and information fractions t^{(k)}, the sequential p-value is the minimum \tilde{p} such that for some analysis k, the observed p-value p^{(k)} crosses the group sequential boundary c_k(\tilde{p}) derived from the spending function:

\tilde{p} = \min\{\alpha : p^{(k)} \le c_k(\alpha) \text{ for some } k\},

where c_k(\alpha) is the nominal p-value boundary at analysis k when the total significance level is \alpha.

The boundary c_k(\alpha) is computed from the spending function f(\alpha, t) using the joint distribution of test statistics. Specifically, the Z-scale boundary b_k satisfies

P(Z_1 < b_1, \ldots, Z_k < b_k) = 1 - f(\alpha, t_k),

and c_k = 1 - \Phi(b_k). Note that c_k \neq f(\alpha, t_k) - f(\alpha, t_{k-1}) for k > 1 due to the correlation between test statistics across analyses.

The sequential p-value is found using stats::uniroot() on the function g(\alpha) = \max_k (z_k - b_k(\alpha)), where z_k = \Phi^{-1}(1 - p^{(k)}) is the observed Z-statistic and b_k(\alpha) is the Z-scale boundary. This function is monotonically increasing in \alpha since boundaries become less stringent as \alpha increases.

Value

A numeric scalar of the sequential p-value.

References

Maurer, W., and Bretz, F. (2013). Multiple testing in group sequential trials using graphical approaches. Statistics in Biopharmaceutical Research, 5(4), 311-320.

Liu, Q., and Anderson, K. M. (2008). On adaptive extensions of group sequential trials for clinical investigations. Journal of the American Statistical Association, 103(484), 1621-1630.

See Also

gs_boundaries() for computing group sequential boundaries, graph_test_shortcut_gsd() for graphical multiple comparison procedures with group sequential designs, spending_of(), spending_pocock(), spending_hsd(), spending_linear() for spending functions.

Examples

# A hypothesis tested at two analyses (interim at 50% and final at 100%)
sequential_p(
  p = c(0.024, 0.01),
  info_frac = c(0.5, 1),
  spending_fn = spending_of
)

# Sequential p-value with Pocock spending
sequential_p(
  p = c(0.024, 0.01),
  info_frac = c(0.5, 1),
  spending_fn = spending_pocock
)

# Sequential p-value updates as more analyses are conducted
# After analysis 1 only
sequential_p(
  p = 0.05,
  info_frac = 0.3,
  spending_fn = spending_of
)

# After analyses 1 and 2
sequential_p(
  p = c(0.05, 0.02),
  info_frac = c(0.3, 0.7),
  spending_fn = spending_of
)

# After all three analyses
sequential_p(
  p = c(0.05, 0.02, 0.01),
  info_frac = c(0.3, 0.7, 1),
  spending_fn = spending_of
)

Alpha spending functions for group sequential designs

Description

Alpha spending functions determine how the total significance level (alpha) is allocated across interim and final analyses in a group sequential design. Given the total alpha and the information fraction(s) at one or more analyses, a spending function returns the cumulative alpha spent at each information fraction.

Four commonly used spending functions are provided:

• spending_of() for the Lan-DeMets O'Brien-Fleming approximation,

• spending_pocock() for the Lan-DeMets Pocock approximation,

• spending_hsd() for the Hwang-Shih-DeCani family,

• spending_linear() for linear (uniform) spending.

Usage

spending_of(alpha, info_frac)

spending_pocock(alpha, info_frac)

spending_hsd(alpha, info_frac, gamma = -4)

spending_linear(alpha, info_frac)

Arguments

Details

All spending functions satisfy the following properties:

• f(\alpha, 0) = 0,

• f(\alpha, 1) = \alpha,

• f(\alpha, t) is non-decreasing in t.

The cumulative alpha spent at analysis k is f(\alpha, t_k), and the incremental spending is

\Delta\alpha_k = f(\alpha, t_k) - f(\alpha, t_{k-1}).

Note that the incremental spending is not the nominal significance level (boundary) at analysis k. The boundary must be derived from the spending using the joint distribution of test statistics across analyses. See sequential_p() and graph_test_shortcut_gsd() for details.

Value

A numeric vector the same length as info_frac of cumulative alpha spent at each information fraction.

Spending function formulas

• O'Brien-Fleming (spending_of):

  f(\alpha, t) = 2\left(1 - \Phi\left(\frac{\Phi^{-1}(1 - \alpha/2)} {\sqrt{t}}\right)\right).

  This is the Lan-DeMets approximation to O'Brien-Fleming boundaries. It is very conservative at early analyses and spends most of the alpha at the final analysis.

• Pocock (spending_pocock):

  f(\alpha, t) = \alpha \cdot \ln(1 + (e - 1) \cdot t).

  This spends alpha more evenly across analyses compared to O'Brien-Fleming.

• Hwang-Shih-DeCani (spending_hsd):

  f(\alpha, t) = \alpha \cdot \frac{1 - e^{-\gamma t}}{1 - e^{-\gamma}}, \quad \gamma \neq 0,

  f(\alpha, t) = \alpha \cdot t, \quad \gamma = 0.

  With gamma = -4, it approximates O'Brien-Fleming; with gamma = 1, it approximates Pocock.

• Linear (spending_linear):

  f(\alpha, t) = \alpha \cdot t.

References

Lan, K. K. G., and DeMets, D. L. (1983). Discrete sequential boundaries for clinical trials. Biometrika, 70(3), 659-663.

Hwang, I. K., Shih, W. J., and De Cani, J. S. (1990). Group sequential designs using a family of type I error probability spending functions. Statistics in Medicine, 9(12), 1439-1445.

Examples

# O'Brien-Fleming spending at 50% information
spending_of(0.025, 0.5)

# Cumulative spending across analyses (vectorized)
spending_of(0.025, c(0, 0.5, 1))

# Compare spending functions at information fractions (1/3, 2/3, 1)
spending_of(0.025, c(1 / 3, 2 / 3, 1))
spending_pocock(0.025, c(1 / 3, 2 / 3, 1))
spending_hsd(0.025, c(1 / 3, 2 / 3, 1), gamma = -4)
spending_linear(0.025, c(1 / 3, 2 / 3, 1))

# User-defined spending function: piecewise combination.
# Use O'Brien-Fleming for the first half of alpha (conservative at
# early analyses), and Pocock for the second half (more aggressive).
# This can be useful when a hypothesis starts with a small weight
# (OBF spending) and later receives additional weight via graph
# propagation (Pocock spending for the increment).
spending_piecewise <- function(alpha, info_frac, threshold = 0.0125) {
  spending_of(pmin(alpha, threshold), info_frac) +
    spending_pocock(pmax(alpha - threshold, 0), info_frac)
}
spending_piecewise(0.025, c(1 / 3, 2 / 3, 1))
# Compare: alpha = 0.0125 uses only OBF
spending_piecewise(0.0125, c(1 / 3, 2 / 3, 1))
spending_of(0.0125, c(1 / 3, 2 / 3, 1))
# Pocock spending at 50% information
spending_pocock(0.025, 0.5)
# Hwang-Shih-DeCani spending at 50% information
spending_hsd(0.025, 0.5, gamma = -4)
spending_hsd(0.025, 0.5, gamma = 1)
spending_hsd(0.025, 0.5, gamma = 0)
# Linear spending at 50% information
spending_linear(0.025, 0.5)

Create a spending function with a custom spending time

Description

Wraps an existing spending function to use a fixed spending time instead of the information fractions passed to it at runtime. This controls only the alpha allocation schedule. The correlation structure of the test statistics is determined separately by the info_frac argument in graph_test_shortcut_gsd() (via gs_corr()), not by the spending function.

This is useful in two common scenarios:

• Subgroup analyses: all-subjects hypotheses use subgroup event fractions as spending time (controlling how alpha is allocated across analyses), while info_frac in graph_test_shortcut_gsd() uses all-subjects event fractions (controlling the correlation structure).

• Monitoring with changed final information: when the actual total information at the final analysis differs from the planned total, the planned information fractions are used as spending time to preserve the alpha allocation at earlier analyses, while info_frac in graph_test_shortcut_gsd() uses the actual information fractions for the correlation structure.

Usage

spending_with_time(spending_fn, spending_time, info_frac = NULL)

Arguments

Value

A function with the same signature as spending_fn — ⁠function(alpha, info_frac)⁠ — that internally uses spending_time instead of info_frac for alpha allocation.

See Also

spending_of(), spending_pocock(), spending_hsd(), spending_linear() for built-in spending functions, graph_test_shortcut_gsd() for the graphical procedure with group sequential designs.

Examples

# --- Subgroup spending time ---
# Without spending_with_time, spending_of() uses info_frac for spending:
info_frac_all <- c(529 / 800, 700 / 800, 1) # all-subjects fractions
spending_of(0.01, info_frac_all)

# With spending_with_time, spending uses subgroup fractions instead.
# The info_frac passed at runtime is ignored by the spending function;
# it is only used by gs_boundaries()/graph_test_shortcut_gsd() for
# the correlation structure.
spending_time_sub <- c(185 / 295, 245 / 295, 1) # subgroup fractions
spending_with_time(spending_of, spending_time_sub)

# --- Monitoring with changed final information ---
# Planned: 295 OS events at 3 analyses (185, 245, 295 events).
# spending_time uses planned fractions for interim analyses and 1
# for the final analysis.
spending_monitor <- spending_with_time(
  spending_of,
  spending_time = c(185 / 295, 245 / 295, 1)
)

# Overrunning (310 events) or underrunning (280 events):
# spending_time is the same in both cases — it uses planned fractions
# for interim analyses and 1 for the final analysis, because alpha
# spent has been fixed for interim analyses. The actual info_frac
# (which differs between overrunning and underrunning) only affects
# the correlation structure in gs_boundaries()/graph_test_shortcut_gsd().
spending_monitor(0.01, c(185 / 295, 245 / 295, 1))

# --- Skipped analyses (NA in spending_time) ---
# If a hypothesis is not tested at analysis 2, both spending_time and
# info_frac have NA at that position. The output also has NA there.
spending_skip <- spending_with_time(
  spending_of,
  spending_time = c(185 / 295, NA, 1),
  info_frac = c(185 / 295, NA, 1)
)
spending_skip(0.01, c(185 / 295, NA, 1))

Wang-Tsiatis spending function

Description

Computes the implied cumulative alpha spending from the Wang-Tsiatis family of group sequential boundaries. The Wang-Tsiatis boundaries at analysis k with information fraction t_k are defined as:

c_k = C \cdot t_k^{\Delta - 0.5},

where \Delta is the shape parameter and C is a constant calibrated so that the overall Type I error equals \alpha.

Special cases:

• \Delta = 0.5: Pocock boundaries (equal Z-scale boundaries across analyses).

• \Delta = 0: O'Brien-Fleming boundaries (very conservative at early analyses).

• 0 < \Delta < 0.5: intermediate between O'Brien-Fleming and Pocock.

Unlike the Lan-DeMets approximations (spending_of(), spending_pocock()), this function computes the exact boundaries from the Wang-Tsiatis family and derives the implied spending. It is computationally more expensive because it requires root-finding and multivariate normal integration at each call.

Usage

spending_wt(alpha, info_frac, delta = 0.5, maxpts = 25000, abseps = 1e-06)

Arguments

Value

A numeric vector the same length as info_frac of cumulative alpha spent at each information fraction.

References

Wang, S. K., and Tsiatis, A. A. (1987). Approximately optimal one-parameter boundaries for group sequential trials. Biometrics, 43(1), 193-199.

See Also

spending_of() and spending_pocock() for the Lan-DeMets approximations, gs_boundaries() for computing boundaries from spending functions, graph_test_shortcut_gsd() for the graphical procedure.

Examples

# Exact O'Brien-Fleming (delta = 0)
spending_wt(0.025, c(0.5, 1), delta = 0)

# Exact Pocock (delta = 0.5)
spending_wt(0.025, c(0.5, 1), delta = 0.5)

# Intermediate (delta = 0.25)
spending_wt(0.025, c(1 / 3, 2 / 3, 1), delta = 0.25)

# Compare with Lan-DeMets approximations
spending_of(0.025, c(1 / 3, 2 / 3, 1)) # Lan-DeMets OBF approximation
spending_wt(0.025, c(1 / 3, 2 / 3, 1), 0) # Exact OBF

# Use in graph_test_shortcut_gsd (wrap to fix delta)

g <- graph_create(c(0.5, 0.5), rbind(c(0, 1), c(1, 0)))
p <- rbind(H1 = c(0.024, 0.01), H2 = c(0.015, 0.005))
graph_test_shortcut_gsd(
  graph = g, p = p, alpha = 0.025,
  info_frac = c(0.5, 1),
  spending_fn = function(a, t) spending_wt(a, t, delta = 0.25)
)

Validate inputs for testing and power simulations

Description

Validate inputs for testing and power simulations

Usage

test_input_val(
  graph,
  p,
  alpha,
  test_groups = list(seq_along(graph$hypotheses)),
  test_types = c("bonferroni"),
  test_corr,
  verbose,
  test_values
)

power_input_val(graph, sim_n, power_marginal, test_corr, success)

Arguments

Value

Returns graph invisibly

Organize outputs for testing an intersection hypothesis

Description

An intersection hypothesis can be tested by a mixture of test types including Bonferroni, parametric and Simes tests. This function organize outputs of testing and prepare them for graph_report.

Usage

test_values_bonferroni(p, hypotheses, alpha, intersection = NA)

test_values_parametric(p, hypotheses, alpha, intersection = NA, test_corr)

test_values_simes(p, hypotheses, alpha, intersection = NA)

test_values_hochberg(p, hypotheses, alpha, intersection = NA)

Arguments

Value

A data frame with rows corresponding to individual hypotheses involved in the intersection hypothesis with hypothesis weights hypotheses. There are following columns:

• Intersection - Name of this intersection hypothesis,

• Hypothesis - Name of an individual hypothesis,

• Test - Test type for an individual hypothesis,

• p - (Unadjusted or raw) p-values for a individual hypothesis,

• c_value- C value for parametric tests,

• Weight - Hypothesis weight for an individual hypothesis,

• Alpha - Overall significance level \alpha,

• Inequality_holds - Indicator to show if the p-value is less than or equal to its significance level.

  • For Bonferroni and Simes tests, the significance level is the hypothesis weight times \alpha.

  • For parametric tests, the significance level is the c value times the hypothesis weight times \alpha.

References

Bretz, F., Maurer, W., Brannath, W., and Posch, M. (2009). A graphical approach to sequentially rejective multiple test procedures. Statistics in Medicine, 28(4), 586-604.

Lu, K. (2016). Graphical approaches using a Bonferroni mixture of weighted Simes tests. Statistics in Medicine, 35(22), 4041-4055.

Xi, D., Glimm, E., Maurer, W., and Bretz, F. (2017). A unified framework for weighted parametric multiple test procedures. Biometrical Journal, 59(5), 918-931.