From e76182def1d31a89ad47b53cfbe8febf32d59dab Mon Sep 17 00:00:00 2001 From: Joshua Pickard Date: Fri, 22 May 2026 22:43:37 -0400 Subject: [PATCH 1/3] FIX: hypergraph constructor bug from joseph --- Python/HAT/hypergraph.py | 1 + Tests/hypergraph_constructors.py | 4 ++-- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/Python/HAT/hypergraph.py b/Python/HAT/hypergraph.py index 7348104..0639cf1 100644 --- a/Python/HAT/hypergraph.py +++ b/Python/HAT/hypergraph.py @@ -89,6 +89,7 @@ def __init__(self, ) # Convert all nodes to integers, and build a map between integers and names + name_to_int = None if edge_list is not None: new_edge_list, name_to_int = convert_nodes_to_integers(edge_list) original_edge_list = copy.deepcopy(edge_list) diff --git a/Tests/hypergraph_constructors.py b/Tests/hypergraph_constructors.py index 1832473..82ecb8a 100644 --- a/Tests/hypergraph_constructors.py +++ b/Tests/hypergraph_constructors.py @@ -336,7 +336,7 @@ def test_add_edge_2(self): edge_df = pd.DataFrame({ 'Nodes': [[0, 1, 2], [0, 1, 3], [2, 3]], 'Edges': [0,1,2], - 'weight': [1.5, 2.5, pd.NA] + 'weight': [1.5, 2.5, np.nan] }) # Assert the edges match @@ -358,7 +358,7 @@ def test_add_edge_3(self): edge_df = pd.DataFrame({ 'Nodes': [[0, 1, 2], [0, 1, 3], [2, 3]], 'Edges': [0,1,2], - 'weight': [pd.NA, pd.NA, 3.0] + 'weight': [np.nan, np.nan, 3.0] }) # Assert the edges match From 649c8dbb1c85dcecc7f15c35b1806b8fddb4db55 Mon Sep 17 00:00:00 2001 From: Joshua Pickard Date: Fri, 22 May 2026 23:02:36 -0400 Subject: [PATCH 2/3] DOCS --- README.md | 123 ++++++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 101 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 4e799d5..f46f18d 100644 --- a/README.md +++ b/README.md @@ -1,31 +1,110 @@ -# Hypergraph-Analysis-Toolbox (HAT) +# Hypergraph Analysis Toolbox (HAT) -[![Documentation Status](https://readthedocs.org/projects/hypergraph-analysis-toolbox/badge/?version=latest)](https://hypergraph-analysis-toolbox.readthedocs.io/en/latest/?badge=latest) -[![View Hypergraph Analysis Toolbox on File Exchange](https://www.mathworks.com/matlabcentral/images/matlab-file-exchange.svg)](https://www.mathworks.com/matlabcentral/fileexchange/121013-hypergraph-analysis-toolbox) +[![Documentation](https://readthedocs.org/projects/hypergraph-analysis-toolbox/badge/?version=latest)](https://hypergraph-analysis-toolbox.readthedocs.io/en/latest/) +[![MATLAB File Exchange](https://www.mathworks.com/matlabcentral/images/matlab-file-exchange.svg)](https://www.mathworks.com/matlabcentral/fileexchange/121013-hypergraph-analysis-toolbox) +[![PyPI version](https://img.shields.io/pypi/v/HypergraphAnalysisToolbox)](https://pypi.org/project/HypergraphAnalysisToolbox/) -The [Hypergraph Analysis Toolbox](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1011190) is a general purpose software for analyzing the structure and dynamics of Hypergraphs. +HAT is a general-purpose software suite for constructing, analyzing, and visualizing hypergraphs and higher-order structures. Originally motivated by the analysis of Pore-C genomic data, HAT is designed to be versatile and extensible across domains with a focus on tensor, dynamics, and control +based algorithms for higher order networks -Hypergraph Analysis Toolbox (HAT) is a software suite for the analysis and visualization of hypergraphs and higher order structures. Motivated to investigate Pore-C data, HAT is intended as a general prupose, versatile software for hypergraph construction, visualization, and analysis. HAT's main features include: +--- -- Controllability and observability of higher order systems -- Hypergraph metrics: centrality, similarity, entropy, etc. -- Tensor based analysis: eigenvalues, decompositions, Kronecker products, etc. +## Features -Documentation for HAT is found [here](https://hypergraph-analysis-toolbox.readthedocs.io/en/latest/index.html) at: https://hypergraph-analysis-toolbox.readthedocs.io/en/latest/index.html +- **Flexible construction** — build hypergraphs from edge lists, incidence matrices, or adjacency tensors; directed and undirected; weighted and unweighted +- **Metrics** — centrality, similarity, entropy, and more +- **Spectral methods** — Laplacians and related operators +- **Tensor analysis** — eigenvalues, decompositions, and Kronecker products +- **Controllability and observability** — analysis of higher-order dynamical systems +- **Visualization** — hypergraph drawing utilities +- **Interoperability** — import/export with HIF, HyperNetX, and HypergraphX -**Papers by the HAT Team** -HAT was developed to consolidate and facilitate the development of new hypergraph methods. Select papers that motivated this development and whose methods are part of HAT include: +--- -- Scalable Hypergraph Algorithms for Observability of Gene Regulation (*coming soon*) -- [Kronecker Products of Tensors and Hypergraphs](https://epubs.siam.org/doi/full/10.1137/23M1592547) -- [Observability of Hypergraphs](https://drive.google.com/file/d/1FQxRj5VdPkY-P64ek7rq4lp9jQW9MLFP/view) -- [Geometric Apsects of Observability of Hypergraphs](https://drive.google.com/file/d/1-5AL_rOvAm-aUClSfyy9MpED7h7_L76o/view) -- [HAT: Hypergraph Analysis Toolbox](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1011190) -- [Deciphering Multiway Interactions in the Human Genome](https://drive.google.com/file/d/1rp6ZtKf_DxUL0xOpcUzRg1rJGA6xlu-f/view) -- [Hypergraph Similarity Measures](https://drive.google.com/file/d/1Dc4nSkkZyk4axOAshdRDXo8Gx24h4M-d/view) -- [Controllability of Hypergraphs](https://drive.google.com/file/d/12aReE7mE4MVbycZUxUYdtICgrAYlzg8o/view) -- [Tensor Entropy for Uniform Hypergraphs](https://drive.google.com/file/d/1-d4uR5KT3iDpOd69aCQVjNZzMyILXp5E/view) -- [Multilinear Control Systems Theory](https://drive.google.com/file/d/1F0ZGoVWeKSWemXvSp6ilTwLS8N7j6n71/view) +## Installation -HAT_logo_v2 +### Python +```bash +pip install HypergraphAnalysisToolbox +``` + +Requires Python ≥ 3.11. + +### MATLAB + +Download from [MATLAB File Exchange](https://www.mathworks.com/matlabcentral/fileexchange/121013-hypergraph-analysis-toolbox) or clone this repository and add the `Matlab/` directory to your MATLAB path. + +--- + +## Quick Start + +```python +import numpy as np +from HAT import Hypergraph + +# Construct from an edge list +H = Hypergraph(edge_list=[[0, 1, 2], [0, 1, 3]]) + +# Construct from an incidence matrix +D = np.array([[1, 1], + [1, 1], + [1, 0], + [0, 1]]) +H = Hypergraph(incidence_matrix=D) + +``` + +--- + +## Documentation + +Full documentation — including API reference, tutorials, and examples — is available at: + +**https://hypergraph-analysis-toolbox.readthedocs.io** + +--- + +## Publications + +HAT consolidates and contains methods from the following works: + +| Paper | Link | +|---|---| +| Structural Controllability of Large-Scale Hypergraphs | [Preprint](https://arxiv.org/pdf/2603.19955) | +| Data-Driven Tensor Decomposition Identification of Homogeneous Polynomial Dynamical Systems | [Preprint](https://arxiv.org/pdf/2604.03508) | +| Scalable Hypergraph Algorithms for Observability of Gene Regulation | [European Control Conference](https://ieeexplore.ieee.org/document/11186979) | +| Deciphering Multiway Interactions in the Human Genome | [Nature Communications](https://drive.google.com/file/d/1rp6ZtKf_DxUL0xOpcUzRg1rJGA6xlu-f/view) | +| Geometric Aspects of Observability of Hypergraphs | [IFAC LHMNC](https://drive.google.com/file/d/1-5AL_rOvAm-aUClSfyy9MpED7h7_L76o/view) | +| Observability of Hypergraphs | [IEEE CDC](https://drive.google.com/file/d/1FQxRj5VdPkY-P64ek7rq4lp9jQW9MLFP/view) | +| Kronecker Products of Tensors and Hypergraphs | [SIAM Journal on Matrix Analysis and Applications](https://epubs.siam.org/doi/full/10.1137/23M1592547) | +| HAT: Hypergraph Analysis Toolbox | [PLOS Computational Biology](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1011190) | +| Hypergraph Similarity Measures | [IEEE TRANSACTIONS ON NETWORK SCIENCE AND ENGINEERING](https://drive.google.com/file/d/1Dc4nSkkZyk4axOAshdRDXo8Gx24h4M-d/view) | +| Controllability of Hypergraphs | [IEEE TRANSACTIONS ON NETWORK SCIENCE AND ENGINEERING](https://drive.google.com/file/d/12aReE7mE4MVbycZUxUYdtICgrAYlzg8o/view) | +| Tensor Entropy for Uniform Hypergraphs | [Tensor Entropy for Uniform Hypergraphs](https://drive.google.com/file/d/1-d4uR5KT3iDpOd69aCQVjNZzMyILXp5E/view) | +| Multilinear Control Systems Theory | [SIAM J. CONTROL OPTIM.](https://drive.google.com/file/d/1F0ZGoVWeKSWemXvSp6ilTwLS8N7j6n71/view) | + +--- + +## Citation + +If you use HAT in your research, please cite: + +```bibtex +@article{pickard2023hat, + title={HAT: Hypergraph analysis toolbox}, + author={Pickard, Joshua and Chen, Can and Salman, Rahmy and Stansbury, Cooper and Kim, Sion and Surana, Amit and Bloch, Anthony and Rajapakse, Indika}, + journal={PLOS Computational Biology}, + volume={19}, + number={6}, + pages={e1011190}, + year={2023}, + publisher={Public Library of Science San Francisco, CA USA} +} +``` + +--- + +## Contributing + +Bug reports and feature requests are welcome via [GitHub Issues](https://github.com/Jpickard1/Hypergraph-Analysis-Toolbox/issues). From 2db2da7917481deb832e84acf034bdce38db4fe6 Mon Sep 17 00:00:00 2001 From: Joshua Pickard Date: Fri, 22 May 2026 23:00:48 -0400 Subject: [PATCH 3/3] DOCS --- README.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index f46f18d..f147749 100644 --- a/README.md +++ b/README.md @@ -65,9 +65,7 @@ Full documentation — including API reference, tutorials, and examples — is a --- -## Publications - -HAT consolidates and contains methods from the following works: +## Related Publications | Paper | Link | |---|---| @@ -75,8 +73,8 @@ HAT consolidates and contains methods from the following works: | Data-Driven Tensor Decomposition Identification of Homogeneous Polynomial Dynamical Systems | [Preprint](https://arxiv.org/pdf/2604.03508) | | Scalable Hypergraph Algorithms for Observability of Gene Regulation | [European Control Conference](https://ieeexplore.ieee.org/document/11186979) | | Deciphering Multiway Interactions in the Human Genome | [Nature Communications](https://drive.google.com/file/d/1rp6ZtKf_DxUL0xOpcUzRg1rJGA6xlu-f/view) | -| Geometric Aspects of Observability of Hypergraphs | [IFAC LHMNC](https://drive.google.com/file/d/1-5AL_rOvAm-aUClSfyy9MpED7h7_L76o/view) | -| Observability of Hypergraphs | [IEEE CDC](https://drive.google.com/file/d/1FQxRj5VdPkY-P64ek7rq4lp9jQW9MLFP/view) | +| Geometric Aspects of Observability of Hypergraphs | [IFAC Workshop on Lagrangian and Hamiltonian Methods for Non Linear Control](https://drive.google.com/file/d/1-5AL_rOvAm-aUClSfyy9MpED7h7_L76o/view) | +| Observability of Hypergraphs | [IEEE Conference on Decision and Control](https://drive.google.com/file/d/1FQxRj5VdPkY-P64ek7rq4lp9jQW9MLFP/view) | | Kronecker Products of Tensors and Hypergraphs | [SIAM Journal on Matrix Analysis and Applications](https://epubs.siam.org/doi/full/10.1137/23M1592547) | | HAT: Hypergraph Analysis Toolbox | [PLOS Computational Biology](https://journals.plos.org/ploscompbiol/article?id=10.1371/journal.pcbi.1011190) | | Hypergraph Similarity Measures | [IEEE TRANSACTIONS ON NETWORK SCIENCE AND ENGINEERING](https://drive.google.com/file/d/1Dc4nSkkZyk4axOAshdRDXo8Gx24h4M-d/view) |