Skip to contents

Optimise graph-based multiple testing procedures

Source: R/optimisation.R
graph_optimisation.Rd

Optimise the hypothesis weights and transition matrix of a graph-based multiple testing procedure using nloptr::nloptr() local optimisation and, optionally, a genetic algorithm using GA::ga() for global optimisation.

Usage

graph_optimise(
  pvals,
  graph_constraint,
  trial_success,
  ...,
  alpha = 0.025,
  start_graph = list(list(hyp_weight = NULL, trans_matrix = NULL)),
  global_search = TRUE,
  num_threads = 1L,
  control = multigrain_control(),
  verbose = multigrain_verbosity()
)

graph_optimize(
  pvals,
  graph_constraint,
  trial_success,
  ...,
  alpha = 0.025,
  start_graph = list(list(hyp_weight = NULL, trans_matrix = NULL)),
  global_search = TRUE,
  num_threads = 1L,
  control = multigrain_control(),
  verbose = multigrain_verbosity()
)

Arguments

pvals

A numeric matrix of p-values. Each row represents a simulated trial, and each column corresponds to a hypothesis.

graph_constraint

A multigrain_graph_constraint object containing constraints on the graph's weights and transition matrix. Created with graph_constraint().

trial_success

A multigrain_trial_success object defining the trial success measure (power objective) function to maximize. Created with trial_success().

...

These dots are for future extensions and must be empty.

alpha

A single numeric value representing the overall one-sided significance level. Default is 0.025.

start_graph

Optional. Initial list of graphs suggested. Each graph is defined as a list containing starting weight vector hyp_weight and transition matrix trans_matrix. If NULL, default starting values are generated (currently with a Bonferroni-Holm graph).

A logical indicating whether to perform a global optimisation before the local optimisation. Defaults to TRUE.

num_threads

Number of threads to use for parallel execution of the shortcut algorithm. On shared systems (HPC clusters, login nodes), always explicitly set num_threads based on your resource allocation. Default is 1L (serial execution).

control

An optional multigrain_control object can be used to set various graph optimisation parameters. Created with multigrain_control().

verbose

An optional string controlling verbosity ("detail" > "info" > "silent"). Verbosity can also be set at package level with the multigrain_verbosity option (see multigrain_verbosity()):

  • "info" (default): will only show milestones / informational messages highlighting the progress of the optimisation at coarse-grained level.

  • "detail": will show milestones and information about fine-grained optimisation events.

  • "silent": no information about the progress of the optimisation is printed to the console. Errors and warnings are still thrown normally.

Value

A multigrain_graph_optimal object containing:

  • hyp_weight: Optimised hypothesis weights (numeric vector).

  • trans_matrix: Optimised transition matrix (numeric matrix).

  • constraints: List of constraints used in the optimisation for weights and transition matrix.

  • trial_success: The trial success function used in the optimisation.

  • power: Power metrics for the optimised graph.

  • solution: A list containing:

    • opt_source: Source of the optimal solution (local or global).

    • graph_valid: Named logical vector indicating validity of the local and global solutions (c("local" = TRUE/FALSE, "global" = TRUE/FALSE)).

  • global_search: TRUE or FALSE indicating whether a global optimisation was performed.

  • control: The modified multigrain_control object used. Values passed on by the user are complemented with contextual defaults.

  • global_output: Output from the genetic algorithm if global optimisation was performed.

  • local_output: Output from the NLOPT optimisation.

  • start_graph: Initial starting values used in the optimisation.

Details

The output is a graph where a specified objective function - the trial success measure - is maximised under given constraints on the graph structure, conditional on a p-value distribution supplied.

References

Spiers, A. D. V., Grayling, M. J., Wheeler, G. M., and Mander, A. P. (2026). Gain-function optimisation of graphical multiple testing procedures for confirmatory clinical trials. arXiv:2609.19994v1. https://arxiv.org/abs/2609.19994

Examples


# Generate test data
pvals <- simulate_pvalues(
  power_nominal = c(0.9, 0.85, 0.8, 0.75),
  corr_matrix = diag(4),
  nsim = 5000
)

# Create trial success function
ts <- trial_success(r1 + r2 + r3 + r4)
#> ✔ Trial success function compiled and sourced successfully.

# \donttest{
# Optimise graph
result <- graph_optimise(
  pvals = pvals,
  graph_constraint = graph_constraint_free(4),
  trial_success = ts,
  num_threads = 2
)
#> ℹ Running global optimization
#> ✔ Running global optimization [26.8s]
#> 
#> ℹ Evaluating trial success of globally optimised graph
#> ✔ Evaluating trial success of globally optimised graph [15ms]
#> 
#> ℹ Running local optimization
#> ✔ Running local optimization [92ms]
#> 
#> ℹ Evaluating trial success of locally optimised graph
#> ✔ Evaluating trial success of locally optimised graph [15ms]
#> 
#> ℹ Pruning redundant weights and edges
#> ✔ Pruning redundant weights and edges [19ms]
#> 
#> ℹ Evaluating trial success of pruned graph
#> ✔ Evaluating trial success of pruned graph [7ms]
#> 
# }