0
# HyperNetX
1

2
A comprehensive Python library for the creation and study of hypergraphs. HyperNetX provides classes and methods that generalize traditional graph metrics to hypergraphs, enabling researchers to study higher-order relationships and complex network structures.
3

4
## Package Information
5

6
- **Package Name**: hypernetx
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install hypernetx`
10

11
## Core Imports
12

13
```python
14
import hypernetx as hnx
15
```
16

17
Common for working with hypergraphs:
18

19
```python
20
from hypernetx import Hypergraph
21
```
22

23
Specific functionality imports:
24

25
```python
26
# Algorithms and analysis
27
from hypernetx import (
28
    s_betweenness_centrality,
29
    betti_numbers,
30
    collective_contagion,
31
    spec_clus,
32
    greedy_matching
33
)
34

35
# Visualization
36
from hypernetx import draw, draw_incidence_upset
37

38
# Data import/export
39
from hypernetx import to_hif, from_hif
40

41
# Reports and statistics
42
from hypernetx import info, degree_dist
43

44
# Example datasets
45
from hypernetx import LesMis
46
```
47

48
## Basic Usage
49

50
```python
51
import hypernetx as hnx
52
import pandas as pd
53

54
# Create hypergraph from incidence data
55
# Edge E1 contains nodes A, B, C
56
# Edge E2 contains nodes B, C, D
57
incidence_data = pd.DataFrame({
58
    'edge': ['E1', 'E1', 'E1', 'E2', 'E2', 'E2'],
59
    'node': ['A', 'B', 'C', 'B', 'C', 'D'],
60
    'weight': [1, 1, 1, 1, 1, 1]
61
})
62

63
# Create hypergraph
64
H = hnx.Hypergraph(incidence_data)
65

66
# Basic hypergraph properties
67
print(f"Number of nodes: {H.order()}")
68
print(f"Number of edges: {len(H.edges)}")
69
print(f"Hypergraph shape: {H.shape}")
70

71
# Node and edge information
72
print(f"Nodes: {list(H.nodes)}")
73
print(f"Edges: {list(H.edges)}")
74
print(f"Incidence dict: {H.incidence_dict}")
75

76
# Basic analysis
77
print(f"Degree of node B: {H.degree('B')}")
78
print(f"Size of edge E1: {H.size('E1')}")
79
```
80

81
## Architecture
82

83
HyperNetX is built on a flexible architecture that separates data storage, views, and properties:
84

85
- **Hypergraph**: Main class that coordinates all hypergraph operations and provides high-level API
86
- **IncidenceStore**: Manages the core edge-node incidence relationships and structural queries
87
- **PropertyStore**: Handles arbitrary properties and weights for nodes, edges, and incidences
88
- **HypergraphView**: Provides filtered and typed access to different object types (nodes, edges, incidences)
89

90
This design enables efficient hypergraph manipulation while supporting rich metadata and properties on all objects.
91

92
## Capabilities
93

94
### Core Hypergraph Operations
95

96
Primary hypergraph data structure with construction, manipulation, and basic analysis methods. Includes property management, structural modifications, and conversion utilities.
97

98
```python { .api }
99
class Hypergraph:
100
    def __init__(self, setsystem=None, **kwargs): ...
101
    def order(self) -> int: ...
102
    def shape(self) -> tuple: ...
103
    def degree(self, node_uid, s=1, max_size=None): ...
104
    def size(self, edge, nodeset=None): ...
105
    def incidence_matrix(self, index=False, weights=False): ...
106
    def add_edge(self, edge_uid, inplace=True, **attr): ...
107
    def remove_edges(self, edge_uids, name=None, inplace=True): ...
108
```
109

110
[Core Hypergraph Operations](./core-hypergraph.md)
111

112
### Analysis and Metrics
113

114
Structural analysis including connectivity, distance measures, diameter calculations, and component analysis. Supports s-connected analysis for higher-order connectivity patterns.
115

116
```python { .api }
117
def is_connected(self, s=1, edges=False) -> bool: ...
118
def s_connected_components(self, s=1, edges=True, return_singletons=False): ...
119
def diameter(self, s=1): ...
120
def distance(self, source, target, s=1): ...
121
def adjacency_matrix(self, s=1, index=False): ...
122
```
123

124
[Analysis and Metrics](./analysis-metrics.md)
125

126
### Algorithms and Computations
127

128
Comprehensive collection of hypergraph algorithms including centrality measures, homology computations, contagion models, clustering methods, and matching algorithms.
129

130
```python { .api }
131
def s_betweenness_centrality(H, s=1): ...
132
def betti_numbers(H, k=None): ...
133
def collective_contagion(H, **kwargs): ...
134
def spec_clus(H, k=2): ...
135
def greedy_matching(H): ...
136
```
137

138
[Algorithms and Computations](./algorithms.md)
139

140
### Visualization and Drawing
141

142
Visualization capabilities for hypergraph display including rubber band layouts, incidence upset plots, and bipartite representations.
143

144
```python { .api }
145
def draw(H, **kwargs): ...
146
def draw_incidence_upset(H, **kwargs): ...
147
def draw_bipartite_using_euler(H, **kwargs): ...
148
```
149

150
[Visualization and Drawing](./visualization.md)
151

152
### Data Import/Export and Utilities
153

154
Data conversion utilities, HIF format support, statistical reporting functions, and example datasets for experimentation and learning.
155

156
```python { .api }
157
def to_hif(hg, filename=None, **kwargs): ...
158
def from_hif(hif=None, filename=None): ...
159
def info(H): ...
160
def degree_dist(H): ...
161
class LesMis: ...
162
```
163

164
[Data Import/Export and Utilities](./utilities.md)
165

166
## Types
167

168
```python { .api }
169
from typing import Union, Optional, Dict, List, Any
170
from pandas import DataFrame
171
from numpy import ndarray
172
from scipy.sparse import csr_matrix
173

174
# Core types
175
NodeID = Union[str, int]
176
EdgeID = Union[str, int]
177
IncidenceID = tuple[EdgeID, NodeID]
178
Weight = Union[int, float]
179
Properties = Dict[str, Any]
180

181
# Data input types
182
SetsystemInput = Union[DataFrame, Dict, List, ndarray, None]
183
PropertyInput = Union[DataFrame, Dict, None]
184

185
class HypergraphView:
186
    def __init__(self, incidence_store, level: int, property_store=None): ...
187
    @property
188
    def items(self) -> set: ...
189
    def is_empty(self) -> bool: ...
190

191
class IncidenceStore:
192
    def __init__(self, data: DataFrame): ...
193
    @property
194
    def elements(self) -> Dict[EdgeID, List[NodeID]]: ...
195
    @property
196
    def memberships(self) -> Dict[NodeID, List[EdgeID]]: ...
197

198
class PropertyStore:
199
    def __init__(self, data: Optional[DataFrame] = None, default_weight: Weight = 1): ...
200
    def get_properties(self, uid: Union[NodeID, EdgeID, IncidenceID]) -> Dict[str, Any]: ...
201
    def set_property(self, uid: Union[NodeID, EdgeID, IncidenceID], prop_name: str, prop_val: Any): ...
202

203
# Exception types
204
class HyperNetXException(Exception): ...
205
class HyperNetXError(Exception): ...
206
class HyperNetXNotImplementedError(NotImplementedError): ...
207
```