HyperNetX

<img src="https://raw.githubusercontent.com/pnnl/HyperNetX/master/docs/source/images/harrypotter_basic_hyp.png" align="right" width="300pt">

The HyperNetX (HNX) library provides classes and methods for the analysis and visualization of complex network data modeled as hypergraphs. The library generalizes traditional graph metrics. Documentation for HNX is available at: https://hypernetx.readthedocs.io/

HNX was originally developed by the Pacific Northwest National Laboratory for the Hypernets project as part of its High Performance Data Analytics (HPDA) program. It is currently maintained by scientists at PNNL, but contributions and bug fixes from the community are welcome and encouraged. Please see our Contributor's Guide for more information.

PNNL is operated by Battelle Memorial Institute under Contract DE-ACO5-76RL01830.

• Principal Developer and Designer: Brenda Praggastis
• Development Team: Brenda Praggastis, Audun Myers, Greg Roek, Ryan Danehy
• Visualization: Dustin Arendt, Ji Young Yun
• Principal Investigator: Cliff Joslyn
• Program Manager: Brian Kritzstein
• Principal Contributors (Design, Theory, Code): Sinan Aksoy, Dustin Arendt, Mark Bonicillo, Ryan Danehy, Helen Jenne, Cliff Joslyn, Nicholas Landry, Audun Myers, Christopher Potvin, Brenda Praggastis, Emilie Purvine, Greg Roek, Mirah Shi, Francois Theberge, Ji Young Yun

The code in this repository is intended to support researchers modeling data as hypergraphs. We have a growing community of users and contributors. HNX is a primary contributor to the Hypergraph Interchange Format (HIF), a json schema for sharing data modeled as hypergraphs. The specification and sample notebooks may be found here: https://github.com/pszufe/HIF-standard/tree/main Other hypergraph libraries using this standard are listed below:

• HypergraphX (HGX) (Python)
• CompleX Group Interactions (XGI) (Python)
• SimpleHypergraphs.jl (Julia)
• Hypergraph-Analysis-Toolbox(HAT) (Python)

For questions and comments about HNX contact the developers directly at: hypernetx@pnnl.gov.

Summary - Release highlights - HNX 2.3

HyperNetX 2.3. is the latest, stable release. The core library has been refactored to take better advantage of Pandas Dataframes, improve readability and maintainability, address bugs, and make it easier to change. New features have been added, most notably the ability to add and remove edges, nodes, and incidences.

Version 2.3 is not backwards compatible. Objects constructed using earlier versions can be imported using their incidence dictionaries and/or property datafames.

What's New

1. Hypergraph now supports adding and removing edges, nodes, and incidences
2. Hypergraph also supports the sum, difference, union, and intersection of a Hypergraph to another Hypergraph
3. New factory methods to support the Hypergraph constructor
4. EntitySet has been replaced by HypergraphView
5. IncidenceStore and PropertyStore are new classes that maintain the structure and attributes of a Hypergraph
6. Hypergraph constructors accept cell, edge, and node metadata.

What's Changed

1. HNX now requires Python ">=3.10,<4.0.0"
2. HNX core libraries have been updated
3. Updated tutorials
4. The static and dynamic distinctions no longer exist. All hypergraphs use the same underlying data structure, supported by Pandas dataFrames. All hypergraphs maintain a state_dict to avoid repeating computations.
5. The nwhy optimizations are no longer supported.

Tutorials Available for Colab

Google Colab

