🚀 Quickstart

Common tasks and minimal examples. Copy and run.

Tasks

Core classes

  • hypergraphx.Hypergraph (undirected)

  • hypergraphx.DirectedHypergraph

  • hypergraphx.TemporalHypergraph

  • hypergraphx.MultiplexHypergraph

Create a hypergraph

import hypergraphx as hgx

hg = hgx.Hypergraph(edge_list=[(0, 1, 2), (2, 3)], weighted=True, weights=[1.0, 2.0])
hg.add_edge((3, 4), weight=1.5, metadata={"kind": "tri"})
print(hg)

Note

Hypergraphs are weighted by default. If you want an unweighted hypergraph, pass weighted=False (unweighted graphs only accept weight=None or weight=1).

Directed / temporal / multiplex

dh = hgx.DirectedHypergraph(edge_list=[((0, 1), (2,)), ((2,), (3,))])
th = hgx.TemporalHypergraph(edge_list=[(0, (0, 1)), (1, (1, 2))])
mx = hgx.MultiplexHypergraph(edge_list=[(0, 1), (1, 2)], edge_layer=["L1", "L2"])

# Directed in/out degrees
dh.in_degree(2)
dh.out_degree(2)

Common queries

hg.num_nodes()
hg.num_edges()
hg.get_edges()
hg.get_incident_edges(2)
hg.degree(2)
hg.get_edge_metadata((0, 1, 2))

Tip

For a smaller API surface, start with hypergraphx.core and hypergraphx.readwrite.

Common patterns

# Build -> analyze -> save
hg = hgx.Hypergraph(edge_list=[(0, 1), (1, 2, 3)])
seq = degree_sequence(hg)
hgx.save_hypergraph(hg, "graph.json")

Conversions

# Drop direction, time, or layer information
dh = hgx.DirectedHypergraph(edge_list=[((0, 1), (2,))], weighted=True, weights=[2.0])
th = hgx.TemporalHypergraph(edge_list=[(0, (0, 1)), (1, (0, 1))], weighted=True, weights=[1.0, 2.0])
mx = hgx.MultiplexHypergraph(edge_list=[(0, 1), (0, 1)], edge_layer=["L1", "L2"], weighted=True, weights=[1.0, 2.0])

dh.to_hypergraph()  # merges source/target, sums weights
th.to_hypergraph()  # drops time, sums weights
mx.to_hypergraph()  # drops layer, sums weights

Load and save

hgx.save_hypergraph(hg, "graph.json")
hg2 = hgx.load_hypergraph("graph.json")

# Server datasets
# Network loading is opt-in (so offline / sandboxed environments don't surprise you)
hg3 = hgx.load_hypergraph_from_server("toy", fmt="json", allow_network=True)

Projections and matrices

from hypergraphx.linalg import adjacency_matrix
from hypergraphx.representations.projections import clique_projection

A = adjacency_matrix(hg)
G = clique_projection(hg)

Measures

from hypergraphx.measures.degree import degree_sequence
from hypergraphx.measures.shortest_paths import calc_ho_shortest_paths
seq = degree_sequence(hg)
paths = calc_ho_shortest_paths(hg)

API map

  • Core classes: hypergraphx.core

  • Read/write: hypergraphx.readwrite

  • Measures: hypergraphx.measures

  • Representations: hypergraphx.representations

  • Linear algebra: hypergraphx.linalg

  • Filters: hypergraphx.filters

  • Motifs: hypergraphx.motifs

  • Dynamics: hypergraphx.dynamics

  • Communities: hypergraphx.communities

  • Utils: hypergraphx.utils

Exceptions

All custom exceptions inherit from HypergraphxError. Most also inherit from ValueError (ReadwriteError inherits from RuntimeError).

from hypergraphx import MissingNodeError

try:
    hg.get_incident_edges("missing")
except MissingNodeError:
    pass

Logging (optional)

Hypergraphx uses the standard logging module. To see info-level logs:

import logging

logging.basicConfig(level=logging.INFO)