Hypergraphx

<img src="assets/logo/logo.png" width="420" alt="HGX logo" />

Hypergraphx (HGX) is a Python library for the analysis of real-world complex systems with group interactions. It provides a comprehensive suite of tools to construct, visualize, and analyze hypergraphs with weighted, directed, temporal, and multiplex interactions. HGX aims to provide, as a single source, a wide range of tools for higher‑order data: conversions across representations, measures of higher‑order organization, filtering and sparsification, generative models, and dynamical processes from contagion to synchronization. The framework is general and designed to be user‑friendly and accessible.

🧭 Menu

• What are higher-order networks?
• Quick start
• Library highlights
• Tutorials and data
• The HGX team
• Acknowledgments
• Citing HGX
• Contributing
• License
• Other resources

🌐 What are higher-order networks?

Networks capture pairwise (dyadic) interactions. But many real systems involve groups of three or more units acting together: cellular networks, drug recombination, brain networks, face‑to‑face interactions, collaboration teams. Hypergraphs model these higher‑order interactions directly, with hyperedges that connect any number of nodes.

<img src="assets/images/hypergraph.png" width="350" alt="Hypergraph example" />

🚀 Quick start

Install

pip install hypergraphx

Latest (from GitHub):

pip install hypergraphx@git+https://github.com/HGX-Team/hypergraphx

Create a hypergraph

from hypergraphx import Hypergraph

H = Hypergraph(edge_list=[(1, 2, 3), (2, 4)])
print(H.num_nodes(), H.num_edges())
print(H.get_neighbors(2))

Add weights and metadata

H = Hypergraph(
    edge_list=[("A", "B"), ("B", "C")],
    weighted=True,
    weights=[1.2, 0.7],
    node_metadata={"A": {"role": "source"}},
    edge_metadata=[{"type": "interaction"}, {"type": "interaction"}],
)

print(H.get_weight(("A", "B")))
print(H.get_node_metadata("A"))

Convert and analyze

line_graph = H.to_line_graph()
print(line_graph.number_of_nodes())

Linear algebra (matrices)

from hypergraphx.linalg import laplacian_matrix_by_order

# Node-indexed incidence + node mapping (row index -> node label)
B, node_map = H.binary_incidence_matrix(return_mapping=True)

# Node-indexed adjacency (CSR by default)
A = H.adjacency_matrix()

# Order-specific Laplacian + mapping
L2, node_map = laplacian_matrix_by_order(H, order=2, return_mapping=True)

# Example: a few smallest eigenvalues
from scipy.sparse.linalg import eigsh

eigs = eigsh(L2, k=5, which="SM", return_eigenvectors=False)
print(eigs)

Temporal interactions (at a glance)

from hypergraphx import TemporalHypergraph

T = TemporalHypergraph()
T.add_edge(("A", "B"), time=1)
T.add_edge(("A", "B", "C"), time=2)
print(T.get_edges(time_window=(1, 3)))

🧰 Library highlights

• Representations and transforms: hypergraphs, bipartite networks, line graphs, clique expansions, duals.
• Measures and statistics: degrees, correlations, assortativity, motifs, and mesoscale structure.
• Centrality and motifs: spectral approaches, shortest paths, betweenness flows, motif sampling.
• Communities and inference: hard and overlapping communities, assortative/disassortative structure.
• Filtering: statistically validated hypergraphs and significant interacting groups.
• Generative models: Erdos-Renyi, scale-free, configuration, community-based, temporal activity-driven.
• Dynamics: synchronization, social contagion, random walks, diffusion.
• Rich semantics: weighted, directed, temporal, multiplex, signed interactions.

📎 Tutorials and data

If you are new to higher‑order networks, start with the introductory notebooks. The tutorials cover:

• building hypergraphs from data
• computing measures and centralities
• filtering and sampling
• community detection and inference
• temporal and multiplex workflows

Tutorials: https://github.com/HGX-Team/hypergraphx/tree/main/tutorials

Datasets: https://github.com/HGX-Team/data

👥 The HGX team

Project coordinators

• Quintino Francesco Lotito (lead developer) · 🐦 Twitter · 🐙 GitHub
• Federico Battiston (project coordinator) · 🔗 Website · 🐦 Twitter · 🐙 GitHub

Contributors

• Lorenzo Betti · 🐦 Twitter · 🐙 GitHub
• Alberto Ceria · 🐦 Twitter
• Davide Colosimo
• Martina Contisciani · 🐦 Twitter · 🐙 GitHub
• Caterina De Bacco · 🔗 Website · 🐙 GitHub
• Leonardo Di Gaetano · 🐦 Twitter · 🐙 GitHub
• Helcio Felippe · 🐦 Twitter
• Luca Gallo · 🐦 Twitter · 🐙 GitHub
• Alec Kirkley · 🔗 Website · 🐦 Twitter · 🐙 GitHub
• Alberto Montresor · 🔗 Website
• Federico Musciotto · 🐦 Twitter · 🐙 GitHub
• Berné Nortier · 🐙 GitHub
• Nicolò Ruggeri · 🔗 Website · 🐦 Twitter · 🐙 GitHub
• Alberto Vendramini

🧾 Citing HGX

@article{lotito2023hypergraphx,
    author = {Lotito, Quintino Francesco and Contisciani, Martina and De Bacco, Caterina and Di Gaetano, Leonardo and Gallo, Luca and Montresor, Alberto and Musciotto, Federico and Ruggeri, Nicolo and Battiston, Federico},
    title = "{Hypergraphx: a library for higher-order network analysis}",
    journal = {Journal of Complex Networks},
    volume = {11},
    number = {3},
    year = {2023},
    month = {05},
    issn = {2051-1329},
    doi = {10.1093/comnet/cnad019},
    url = {https://doi.org/10.1093/comnet/cnad019},
    note = {cnad019},
    eprint = {https://academic.oup.com/comnet/article-pdf/11/3/cnad019/50461094/cnad019.pdf},
}

🤝 Contributing

HGX is a collaborative project and we welcome suggestions and contributions. If you are interested in contributing to HGX or have any questions about our project, please do not hesitate to reach out to us.

For setup instructions, local checks, and pull-request guidelines, see CONTRIBUTING.md.

📜 License

Released under the 3-Clause BSD license. See LICENSE.md.

🙏 Acknowledgments

This project is supported by the Air Force Office of Scientific Research under award number FA8655-22-1-7025.

HGX contains copied or modified code from third sources. The licenses of such code sources can be found in LICENSE.md.