Hypergraph analysis in Python

A Python library for higher-order networks.

Hypergraphx is a research-friendly Python library for building, analyzing, and visualizing hypergraphs.

Install pip install hypergraphx

Read the paper

Example figure Python

Higher-order analytics Visualization tools

Higher-order networks

Graphs connect pairs. Hypergraphs connect groups.

Standard networks record one-to-one relations. Hypergraphs keep the full group: a collaboration, a coauthored paper, a reaction, or a shared event can be represented as one object.

Graph

Pairwise links

Hypergraph

Overlapping group interactions

Cellular systems Drug recombination Brain networks Collaboration teams

Workflow

Build, measure, and visualize hypergraphs.

01 Model

Create hypergraphs from node groups, files, or generators.

02 Analyze

Run measures for degree, centrality, motifs, projections, and spectra.

03 Visualize

Draw hypergraphs and derived views with reproducible layouts.

Features

What you can do with Hypergraphx.

Load and filter data

Search hypergraphx-data, load datasets into the library, and use filtering tools to prepare them for analysis.

Measure structure

Compute degrees, centralities, motifs, and communities on the same hypergraph object.

Convert representations

Switch between hypergraphs, bipartite graphs, clique projections, line graphs, and simplicial complexes.

Generate hypergraphs

Sample random hypergraphs with specified numbers of nodes, hyperedges, and hyperedge sizes.

Study dynamics

Explore contagion, synchronization, random walks, diffusion, and temporal activity on higher-order structures.

Draw hypergraphs

Visualize pairwise links and higher-order hyperedges from the same Hypergraphx object.

Tutorials

A short example, from construction to plots.

Step 01

Create a random hypergraph

from hypergraphx.generation import random_hypergraph

h = random_hypergraph(
    num_nodes=8,
    num_edges_by_size={2: 4, 3: 4, 4: 4},
    seed=9,
)

Step 02

Degree centrality distribution

import matplotlib.pyplot as plt
from hypergraphx.measures.degree import degree_sequence

deg = degree_sequence(h)
plt.hist(deg.values())

Step 03

Draw the hypergraph

from hypergraphx.measures.degree import degree_sequence
from hypergraphx.viz import draw_hypergraph

deg = degree_sequence(h)
top = set(sorted(deg, key=deg.get, reverse=True)[:2])
draw_hypergraph(h)  # then recolor top nodes

Hypergraph visualization with highlighted hubs

Dataset loading

Load datasets from hypergraphx-data.

Search the remote catalog, choose a dataset, and load it as a Hypergraphx object for analysis.

Browse hypergraphx-data Read the loader docs

from hypergraphx.readwrite import (
    search_remote_datasets,
    load_hypergraph_from_server,
)
from hypergraphx.measures.degree import degree_sequence

matches = search_remote_datasets(tags="Food")
dataset = matches[0]["name"]

h = load_hypergraph_from_server(dataset, fmt="json")
print(dataset, h.num_nodes(), h.num_edges())
print(degree_sequence(h))

Get started

Install Hypergraphx.

Start with the package, then use the documentation and tutorials for the parts of the API you need.

Install pip install hypergraphx

API docs GitHub Paper

Citation

How to cite Hypergraphx.

If you use Hypergraphx in a publication, cite the paper below.

Read the paper Repository

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},
    doi = {10.1093/comnet/cnad019},
    pages = {cnad019},
    publisher = {Oxford University Press}
}