Skip to contents

Three-Stage Significance Testing Pipeline for Hyperedges

Source: R/three_step_testing.R
sig_multiplet_testing_pipeline.Rd

Performs the full inferential validation procedure for candidate hyperedges following Possenti et al. (2026).

Usage

sig_multiplet_testing_pipeline(
  data,
  multiplets,
  n_perm = 1000,
  n_boot = 1000,
  alpha_perm = 0.05,
  alpha_boot = 0.05,
  Oinfo_threshold = 0.01,
  correct_method = c("fdr", "holm"),
  cor_method = c("pearson", "polychoric"),
  parallel = TRUE,
  n_cores = 1
)

Arguments

data

Preprocessed numeric data frame.

multiplets

List of candidate variable subsets.

n_perm

Number of permutations.

n_boot

Number of bootstrap samples.

alpha_perm

Significance threshold after multiple testing correction.

alpha_boot

Significance level for BCa confidence intervals. The confidence level is 1 - alpha_boot.

Oinfo_threshold

Minimum absolute O-information required for bootstrap evaluation.

correct_method

Multiple-testing correction method.

cor_method

Correlation estimation method.

parallel

Logical indicating whether parallel processing should be used.

n_cores

Number of worker processes.

Value

A data frame containing:

hyperedge_id

Hyperedge identifier.

vars

Variables composing the hyperedge.

k

Hyperedge order.

Oinfo

Observed O-information.

perm_p

Raw permutation p-value.

perm_p_adj

Adjusted p-value.

boot_ci_lower

Lower BCa confidence limit.

boot_ci_upper

Upper BCa confidence limit.

boot_robust

Bootstrap robustness indicator.

hierarchical_valid

Hierarchical validation result.

significant

Final significance indicator.

The hierarchical_subset_results attribute stores cached intervals used for hierarchical comparison, including supplementary subset intervals.

Details

The pipeline consists of three sequential stages:

  1. Permutation testing against a null model (permutation_Oinfo);

  2. BCa bootstrap robustness assessment (bootstrap_Oinfo);

  3. Hierarchical validation against nested lower-order subsets (hierarchical_validation).

Only hyperedges passing all three stages are retained as statistically significant higher-order interactions.

This function implements a three-stage validation framework described by Possenti et al. (2026) for psychometric hypergraph construction.

Candidate hyperedges are first screened against a permutation-based null model. Surviving candidates are then subjected to bootstrap robustness assessment. Finally, hierarchical validation removes higher-order interactions whose effects can be explained by nested lower-order subsets. Required subset intervals are cached or computed even if the subsets were not candidates or did not pass permutation testing. These comparisons do not add candidates to the permutation-testing family. Missing or invalid intervals prevent hierarchical validation.

With parallel = FALSE, testing is sequential. Otherwise, n_cores controls the multisession workers. The previous future plan is restored on exit, including on error.

The resulting significant hyperedges constitute the final hypergraph structure.

References

Marinazzo, D., Van Roozendaal, J., Rosas, F. E., Stella, M., Comolatti, R., Colenbier, N., Stramaglia, S., & Rosseel, Y. (2024). An information-theoretic approach to build hypergraphs in psychometrics. Behavior Research Methods, 56(7), 8057-8079.

Possenti, F., Girelli, L., Tieri, P., & Petti, M. (2026). Multiplex Hypergraph Modeling of Higher Order Structures in Psychometric Networks (Version 1). arXiv. https://doi.org/10.48550/ARXIV.2604.22744

See also

permutation_Oinfo, bootstrap_Oinfo, hierarchical_validation