The HNX library provides classes and methods for modeling the entities and relationships found in complex networks as hypergraphs, the natural models for multi-dimensional network data. As strict generalizations of graphs, hyperedges can represent arbitrary multi-way relations among entities, and in particular can distinguish cliques and simplices, and admit singleton edges. As both vertex adjacency and edge incidence are generalized to be quantities, hypergraph paths and walks thereby have both length and width because of these multiway connections. Most graph metrics have natural generalizations to hypergraphs, but since hypergraphs are basically set systems, they also admit to the powerful tools of algebraic topology, including simplicial complexes and simplicial homology, to study their structure.
This library serves as a repository of the methods and algorithms we find most useful as we explore what hypergraphs can tell us. We have a growing community of users and contributors. To learn more about some of our research check out our publications below:
Joslyn, Cliff A; Aksoy, Sinan; Callahan, Tiffany J; Hunter, LE; Jefferson, Brett ; Praggastis, Brenda ; Purvine, Emilie AH ; Tripodi, Ignacio J: (2020) "Hypernetwork Science: From Multidimensional Networks to Computational Topology", in: Int. Conf. Complex Systems (ICCS 2020), https://arxiv.org/abs/2003.11782, (in press)
Feng, Song; Heath, Emily; Jefferson, Brett; Joslyn, CA; Kvinge, Henry; McDermott, Jason E ; Mitchell, Hugh D ; Praggastis, Brenda ; Eisfeld, Amie J; Sims, Amy C ; Thackray, Larissa B ; Fan, Shufang ; Walters, Kevin B; Halfmann, Peter J ; Westhoff-Smith, Danielle ; Tan, Qing ; Menachery, Vineet D ; Sheahan, Timothy P ; Cockrell, Adam S ; Kocher, Jacob F ; Stratton, Kelly G ; Heller, Natalie C ; Bramer, Lisa M ; Diamond, Michael S ; Baric, Ralph S ; Waters, Katrina M ; Kawaoka, Yoshihiro ; Purvine, Emilie: (2020) "Hypergraph Models of Biological Networks to Identify Genes Critical to Pathogenic Viral Response", in: https://arxiv.org/abs/2010.03068, BMC Bioinformatics, 22:287, doi: 10.1186/s12859-021-04197-2
Aksoy, Sinan G; Joslyn, Cliff A; Marrero, Carlos O; Praggastis, B; Purvine, Emilie AH: (2020) "Hypernetwork Science via High-Order Hypergraph Walks", EPJ Data Science, v. 9:16, https://doi.org/10.1140/epjds/s13688-020-00231-0
Joslyn, Cliff A; Aksoy, Sinan; Arendt, Dustin; Firoz, J; Jenkins, Louis ; Praggastis, Brenda ; Purvine, Emilie AH ; Zalewski, Marcin: (2020) "Hypergraph Analytics of Domain Name System Relationships", in: 17th Wshop. on Algorithms and Models for the Web Graph (WAW 2020), Lecture Notes in Computer Science, v. 12901, ed. Kaminski, B et al., pp. 1-15, Springer, https://doi.org/10.1007/978-3-030-48478-1_1
Joslyn, Cliff A; Aksoy, Sinan; Arendt, Dustin; Jenkins, L; Praggastis, Brenda; Purvine, Emilie; Zalewski, Marcin: (2019) "High Performance Hypergraph Analytics of Domain Name System Relationships", in: Proc. HICSS Symp. on Cybersecurity Big Data Analytics, http://www.azsecure-hicss.org/
HNX was developed by the Pacific Northwest National Laboratory for the Hypernets project as part of its High Performance Data Analytics (HPDA) program. PNNL is operated by Battelle Memorial Institute under Contract DE-ACO5-76RL01830.
- Principle Developer and Designer: Brenda Praggastis
- Visualization: Dustin Arendt, Ji Young Yun
- High Performance Computing: Tony Liu, Andrew Lumsdaine
- Principal Investigator: Cliff Joslyn
- Program Manager: Mark Raugas, Brian Kritzstein
- Mathematics, methods, and algorithms: Sinan Aksoy, Dustin Arendt, Cliff Joslyn, Andrew Lumsdaine, Tony Liu, Brenda Praggastis, and Emilie Purvine
The code in this repository is intended to support researchers modeling data as hypergraphs. We have a growing community of users and contributors. Documentation is available at: https://pnnl.github.io/HyperNetX/ For questions and comments contact the developers directly at: [email protected]
- Hypergraph construction can be sped up by reading in all of the data at once. In particular the hypergraph constructor may read a Pandas dataframe object and create edges and nodes based on column headers. The new hypergraphs are given an attribute
static=True. - A C++ addon called NWHy can be used in Linux environments to support optimized hypergraph methods such as s-centrality measures.
- A JavaScript addon called Hypernetx-Widget can be used to interactively inspect hypergraphs in a Jupyter Notebook.
- We've added four new tutorials highlighting the s-centrality metrics, static Hypergraphs, NWHy, and Hypernetx-Widget.
Tutorial 1 - HNX Basics
Tutorial 2 - Visualization Methods
Tutorial 3 - LesMis Case Study
Tutorial 4 - LesMis Visualizations-Book Tour
Tutorial 5 - Homology mod2 for TriLoop Example
Tutorial 6 - Static Hypergraphs and Entities
Tutorial 7 - s-Centrality
HyperNetX may be cloned or forked from: https://github.com/pnnl/HyperNetX
>>> conda create -n <env name> python=3.7
>>> source activate <env name>
>>> pip install hypernetx
Mac Users: If you wish to build the documentation you will need the conda version of matplotlib:
>>> conda create -n <env name> python=3.7 matplotlib
>>> source activate <env name>
>>> pip install hypernetx
To use NWHy use python=3.9 and the conda version of tbb in your environment. Note that NWHy only works on Linux and some OSX systems. See NWHy documentation for more.:
>>> conda create -n <env name> python=3.9 tbb
>>> source activate <env name>
>>> pip install hypernetx
>>> pip install nwhy
>>> virtualenv --python=<path to python 3.7 executable> <path to env name>
This will create a virtual environment in the specified location using the specified python executable. For example:
>>> virtualenv --python=C:\Anaconda3\python.exe hnx
This will create a virtual environment in .\hnx using the python that comes with Anaconda3.
>>> <path to env name>\Scripts\activate<file extension>
If you are running in Windows PowerShell use =.ps1
If you are running in Windows Command Prompt use =.bat
Otherwise use =NULL (no file extension).
Once activated continue to follow the installation instructions below.
For a minimal installation:
>>> pip install hypernetx
For an editable installation with access to jupyter notebooks:
>>> pip install [-e] .
To install with the tutorials:
>>> pip install -e .['tutorials']
To install with the documentation:
>>> pip install -e .['documentation']
>>> chmod 755 build_docs.sh
>>> sh build_docs.sh
## This will generate the documentation in /docs/build/
## Open them in your browser with /docs/index.html
To install and test using pytest:
>>> pip install -e .['testing']
>>> pytest
To install the whole shabang:
>>> pip install -e .['all']
This material was prepared as an account of work sponsored by an agency of the United States Government. Neither the United States Government nor the United States Department of Energy, nor Battelle, nor any of their employees, nor any jurisdiction or organization that has cooperated in the development of these materials, makes any warranty, express or implied, or assumes any legal liability or responsibility for the accuracy, completeness, or usefulness or any information, apparatus, product, software, or process disclosed, or represents that its use would not infringe privately owned rights. Reference herein to any specific commercial product, process, or service by trade name, trademark, manufacturer, or otherwise does not necessarily constitute or imply its endorsement, recommendation, or favoring by the United States Government or any agency thereof, or Battelle Memorial Institute. The views and opinions of authors expressed herein do not necessarily state or reflect those of the United States Government or any agency thereof.
PACIFIC NORTHWEST NATIONAL LABORATORY operated by BATTELLE for the UNITED STATES DEPARTMENT OF ENERGY under Contract DE-AC05-76RL01830
Released under the 3-Clause BSD license (see License.rst)