Build Information-Theoretic Psychometric Hypergraph — build

Constructs psychometric hypergraphs based on higher-order statistical dependencies quantified by O-information. The function implements a complete analysis pipeline inspired by Marinazzo et al. (2024) and extended by Possenti et al. (2026), including:

Usage

build_hypergraph(
  data,
  cor_method = c("pearson", "polychoric"),
  k = 3,
  candidate_method = c("full", "clique", "possenti", "user"),
  user_multiplets = NULL,
  ebic.gamma = 0.5,
  min_clique_size = 2,
  n_perm = 1000,
  alpha_perm = 0.05,
  Oinfo_threshold = 0.01,
  n_boot = 1000,
  alpha_boot = 0.05,
  correct_method = c("fdr", "holm"),
  handle_na = c("impute", "omit"),
  impute_fun = stats::median,
  seed = 123,
  parallel = TRUE,
  n_cores = 1,
  transform = c("auto", "rank", "none")
)

Arguments

data

A data frame or matrix containing psychometric observations. Rows correspond to subjects and columns correspond to numeric variables/items.

cor_method

Correlation estimation method.

"pearson": Pearson correlation matrix.
"polychoric": Polychoric correlation matrix for ordinal variables.

k

Integer vector specifying hyperedge orders to evaluate. For example, k = 3:5 evaluates all candidate triplets, quadruplets, and quintuplets.

candidate_method

Method used to generate candidate multiplets.

"full": Exhaustive search over all possible combinations (Marinazzo et al., 2024). See generate_all_multiplets.
"clique": Generate candidates from maximal cliques identified in an EBICglasso network. See generate_candidate_multiplets.
"possenti": Topology-guided candidate generation strategy inspired by Possenti et al. (2026). See generate_candidate_multiplets_possenti.
"user": Use only the multiplets supplied in user_multiplets.

user_multiplets

Optional list of user-defined multiplets. Each element should contain integer node indices or variable names, without repeated nodes, and its order must be included in k. Variable names must match unique analysis column names. Multiplets are added to automatically generated candidates unless candidate_method = "user", which requires a non-empty list and replaces automatic candidate generation.

ebic.gamma

EBIC tuning parameter used when estimating pairwise networks using EBICglasso.

min_clique_size

Minimum clique size retained during clique-based candidate generation.

n_perm

Number of permutations used in significance testing.

alpha_perm

Significance threshold after multiple-testing correction.

Oinfo_threshold

Minimum absolute O-information value required before a hyperedge can be considered significant.

n_boot

Number of bootstrap samples used for robustness assessment.

alpha_boot

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

correct_method

Multiple-testing correction method. One of "fdr" or "holm".

handle_na

Missing-data handling strategy.

"impute": Impute missing values using impute_fun.
"omit": Remove observations containing missing values.

impute_fun

Function used for imputation when handle_na = "impute".

seed

Random seed for reproducibility.

parallel

Logical. Should computations be performed in parallel?

n_cores

Number of CPU cores used when parallel = TRUE.

transform

Data transformation: "auto" (default), "rank", or "none". "auto" applies rank normalization for Pearson correlation and no transformation for polychoric correlation. Use "none" to analyze continuous data without rank normalization. Polychoric correlation does not support "rank".

Value

An object of class "psychHypergraph" containing:

hypergraph: List of all significant hyperedges.
redundant_hypergraph: Hyperedges with positive O-information.
synergistic_hypergraph: Hyperedges with negative O-information.
incidence_matrix: Hypergraph incidence matrix. Rows correspond to hyperedges and columns correspond to nodes.
redundant_incidence_matrix: Incidence matrix for redundant hyperedges.
synergistic_incidence_matrix: Incidence matrix for synergistic hyperedges.
hyperedge_details: Data frame containing significant hyperedges and associated statistics.
all_test_results: Complete testing results for all evaluated candidate multiplets. These are not all possible combinations unless exhaustive search is used. The hierarchical_subset_results attribute stores intervals used for hierarchical comparison.
cor_matrix: Correlation matrix used in analysis.
ebicglasso_network: Estimated EBICglasso adjacency matrix (if applicable).
candidate_multiplets: All evaluated candidate multiplets.
parameters: Analysis settings used to generate the hypergraph, including the actual transform and the original transform_requested choice.
normalized_data: Preprocessed data used for estimation and resampling. With transform = "none", values are not rank-normalized.

Details

Data preprocessing and correlation estimation
Candidate hyperedge generation
O-information computation
Permutation-based significance testing
Bootstrap-based robustness assessment
Hierarchical validation of hyperedges
Multiple-testing correction
Construction of redundant and synergistic hypergraphs

Hyperedges represent groups of variables exhibiting statistically significant higher-order interactions. Positive O-information indicates dominant redundancy, whereas negative O-information indicates dominant synergy.

The analysis proceeds in three major stages:

Stage 1: Data preprocessing

Variables are optionally transformed and a correlation matrix is estimated.

Stage 2: Candidate generation

Candidate hyperedges are generated using either exhaustive enumeration, network-based clique selection, topology-guided search, or user-defined sets. The clique method retains subsets contained in maximal cliques and does not fall back to exhaustive search when no candidates are found.

Stage 3: Hyperedge construction

Hyperedge construction follows a rigorous three-step testing pipeline proposed by Possenti et al. (2026).

O-information is computed for each candidate multiplet and evaluated using permutation tests, bootstrap stability assessment, and hierarchical validation. Significant multiplets are retained as hyperedges. Detailed three-step testing pipelines are implemented in sig_multiplet_testing_pipeline.

Hyperedges with positive O-information are assigned to the redundant hypergraph, whereas hyperedges with negative O-information are assigned to the synergistic hypergraph.

Required lower-order subset intervals are computed for hierarchical comparison, even when those subsets did not pass permutation testing. They are not added to the candidate testing family or final hypergraph. The previous future plan is restored after testing, including on error.

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

Examples

if (FALSE) { # \dontrun{
library(psych)
data(bfi)

hg <- build_hypergraph(
  data = bfi[,1:25],
  k = 3:5,
  candidate_method = "clique",
  cor_method = "pearson",
  parallel = TRUE
)

hg

plot(hg)

} # }