<a href="https://colab.research.google.com/github/pnnl/HyperNetX/blob/master/tutorials/basic/Basic%201%20-%20HNX%20Basics.ipynb" target="_blank"> <img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/> <span >Basic 1 - HNX Basics</span> </a> <br> <a href="https://colab.research.google.com/github/pnnl/HyperNetX/blob/master/tutorials/basic/Basic%202%20-%20Visualization%20Methods.ipynb" target="_blank"> <img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/> <span >Basic 2 - Visualization Methods</span> </a> <br> <a href="https://colab.research.google.com/github/pnnl/HyperNetX/blob/master/tutorials/basic/Basic%203%20-%20LesMis%20Case%20Study.ipynb" target="_blank"> <img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/> <span >Basic 3 - LesMis Case Study</span> </a> <br> <a href="https://colab.research.google.com/github/pnnl/HyperNetX/blob/master/tutorials/basic/Basic%204%20-%20LesMis%20Visualizations-BookTour.ipynb" target="_blank"> <img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/> <span >Basic 4 - LesMis Visualizations-Book Tour</span> </a> <br> <a href="https://colab.research.google.com/github/pnnl/HyperNetX/blob/master/tutorials/basic/Basic%205%20-%20HNX%20attributed%20hypergraph.ipynb" target="_blank"> <img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/> <span >Basic 5 - HNX attributed hypergraph</span> </a> <br> <a href="https://colab.research.google.com/github/pnnl/HyperNetX/blob/master/tutorials/basic/Basic%206%20-%20Hypergraph%20Arithmetic.ipynb" target="_blank"> <img src="https://colab.research.google.com/assets/colab-badge.svg" alt="Open In Colab"/> <span >Basic 6 - Hypergraph Arithmetic.ipynb</span> </a> <br>

Jupyter Notebooks

Additional tutorials that can be run as Jupyter Notebooks are found under tutorials.

Installation

The recommended installation method for most users is to create a virtual environment and install HyperNetX from PyPi.

HyperNetX may be cloned or forked from GitHub.

Prerequisites

HyperNetX officially supports Python >=3.10,<4.0.0

Create a virtual environment

Using venv

python -m venv venv-hnx
source venv-hnx/bin/activate

Using Anaconda

conda create -n venv-hnx python=3.11 -y
conda activate venv-hnx

Using virtualenv

virtualenv venv-hnx
source venv-hnx/bin/activate

For Windows Users

On both Windows PowerShell or Command Prompt, you can use the following command to activate your virtual environment:

.\env-hnx\Scripts\activate

To deactivate your environment, use:

.\env-hnx\Scripts\deactivate

Installing HyperNetX

Regardless of how you install HyperNetX, ensure that your environment is activated and that you are running Python ">=3.10,<4.0.0".

Installing from PyPi

pip install hypernetx

Installing from Source

Ensure that you have git installed.

git clone https://github.com/pnnl/HyperNetX.git
cd HyperNetX

# Create a virtual environment
make venv
source venv-hnx/bin/activate

# install required dependencies
make install

Using HyperNetX on Docker

As an alternative to installing HyperNetX, you can use the officially supported HyperNetX Docker image maintained at DockerHub. Use the image to quickly start HyperNetX in a Docker container. The container starts a Jupyter Notebook that has the latest version of HyperNetX and HNXWidget installed; it also contains all the HyperNetX tutorials.

Run the Container

• Using Docker CLI, run the container in the foreground:

docker run -it --rm -p 8888:8888 -v "${PWD}":/home/jovyan/work hypernetx/hypernetx:latest

• Alternatively, you can create a docker-compose.yml file with the following:

version: '3'

services:
  hypernetx:
    image: hypernetx/hypernetx:latest
    ports:
      - "8888:8888"
    tty: true
    stdin_open: true
    volumes:
      - "${PWD}:/home/jovyan/work"

Once docker-compose.yml is created, run the container:

docker-compose up

Open Jupyter Notebook

After the container has started, access the HyperNetX Jupyter Notebooks by opening the following URL in a browser:

http://localhost:8888/tree

Development

As a developer, set up your environment using either the standard pip tool or Poetry.

Using Pip

Setup virtual environment and install HNX

Create a virtual environement. Then install an editable version of HNX and also install additional dependencies to support testing and jupyter notebooks:

python -m venv venv-hnx
source venv-hnx/bin/activate
pip install -e .
pip install -r requirements.txt

As an alternative, you can also install all these requirements in one Make target:

make venv
source venv-hnx/bin/activate
make install

Setup pre-commit

Use the pre-commit framework to automatically point out issues and resolve those issues before code review. It is highly recommended to install pre-commit in your development environment so that issues with your code can be found before you submit a pull