# hypergraphx
**Repository Path**: Dledger/hypergraphx
## Basic Information
- **Project Name**: hypergraphx
- **Description**: HGX is a multi-purpose, open-source Python library for higher-order network analysis
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-02
- **Last Updated**: 2026-09-02
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
**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鈥憃rder data: conversions across representations, measures of higher鈥憃rder organization, filtering and sparsification, generative models, and dynamical processes from contagion to synchronization. The framework is general and designed to be user鈥慺riendly and accessible.
[](https://hypergraphx.readthedocs.io/) [](https://arxiv.org/abs/2303.15356) [](https://github.com/HGX-Team/hypergraphx/tree/main/tutorials)  [](https://pepy.tech/project/hypergraphx) [](https://github.com/HGX-Team/hypergraphx/issues) [](https://hgx-team.github.io/hypergraphx-data/)   [](mailto:quintino.lotito@unitn.it)
## 馃Л Menu
- [What are higher-order networks?](#-what-are-higher-order-networks)
- [Quick start](#-quick-start)
- [Library highlights](#-library-highlights)
- [Tutorials and data](#-tutorials-and-data)
- [The HGX team](#-the-hgx-team)
- [Acknowledgments](#-acknowledgments)
- [Citing HGX](#-citing-hgx)
- [Contributing](#-contributing)
- [License](#-license)
- [Other resources](#-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鈥憈o鈥慺ace interactions, collaboration teams. Hypergraphs model these **higher鈥憃rder interactions** directly, with hyperedges that connect any number of nodes.
## 馃殌 Quick start
### Install
```bash
pip install hypergraphx
```
Latest (from GitHub):
```bash
pip install hypergraphx@git+https://github.com/HGX-Team/hypergraphx
```
### Create a hypergraph
```python
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
```python
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
```python
line_graph = H.to_line_graph()
print(line_graph.number_of_nodes())
```
### Linear algebra (matrices)
```python
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)
```python
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鈥憃rder 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://hgx-team.github.io/hypergraphx-data/
## 馃懃 The HGX team
Project coordinators
- Quintino Francesco Lotito (lead developer) 路 馃惁 [Twitter](https://twitter.com/FraLotito) 路 馃悪 [GitHub](https://github.com/FraLotito)
- Federico Battiston (project coordinator) 路 馃敆 [Website](https://people.ceu.edu/federico_battiston) 路 馃惁 [Twitter](https://twitter.com/fede7j) 路 馃悪 [GitHub](https://github.com/fede7j)
Contributors
- Lorenzo Betti 路 馃惁 [Twitter](https://x.com/LoreBetti) 路 馃悪 [GitHub](https://github.com/Loreb92)
- Alberto Ceria 路 馃惁 [Twitter](https://twitter.com/cerialbo)
- Davide Colosimo
- Martina Contisciani 路 馃惁 [Twitter](https://twitter.com/mcontisc) 路 馃悪 [GitHub](https://github.com/mcontisc)
- Caterina De Bacco 路 馃敆 [Website](https://www.cdebacco.com/) 路 馃悪 [GitHub](https://github.com/cdebacco)
- Leonardo Di Gaetano 路 馃惁 [Twitter](https://twitter.com/leodigaetano) 路 馃悪 [GitHub](https://github.com/LeonardoDiGaetano)
- Helcio Felippe 路 馃惁 [Twitter](https://x.com/juniorfelippe)
- Luca Gallo 路 馃惁 [Twitter](https://twitter.com/l_gajo) 路 馃悪 [GitHub](https://github.com/lgajo)
- Alec Kirkley 路 馃敆 [Website](https://aleckirkley.com/) 路 馃惁 [Twitter](https://x.com/captainkirk1041) 路 馃悪 [GitHub](https://github.com/aleckirkley)
- Alberto Montresor 路 馃敆 [Website](http://cricca.disi.unitn.it/montresor/)
- Federico Musciotto 路 馃惁 [Twitter](https://twitter.com/musci8) 路 馃悪 [GitHub](https://github.com/musci8)
- Bern茅 Nortier 路 馃悪 [GitHub](https://github.com/joanne-b-nortier)
- Nicol貌 Ruggeri 路 馃敆 [Website](https://nickruggeri.github.io/) 路 馃惁 [Twitter](https://twitter.com/NikRuggeri) 路 馃悪 [GitHub](https://github.com/nickruggeri)
- Alberto Vendramini
## 馃Ь Citing HGX
```bibtex
@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](CONTRIBUTING.md).
## 馃摐 License
Released under the 3-Clause BSD license. See [LICENSE.md](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-party sources. The licenses of such code sources can be found in [LICENSE.md](LICENSE.md).