diff --git a/.cz.toml b/.cz.toml
index aa6714ca..1e161e97 100644
--- a/.cz.toml
+++ b/.cz.toml
@@ -1,8 +1,8 @@
[tool.commitizen]
name = "cz_conventional_commits"
-version = "2.2.0"
+version = "2.3.0"
version_files = [
- "setup.py",
+ "pyproject.toml",
"docs/source/conf.py",
"hypernetx/__init__.py"
]
diff --git a/.github/workflows/cff.yml b/.github/workflows/cff.yml
new file mode 100644
index 00000000..b493cf0b
--- /dev/null
+++ b/.github/workflows/cff.yml
@@ -0,0 +1,20 @@
+on:
+ push:
+ paths:
+ - CITATION.cff
+ workflow_dispatch:
+
+name: CITATION.cff
+jobs:
+ Validate-CITATION-cff:
+ runs-on: ubuntu-latest
+ name: Validate CITATION.cff
+ env:
+ GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+
+ steps:
+ - name: Checkout
+ uses: actions/checkout@v3
+
+ - name: Validate CITATION.cff
+ uses: dieghernan/cff-validator@v3
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index b8826ea6..ce188394 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -1,5 +1,4 @@
-name: Continuous Integration
-
+name: Run tests, linters, formatters
on:
push:
@@ -21,18 +20,14 @@ env:
LC_ALL: en_US.utf-8
jobs:
-
run-tests:
-
strategy:
matrix:
- os: [ubuntu-22.04, macos-12, windows-2022]
- python: ['3.8', '3.9', '3.10', '3.11']
-
+ os: [ubuntu-latest, macos-latest]
+ python: ['3.10', '3.11', '3.12']
runs-on: ${{ matrix.os }}
steps:
-
- run: |
echo "This workflow was triggered by: $TRIGGER_PERSON"
env:
@@ -41,28 +36,35 @@ jobs:
- run: echo "🐧 This job is now running on a ${{ runner.os }} server hosted by GitHub!"
- run: echo "🔎 The name of your branch is ${{ github.ref }} and your repository is ${{ github.repository }}."
- - name: Checkout
- uses: actions/checkout@v3
+ #----------------------------------------------
+ # check-out repo and set-up python
+ #----------------------------------------------
+ - name: Check out repository
+ uses: actions/checkout@v4
- name: Set up Python ${{ matrix.python }}
- uses: actions/setup-python@v4
+ id: setup-python
+ uses: actions/setup-python@v5
with:
python-version: ${{ matrix.python }}
- - name: Install Pylint
- run: pip install pylint
-
- # https://github.com/pre-commit/action
- - name: Run pre-commit hooks
- uses: pre-commit/action@v3.0.0
-
- - name: Run tests
- run: |
- make test-ci-github
- - name: Install documentation dependencies
- run: |
- pip install sphinx sphinx_rtd_theme
- pip install .'[documentation]'
- - name: Check documentation build
+ #----------------------------------------------
+ # ----- install & configure poetry -----
+ #----------------------------------------------
+ - name: Install Poetry
+ uses: snok/install-poetry@v1
+ with:
+ virtualenvs-create: true
+ virtualenvs-in-project: true
+ installer-parallel: true
+ #----------------------------------------------
+ # install other testing dependencies
+ #----------------------------------------------
+ - name: Install tox, pytest-github, tox-gh-actions
+ run: pip install 'tox>=4.4.11' 'pytest-github-actions-annotate-failures>=0.1.7' 'tox-gh-actions'
+ #----------------------------------------------
+ # Run tests, linters defined in Tox
+ #----------------------------------------------
+ - name: Run tests, linters
run: |
- sphinx-build docs/source _build
+ tox
diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
index 46baff65..aeee0efb 100644
--- a/.github/workflows/documentation.yml
+++ b/.github/workflows/documentation.yml
@@ -1,19 +1,60 @@
name: Docs
+
on: [push, workflow_dispatch]
+
permissions:
contents: write
+
jobs:
- docs:
+ test:
runs-on: ubuntu-latest
steps:
- - uses: actions/checkout@v3
- - uses: actions/setup-python@v3
+ #----------------------------------------------
+ # check-out repo and set-up python
+ #----------------------------------------------
+ - name: Check out repository
+ uses: actions/checkout@v4
+ - name: Set up python
+ id: setup-python
+ uses: actions/setup-python@v5
+ with:
+ python-version: '3.11.8'
+ #----------------------------------------------
+ # ----- install & configure poetry -----
+ #----------------------------------------------
+ - name: Install Poetry
+ uses: snok/install-poetry@v1
+ with:
+ virtualenvs-create: true
+ virtualenvs-in-project: true
+ installer-parallel: true
+
+ #----------------------------------------------
+ # load cached venv if cache exists
+ #----------------------------------------------
+ - name: Load cached venv
+ id: cached-poetry-dependencies
+ uses: actions/cache@v4
+ with:
+ path: .venv
+ key: venv-${{ runner.os }}-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('**/poetry.lock') }}
+ #----------------------------------------------
+ # install dependencies if cache does not exist
+ #----------------------------------------------
- name: Install dependencies
- run: |
- pip install .'[documentation]'
+ if: steps.cached-poetry-dependencies.outputs.cache-hit != 'true'
+ run: poetry install --no-interaction --no-root
+ #----------------------------------------------
+ # install your root project, if required
+ #----------------------------------------------
+ - name: Install project
+ run: poetry install --all-extras --no-interaction --with docs
+ #----------------------------------------------
+ # publish documentation
+ #----------------------------------------------
- name: Sphinx build
run: |
- sphinx-build docs/source _build
+ poetry run sphinx-build docs/source _build
- name: Deploy
if: github.head_ref == 'master'
uses: peaceiris/actions-gh-pages@v3
diff --git a/.github/workflows/publish-to-pypi.yml b/.github/workflows/publish-to-pypi.yml
index e765ddc0..6c5990cd 100644
--- a/.github/workflows/publish-to-pypi.yml
+++ b/.github/workflows/publish-to-pypi.yml
@@ -17,7 +17,6 @@ permissions:
jobs:
deploy:
-
runs-on: ubuntu-latest
steps:
@@ -25,39 +24,18 @@ jobs:
- run: echo "🐧 This job is now running on a ${{ runner.os }} server hosted by GitHub!"
- run: echo "🔎 The name of your branch is ${{ github.ref }} and your repository is ${{ github.repository }}."
- run: echo "Building wheel from tag ${{ github.ref_name }}"
+ - uses: actions/checkout@v4
- - uses: actions/checkout@v3
- - name: Set up Python
- uses: actions/setup-python@v4
- with:
- python-version: "3.11"
-
- - name: Install pypa/build
- run: >-
- python3 -m
- pip install
- build
- --user
-
- - name: Build a binary wheel and a source tarball
- run: >-
- python3 -m
- build
- --sdist
- --wheel
- --outdir dist/
- .
-
- - name: Publish distribution 📦 to Test PyPI
- uses: pypa/gh-action-pypi-publish@release/v1
+ - name: Build and publish distribution 📦 to Test PyPI
+ uses: JRubics/poetry-publish@v2.0
with:
- password: ${{ secrets.TEST_PYPI_API_TOKEN }}
- repository-url: https://test.pypi.org/legacy/
+ python_version: "3.11.8"
+ pypi_token: ${{ secrets.TEST_PYPI_API_TOKEN }}
+ repository_name: "testpypi"
+ repository_url: "https://test.pypi.org/legacy/"
- - name: Publish distribution 📦 to PyPI
- if: startsWith(github.ref, 'refs/tags')
- uses: pypa/gh-action-pypi-publish@release/v1
+ - name: Build and publish distribution 📦 to PyPI
+ uses: JRubics/poetry-publish@v2.0
with:
- password: ${{ secrets.PYPI_API_TOKEN }}
- verbose: true
- print-hash: true
+ python_version: "3.11.18"
+ pypi_token: ${{ secrets.PYPI_API_TOKEN }}
diff --git a/.gitignore b/.gitignore
index 75d1a1a4..891e468e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -39,3 +39,5 @@ docs/build
coverage.xml
cov.syspath.txt
*.whl
+*dogsAndcats*
+pytest_notebooks.xml
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 4a0c63da..20b99374 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -13,3 +13,7 @@ repos:
- id: trailing-whitespace
exclude: ^(docs/|hypernetx.egg-info/|setup.cfg)
- id: check-merge-conflict
+- repo: https://github.com/psf/black
+ rev: 24.3.0
+ hooks:
+ - id: black
diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 00000000..eff4b43d
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,328 @@
+# Changelog
+
+## 2.3.0 - 2023-05-16
+
+### Changed
+
+- Update Glossary with new terms and figure
+- Update Hypergraph docstrings
+- Refactor and add more tests
+- Update Visualization Tutorial
+- Change required Python version to ^3.10,<=3.12
+- Upgrade core dependencies
+- Update Tutorial 10, Hypergraph Modularity
+
+### Added
+
+- Add functionality to add and remove nodes, edges, and incidences on Hypergraph
+- Add Hypergraph arithmetic operations such as sum, difference, union, intersection
+- Add Hypergraph Arithmetic Operations tutorial
+- Add internal classes, IncidenceStore and PropertyStore, to support HypergraphView
+- Add new factory methods to support the creation of Hypergraph objects
+- Add support for Poetry to manage packaging, build, publishing, and environments
+
+### Removed
+
+- Remove EntitySet and replaced with HypergraphView
+- Remove setup.cfg and replaced with pyproject.toml
+
+### Fixed
+
+- Update usage of deprecated NetworkX methods
+
+#### Changelog from 2.2.0 to 2.3.0
+
+The following logs were generated using `git log v2.2.0..HEAD --pretty=format:"- %s (%h, %an, %ad)"`
+
+- updated glossary to remove duplicate terms and docstring to fix spelling (34f047a, Brenda Praggastis, Wed May 15 17:15:52 2024 -0700)
+- updated doc strings for s-connected components (d125c45, Brenda Praggastis, Wed May 15 17:07:33 2024 -0700)
+- updated the glossary, so it should be good now (771240e, Brenda Praggastis, Wed May 15 17:03:08 2024 -0700)
+- Pull request #179: Adding demo with attributes (7e253a0, Bonicillo, Mark A, Wed May 15 22:16:04 2024 +0000)
+- Pull request #178: Defaults2 (50d890d, Bonicillo, Mark A, Wed May 15 22:10:33 2024 +0000)
+- Merge branch 'develop' into defaults_backup (1e1c2a1, Brenda Praggastis, Wed May 15 15:04:05 2024 -0700)
+- Merge branch 'defaults_backup' into defaults_backup (001bc1e, Brenda Praggastis, Wed May 15 15:03:59 2024 -0700)
+- hypview added user defined props (19707ac, Brenda Praggastis, Wed May 15 13:56:51 2024 -0700)
+- adding two new tutorials under basic (773fa84, audun myers, Wed May 15 16:50:08 2024 -0400)
+- Pull request #177: Defaults backup (9516ca8, Bonicillo, Mark A, Wed May 15 20:46:04 2024 +0000)
+- Update tests (eedba46, Mark Bonicillo, Wed May 15 12:35:47 2024 -0700)
+- test (a2b8e3c, Brenda Praggastis, Wed May 15 13:18:53 2024 -0700)
+- created set_defaults (6f17867, Brenda Praggastis, Wed May 15 13:12:56 2024 -0700)
+- Merge branch 'defaults' of into defaults (145581e, Brenda Praggastis, Wed May 15 12:36:47 2024 -0700)
+- removed default_properties_df (0b2ccea, Brenda Praggastis, Wed May 15 12:36:32 2024 -0700)
+- Update tests (70e52f9, Mark Bonicillo, Wed May 15 12:35:47 2024 -0700)
+- Update Tutorial 2 - Visualization Methods.ipynb (a71c259, audun myers, Wed May 15 15:26:00 2024 -0400)
+- created self.defaults (793b715, Brenda Praggastis, Wed May 15 11:28:38 2024 -0700)
+- Pull request #176: Glossary (357d339, Bonicillo, Mark A, Wed May 15 18:24:33 2024 +0000)
+- Merge branch 'develop' into glossary (65cd70b, Mark Bonicillo, Wed May 15 11:21:26 2024 -0700)
+- Pull request #175: Fix tutorial imports (a98e917, Bonicillo, Mark A, Wed May 15 18:04:42 2024 +0000)
+- adding figure to glossary describing HNX structure (c5588ba, audun myers, Wed May 15 14:02:17 2024 -0400)
+- Fix tutorial imports (b248be0, Mark Bonicillo, Wed May 15 10:47:34 2024 -0700)
+- new glossary again (d2eb5b1, Brenda Praggastis, Wed May 15 10:52:55 2024 -0700)
+- new glossary (66ff679, Brenda Praggastis, Wed May 15 10:42:18 2024 -0700)
+- new glossary (e5d8972, Brenda Praggastis, Wed May 15 10:34:07 2024 -0700)
+- glossary and classes init updated (9d94a8b, Brenda Praggastis, Wed May 15 09:59:46 2024 -0700)
+- Pull request #172: Add, update docstrings in hypergraph (27ed0fb, Bonicillo, Mark A, Wed May 15 16:49:55 2024 +0000)
+- Merge remote-tracking branch 'develop' into update-hypergraph-docstrings (501247a, Mark Bonicillo, Mon May 13 15:44:03 2024 -0700)
+- Pull request #174: Add tests for union, intersection; update other tests (75153a2, Bonicillo, Mark A, Mon May 13 22:35:06 2024 +0000)
+- Add tests for union, intersection; update other tests (1bfe844, Mark Bonicillo, Mon May 13 15:20:48 2024 -0700)
+- Merge remote-tracking branch 'develop' into update-hypergraph-docstrings (5622b8e, Mark Bonicillo, Thu May 9 08:54:06 2024 -0700)
+- Pull request #173: Ndarray (55e7321, Bonicillo, Mark A, Thu May 9 06:59:23 2024 +0000)
+- Fix import error in ndarray factory method (54b6704, Mark Bonicillo, Wed May 8 16:59:28 2024 -0700)
+- Add ndarray test on constructor; fix docstrings (c515db1, Mark Bonicillo, Wed May 8 16:55:28 2024 -0700)
+- Fix malformed table (1594fc0, Mark Bonicillo, Wed May 8 16:11:49 2024 -0700)
+- Update LICENSE.rst to 2024 (4277fef, Mark Bonicillo, Wed May 8 15:50:34 2024 -0700)
+- Fix math syntax (1cdbc44, Mark Bonicillo, Wed May 8 15:40:21 2024 -0700)
+- Refactor matrix methods; update tests and docstrings (0104565, Mark Bonicillo, Wed May 8 14:29:11 2024 -0700)
+- Remove typing from Hypergraph constructor (4279ae4, Mark Bonicillo, Wed May 8 10:38:23 2024 -0700)
+- Update remove methods and its docstrings; updates tests (4185dda, Mark Bonicillo, Tue May 7 17:08:42 2024 -0700)
+- updated docstrings (01998e9, Brenda Praggastis, Mon May 6 17:02:09 2024 -0700)
+- add ndarray factory method (d65f52d, Brenda Praggastis, Mon May 6 16:27:17 2024 -0700)
+- Add, update docstrings in hypergraph (cf3a299, Mark Bonicillo, Mon May 6 11:55:29 2024 -0700)
+- Pull request #171: Update documentation (4e1a27e, Bonicillo, Mark A, Thu May 2 21:27:04 2024 +0000)
+- Update Python version references in docs; update docs Makefile (a58f0f5, Mark Bonicillo, Thu May 2 14:05:59 2024 -0700)
+- Update long description (29a42e0, Mark Bonicillo, Thu May 2 13:07:22 2024 -0700)
+- Fix Sphinx errors, warnings on docstrings (f33a152, Mark Bonicillo, Wed May 1 14:09:28 2024 -0700)
+- Remove references to non-existing modules; fix docstrings (e8a0ea0, Mark Bonicillo, Tue Apr 30 15:06:54 2024 -0700)
+- Remove helpers.py; remove unused imports (f26b58d, Mark Bonicillo, Mon Apr 29 16:24:59 2024 -0700)
+- Remove EntitySet references; remove old AttrList (3646fb0, Mark Bonicillo, Mon Apr 29 16:03:19 2024 -0700)
+- Pull request #170: Upgrade Python to 3.10; upgrade core dependencies (c819ca2, Bonicillo, Mark A, Thu May 2 18:55:24 2024 +0000)
+- Upgrade Python to 3.10; upgrade core dependencies (bab41d5, Mark Bonicillo, Thu May 2 10:42:50 2024 -0700)
+- Pull request #169: Additems (be63722, Bonicillo, Mark A, Wed May 1 21:20:15 2024 +0000)
+- Minor cleanup (9222850, Mark Bonicillo, Wed May 1 14:16:35 2024 -0700)
+- added import for deepcopy (aa9fab3, Brenda Praggastis, Wed May 1 13:58:23 2024 -0700)
+- updated copy in PropertyStore to deep copy misc_properties (5687346, Brenda Praggastis, Wed May 1 13:36:19 2024 -0700)
+- updated construct from stores to return inplace or deep copy (116f41b, Brenda Praggastis, Wed May 1 13:35:03 2024 -0700)
+- restricting todataframe to only return on objects actually in the hypergraph (1f1921f, Brenda Praggastis, Wed May 1 13:32:47 2024 -0700)
+- Pull request #167: added items property to hyp_view and intersection and union to hypergraph (c519d05, Praggastis, Brenda, Tue Apr 30 20:05:49 2024 +0000)
+- Fix and refactor sum method; add tests (b178da6, Mark Bonicillo, Tue Apr 30 11:18:47 2024 -0700)
+- Merge branch 'develop', remote-tracking branch 'stash' into bpedits3 (787314d, Mark Bonicillo, Tue Apr 30 11:37:48 2024 -0700)
+- added items property to hyp_view and intersection and union to hypergraph (5bab9d7, Brenda Praggastis, Mon Apr 29 15:57:44 2024 -0700)
+- Pull request #165: Fix bugs, refactor methods in Hypergraph; add and update tests for Hypergraph (abd35cd, Bonicillo, Mark A, Mon Apr 29 20:47:19 2024 +0000)
+- Fix bug in get_cell_properties; update tests (65949c6, Mark Bonicillo, Wed Apr 24 13:58:13 2024 -0700)
+- Cleanup tests (d126e8b, Mark Bonicillo, Wed Apr 24 12:01:09 2024 -0700)
+- Pull request #166: Bpedits2 (6fd94ec, Praggastis, Brenda, Mon Apr 29 17:17:15 2024 +0000)
+- Run linter (b5dd816, Mark Bonicillo, Mon Apr 29 10:12:12 2024 -0700)
+- updates collapse to put user defined keys for equivalence classes first and allow for aggregations. (072770c, Brenda Praggastis, Fri Apr 26 18:42:56 2024 -0700)
+- replaced deep copy on to_dataframe since it wasn't copying misc properties (f825248, Brenda Praggastis, Fri Apr 26 18:41:55 2024 -0700)
+- fixes collapse so that chosen key will always be listed first (85cc730, Brenda Praggastis, Fri Apr 26 18:40:21 2024 -0700)
+- changed to_dataframe to only return a complete clone of dataframe - fixes misc properties not deep copying (783edd3, Brenda Praggastis, Fri Apr 26 18:39:19 2024 -0700)
+- Merge branch 'develop' into bpedits (293ee43, Brenda Praggastis, Fri Apr 26 14:19:57 2024 -0700)
+- note TODO and update on inplace (0cadce0, Brenda Praggastis, Fri Apr 26 14:12:44 2024 -0700)
+- Pull request #164: Fixing factory bug (db3576f, Myers, Audun D, Wed Apr 24 19:12:04 2024 +0000)
+- Revert "Adding init files to tests folder" (38bc621, Mark Bonicillo, Wed Apr 24 12:04:55 2024 -0700)
+- Linter (d76cd2a, Mark Bonicillo, Wed Apr 24 12:03:27 2024 -0700)
+- fixing edges and nodes methods in incicdence store (475f066, audun myers, Wed Apr 24 14:19:57 2024 -0400)
+- Adding init files to tests folder (068b248, audun myers, Wed Apr 24 11:31:00 2024 -0400)
+- Update factory.py (9348e3d, audun myers, Wed Apr 24 10:48:38 2024 -0400)
+- Pull request #163: Add __eq__ method to Hypergraph; add tests for clone (62e9e2a, Bonicillo, Mark A, Tue Apr 23 22:29:59 2024 +0000)
+- Add __eq__ method; add tests for clone (a6da1e3, Mark Bonicillo, Thu Apr 18 11:34:38 2024 -0700)
+- Pull request #162: Fix bug in components method; update tests (881c7ba, Bonicillo, Mark A, Tue Apr 23 21:51:29 2024 +0000)
+- Fix bug in components method; update tests (6c302f2, Mark Bonicillo, Tue Apr 23 14:43:57 2024 -0700)
+- Recovered changes to hypergraph.py (5909d07, Brenda Praggastis, Thu Apr 18 12:50:26 2024 -0700)
+- Pull request #161: Docs (a0813bc, Praggastis, Brenda, Thu Apr 18 18:41:11 2024 +0000)
+- Run linter (0852180, Mark Bonicillo, Thu Apr 18 11:37:15 2024 -0700)
+- refactored tests to be consistent with new core code (274d7ad, Brenda Praggastis, Wed Apr 17 18:55:56 2024 -0700)
+- updated modules to be consistent with new core code (14b8498, Brenda Praggastis, Wed Apr 17 18:55:38 2024 -0700)
+- updates to hypergraph and incidence store include doc string improvements and refactored collapse methods (3a53d74, Brenda Praggastis, Wed Apr 17 18:55:18 2024 -0700)
+- Merge branch 'develop' into docs (b9d801c, Brenda Praggastis, Wed Apr 17 11:26:23 2024 -0700)
+- updated hypergraph doc strings (fb1a3b9, Brenda Praggastis, Wed Apr 17 11:25:36 2024 -0700)
+- Pull request #160: removed inplace and changed remove to _remove for internal use (8adb1a7, Praggastis, Brenda, Wed Apr 17 18:20:28 2024 +0000)
+- Run linter (4270e44, Mark Bonicillo, Wed Apr 17 11:15:42 2024 -0700)
+- added ability to add a nested dictionary for nodes to edges (8a3244b, Brenda Praggastis, Tue Apr 16 21:11:09 2024 -0700)
+- added clone method to create a copy on which to make changes. (c18687d, Brenda Praggastis, Tue Apr 16 21:06:23 2024 -0700)
+- Pull request #159: Update tests add_* functionality (5227d27, Bonicillo, Mark A, Wed Apr 17 18:00:18 2024 +0000)
+- Fix bugs; refactor code; update tests (4a273c8, Mark Bonicillo, Wed Apr 17 10:37:05 2024 -0700)
+- Fix bug in PropertyStore; update add_edge tests (63e671d, Mark Bonicillo, Tue Apr 16 16:57:20 2024 -0700)
+- removed inplace and changed remove to _remove for internal use (c1a52cf, Brenda Praggastis, Tue Apr 16 13:47:42 2024 -0700)
+- Add tests for add_node and add_incidences (366f136, Mark Bonicillo, Tue Apr 16 14:11:55 2024 -0700)
+- Pull request #158: Update tests (f4c98ca, Bonicillo, Mark A, Tue Apr 16 00:08:16 2024 +0000)
+- Add test-core target (6fff636, Mark Bonicillo, Mon Apr 15 17:04:08 2024 -0700)
+- Update tests (1d6eba4, Mark Bonicillo, Mon Apr 15 11:02:12 2024 -0700)
+- Remove old notebooks (d3c6142, Mark Bonicillo, Thu Apr 11 11:19:52 2024 -0700)
+- Move tests to root-level (62f451d, Mark Bonicillo, Tue Apr 9 14:36:44 2024 -0700)
+- Pull request #157: Fix bugs in _add_item; add tests for add_edge (3a89c2c, Bonicillo, Mark A, Mon Apr 15 23:52:07 2024 +0000)
+- Fix bugs in _add_item; add tests for add_edge (857130a, Mark Bonicillo, Mon Apr 15 14:53:08 2024 -0700)
+- Pull request #156: Fix bug in Hypergraph.dual; update tests (d42a698, Bonicillo, Mark A, Fri Apr 12 15:27:05 2024 +0000)
+- Fix bug in Hypergraph.dual; update tests (111721c, Mark Bonicillo, Thu Apr 11 11:09:47 2024 -0700)
+- Pull request #155: updating index column naming for factory (7249e43, Myers, Audun D, Thu Apr 11 18:37:23 2024 +0000)
+- Fix formatting (3070166, Mark Bonicillo, Thu Apr 11 11:36:21 2024 -0700)
+- Fixed PR comments from mark (e9dc62d, audun myers, Thu Apr 11 14:24:19 2024 -0400)
+- updating index column naming for factory (20042b0, audun myers, Thu Apr 11 12:26:17 2024 -0400)
+- Pull request #154: difference_function fix (e6220d2, Praggastis, Brenda, Wed Apr 10 04:02:26 2024 +0000)
+- Add tests for difference method (307e062, Mark Bonicillo, Tue Apr 9 17:05:11 2024 -0700)
+- fixed difference of hypergraphs as it removed properties and shouldn't have (552ced6, Brenda Praggastis, Tue Apr 9 16:08:20 2024 -0700)
+- merged origin/develop into develop (890ca80, Brenda Praggastis, Tue Apr 9 15:10:16 2024 -0700)
+- Pull request #153: Infra update (370e671, Bonicillo, Mark A, Tue Apr 9 21:04:01 2024 +0000)
+- Move pytest config into pyproject (5012941, Mark Bonicillo, Tue Apr 9 13:39:12 2024 -0700)
+- Fix make targets (e51f4ca, Mark Bonicillo, Fri Apr 5 17:24:43 2024 -0700)
+- Add poetry (9591806, Mark Bonicillo, Mon Mar 25 11:19:36 2024 -0700)
+- Pull request #152: Updating factory to fix some nbugs and improve documentation (9d3d22a, Myers, Audun D, Tue Apr 9 20:50:31 2024 +0000)
+- Run linter (bcfe9d0, Mark Bonicillo, Tue Apr 9 13:44:41 2024 -0700)
+- Delete testing_factory.ipynb (15ebb13, audun myers, Tue Apr 9 16:14:46 2024 -0400)
+- Create testing_factory.ipynb (a1bd873, audun myers, Tue Apr 9 16:10:13 2024 -0400)
+- updating factory to fix bugs (f2fb670, audun myers, Tue Apr 9 16:00:43 2024 -0400)
+- Pull request #151: Hg functionality (4a848f7, Bonicillo, Mark A, Tue Apr 9 19:44:30 2024 +0000)
+- Cleanup tutorial 9 (d374d02, Mark Bonicillo, Tue Apr 9 12:11:20 2024 -0700)
+- Fix image link in tutorials 8 (ee33355, Mark Bonicillo, Tue Apr 9 12:04:59 2024 -0700)
+- Fix call to toplexes method in tutorial 1 (dd8ea58, Mark Bonicillo, Tue Apr 9 11:50:19 2024 -0700)
+- Update set and get methods on property store; fix bug (3311d58, Mark Bonicillo, Mon Apr 8 10:25:10 2024 -0700)
+- Run linter (9f23c13, Mark Bonicillo, Mon Apr 8 08:13:03 2024 -0700)
+- updated docs (4623ac7, Brenda Praggastis, Sun Apr 7 18:52:16 2024 -0700)
+- updated test_hypergraph so that toplexes test works (657b8ef, Brenda Praggastis, Sun Apr 7 18:51:54 2024 -0700)
+- hypergraph methods for add and remove and toplexes were updated , replaced keyword share_properties with inplace (9bd91f1, Brenda Praggastis, Sun Apr 7 18:51:27 2024 -0700)
+- added check for items not in incidence dataframe (efc0b64, Brenda Praggastis, Sun Apr 7 18:48:50 2024 -0700)
+- updated property_store so that _add_row can take multiple properties as kwargs. added copy to Property Store (0ceb77b, Brenda Praggastis, Sun Apr 7 18:45:27 2024 -0700)
+- Pull request #150: Tutorials no infra (3491c6c, Bonicillo, Mark A, Sat Apr 6 00:12:02 2024 +0000)
+- replaced Tutorial 10 with Francois's new version (4276532, Brenda Praggastis, Fri Apr 5 10:47:16 2024 -0700)
+- Update to_dataframe, add hypergraph_view tests (4916497, Mark Bonicillo, Fri Apr 5 16:52:24 2024 -0700)
+- removed files that don't belong in top level of tutorials (c863e84, Brenda Praggastis, Thu Apr 4 18:25:25 2024 -0700)
+- updated Tutorial 9 and corresponding module. (b7933eb, Brenda Praggastis, Thu Apr 4 18:21:44 2024 -0700)
+- updated Tutorial 10 (8397e9c, Brenda Praggastis, Thu Apr 4 18:00:37 2024 -0700)
+- changed NList to AttrList to be consistent with previous version. (83dad8a, Brenda Praggastis, Thu Apr 4 14:22:59 2024 -0700)
+- Run linter (d03c651, Mark Bonicillo, Thu Apr 4 09:43:43 2024 -0700)
+- Tutorial 8 updates (9f70fea, Brenda Praggastis, Wed Apr 3 17:41:35 2024 -0700)
+- updated tutorials 5,6,7 (5ddb33b, Brenda Praggastis, Wed Apr 3 12:50:27 2024 -0700)
+- created to_dataframe method and removed property_view from property store (bd12e4d, Brenda Praggastis, Wed Apr 3 12:12:34 2024 -0700)
+- updated tutorial 2 (1a3d424, Brenda Praggastis, Wed Apr 3 11:44:33 2024 -0700)
+- updated vis (6421cdf, Brenda Praggastis, Wed Apr 3 11:21:27 2024 -0700)
+- update tutorials again (dbdfe71, Brenda Praggastis, Wed Apr 3 10:29:17 2024 -0700)
+- Remove setup.py (4ccbd11, Mark Bonicillo, Tue Apr 2 13:57:26 2024 -0700)
+- Run formatter (10a99f2, Mark Bonicillo, Tue Apr 2 12:01:46 2024 -0700)
+- Update tox.ini (10c259a, Mark Bonicillo, Tue Apr 2 11:41:08 2024 -0700)
+- Update ci.yml (46aed8d, Mark Bonicillo, Mon Apr 1 13:16:42 2024 -0700)
+- Fix github workflows (f655be4, Mark Bonicillo, Mon Apr 1 12:51:15 2024 -0700)
+- Cleanup required dependencies (a60bff3, Mark Bonicillo, Mon Apr 1 11:32:46 2024 -0700)
+- Update cz file (bad6401, Mark Bonicillo, Tue Mar 26 15:40:57 2024 -0700)
+- Update GH workflows (2eaa364, Mark Bonicillo, Tue Mar 26 15:36:23 2024 -0700)
+- Cleanup Makefile (d22d8a6, Mark Bonicillo, Mon Mar 25 23:51:17 2024 -0700)
+- testing new docs-deps (dd6436f, Mark Bonicillo, Mon Mar 25 22:46:23 2024 -0700)
+- testing (adb34e7, Mark Bonicillo, Mon Mar 25 22:26:24 2024 -0700)
+- Modify tox to integrate with poetry (7f6ee9d, Mark Bonicillo, Mon Mar 25 16:15:50 2024 -0700)
+- Add poetry (7703cf1, Mark Bonicillo, Mon Mar 25 11:19:36 2024 -0700)
+- Pull request #147: Hypergraph edit (638870a, Praggastis, Brenda, Mon Apr 1 21:59:00 2024 +0000)
+- removed old hypergraph code (1e1dbf7, Brenda Praggastis, Mon Apr 1 13:59:16 2024 -0700)
+- removed .github from .gitignore (3e1c8b6, Brenda Praggastis, Mon Apr 1 13:57:34 2024 -0700)
+- updated hypergraph from incidence matrix constructor (b9dbc0b, Brenda Praggastis, Fri Mar 29 18:08:47 2024 -0700)
+- Merge branch 'develop' into develop (d38b2ff, Brenda Praggastis, Wed Mar 27 12:40:53 2024 -0700)
+- removing notebooks not intended for sharing (126610b, Brenda Praggastis, Wed Mar 27 12:40:32 2024 -0700)
+- Pull request #145: Add HNX paper (d0a7e3d, Bonicillo, Mark A, Wed Mar 27 19:12:05 2024 +0000)
+- Add HNX paper (463d12f, Mark Bonicillo, Wed Mar 27 12:10:07 2024 -0700)
+- Pull request #144: Feature/hyp 367 (519c771, Bonicillo, Mark A, Wed Mar 27 18:54:43 2024 +0000)
+- Fix formatting (89c712b, Mark Bonicillo, Wed Mar 27 11:48:34 2024 -0700)
+- adding arithmetic for hypergraphs (29cfed8, Brenda Praggastis, Wed Mar 27 11:44:23 2024 -0700)
+- Bug fix: shouldn't require passing position for hyper-edges. (f93504f, Dustin Arendt, Tue Mar 26 14:51:52 2024 -0700)
+- Remove nwhy decorator reference (c180bd0, Mark Bonicillo, Mon Mar 25 09:24:08 2024 -0700)
+- Run linter; remove HNX_Paper (850ddd6, Mark Bonicillo, Mon Mar 25 09:18:30 2024 -0700)
+- updated hypergraph code class method constructors (f13a325, Brenda Praggastis, Fri Mar 22 14:36:00 2024 -0700)
+- Remove references to warn_nwhy deprecation decorator (f1c3e43, Mark Bonicillo, Fri Mar 22 11:43:24 2024 -0700)
+- Remove deprecated NetworkX functions (379bc19, Mark Bonicillo, Fri Mar 22 11:35:46 2024 -0700)
+- Remove unnecessary hypergraph test (3e70822, Mark Bonicillo, Fri Mar 22 11:11:56 2024 -0700)
+- Fix incidence_store bug; move, update, and fix incidence store tests; (c05c4b4, Mark Bonicillo, Fri Mar 22 11:09:03 2024 -0700)
+- Remove EntitySet and tests (598c69c, Mark Bonicillo, Fri Mar 22 09:37:24 2024 -0700)
+- add incidences reference to access _E HypergraphView (0373ac5, Brenda Praggastis, Thu Mar 21 17:58:39 2024 -0700)
+- removing hypergraph_outline to avoid versioning issues. new code is on hypergraph.py now (2d1f6db, Brenda Praggastis, Thu Mar 21 17:49:01 2024 -0700)
+- centrality tutorial 5 is ready to go (aaef8dc, Brenda Praggastis, Thu Mar 21 17:47:26 2024 -0700)
+- Updated the tutorials in basic 1,3,4 to work with new code.. (c1a80f0, Brenda Praggastis, Thu Mar 21 17:32:10 2024 -0700)
+- moved old hypergraph code into hypergraph_2.0 and set hypergraph to match hypergraph_outline. updated dogsAndcats for testing (b6c230d, Brenda Praggastis, Thu Mar 21 16:33:16 2024 -0700)
+- updated tests to work with new hypergraph code. commented out _by_setsystem tests until they can be upgraded (791cf89, Brenda Praggastis, Thu Mar 21 16:32:19 2024 -0700)
+- updated collapse in incidence to separate functions for equivalence classes and collapse identical elements. user can now specify keys when collapsing (06bd85d, Brenda Praggastis, Thu Mar 21 16:31:24 2024 -0700)
+- added is_empty to match old behavior (fc6b6a6, Brenda Praggastis, Thu Mar 21 16:30:11 2024 -0700)
+- Refactor set property (f5bc644, Mark Bonicillo, Thu Mar 21 12:36:01 2024 -0700)
+- Add properties_uids method (aa263c4, Mark Bonicillo, Thu Mar 21 11:30:27 2024 -0700)
+- updated much of outline - time to start testing (b0b6055, Brenda Praggastis, Wed Mar 20 17:53:51 2024 -0700)
+- added implementation for weighted incidence matrix and incidence dataframe (ec8c369, Brenda Praggastis, Wed Mar 20 13:54:20 2024 -0700)
+- debugging new outline code (ac9127a, Brenda Praggastis, Wed Mar 20 10:32:37 2024 -0700)
+- Update tests and docstrings; cleanup code (04bb9a7, Mark Bonicillo, Wed Mar 20 10:23:59 2024 -0700)
+- adding functionality for collapsing and incidence matrix (c34278e, Brenda Praggastis, Tue Mar 19 20:19:37 2024 -0700)
+- Merge branch 'develop' into feature/hyp-367 (36590d6, Brenda Praggastis, Mon Mar 18 18:07:00 2024 -0700)
+- Pull request #143: HYP-396 Add CFF citation (b67b38b, Bonicillo, Mark A, Tue Mar 19 00:00:20 2024 +0000)
+- Update docs, add helper method, update tests (3642fa8, Mark Bonicillo, Mon Mar 18 13:53:20 2024 -0700)
+- Remove old propertystore and test (a4cfa30, Mark Bonicillo, Mon Mar 18 13:20:33 2024 -0700)
+- updating hypergraph_outline methods to work with draw) (dad6085, Brenda Praggastis, Mon Mar 18 10:29:10 2024 -0700)
+- updated to get basic functionality on hypergraph_outline. please review (47d6899, Brenda Praggastis, Sun Mar 17 16:23:54 2024 -0700)
+- Update set_property; update docs, tests (5f0bad5, Mark Bonicillo, Fri Mar 15 16:56:04 2024 -0700)
+- Updated factory to be more simple and allow indices to be provided. (3b13dd6, audun myers, Fri Mar 15 16:19:59 2024 -0400)
+- updates for simplifying factory and propertystore (2d60e4d, Brenda Praggastis, Fri Mar 15 08:13:15 2024 -0700)
+- fixed typo (54e887a, Brenda Praggastis, Thu Mar 14 15:19:56 2024 -0700)
+- updating for default properties (0e19ba7, Brenda Praggastis, Thu Mar 14 12:53:48 2024 -0700)
+- pulled and merged new content (044dddb, Brenda Praggastis, Thu Mar 14 11:18:59 2024 -0700)
+- fixing syntax errors (cc230af, Brenda Praggastis, Wed Mar 13 12:00:06 2024 -0700)
+- fixed syntax errors in 3 files (c016f3f, Brenda Praggastis, Wed Mar 13 08:57:29 2024 -0700)
+- Refactor Index param (9ed8b54, Mark Bonicillo, Wed Mar 13 15:05:19 2024 -0700)
+- changed uid column to 'uid' for edges and nodes and fixed index for uid_cols bug. (07c83af, audun myers, Wed Mar 13 14:21:35 2024 -0400)
+- HYP-396 Add CFF citation; add cff workflow and badge (44e06fa, Mark Bonicillo, Wed Mar 13 09:23:22 2024 -0700)
+- Adding level input to factory (e80403e, audun myers, Wed Mar 13 11:44:42 2024 -0400)
+- Add index param to PropertyStore (f947720, Mark Bonicillo, Tue Mar 12 17:03:16 2024 -0700)
+- Update property store, tests, notebook (4a9752a, Mark Bonicillo, Fri Mar 8 13:29:55 2024 -0800)
+- added list factory method (c400777, audun myers, Thu Mar 7 16:13:56 2024 -0500)
+- Added dictionary factory method and more examples (b43ec9e, audun myers, Thu Mar 7 15:39:29 2024 -0500)
+- updated factory to follow hypergraph_outline structure (0b5cf2e, audun myers, Thu Mar 7 14:31:57 2024 -0500)
+- removing tutorial to avoid conflicts (eab01de, Brenda Praggastis, Thu Mar 7 09:20:40 2024 -0800)
+- working on notebook (c0ea4d7, Brenda Praggastis, Thu Mar 7 09:18:37 2024 -0800)
+- updated hypergraph outline to notes from meeting (3dd9616, Brenda Praggastis, Wed Mar 6 14:11:26 2024 -0800)
+- updates from meeting (a53b7af, Brenda Praggastis, Wed Mar 6 12:06:21 2024 -0800)
+- updates (7ed7414, Brenda Praggastis, Wed Mar 6 10:41:14 2024 -0800)
+- updates on outline (052f029, Brenda Praggastis, Wed Mar 6 10:39:43 2024 -0800)
+- Run linter (4eadb9a, Mark Bonicillo, Wed Mar 6 09:11:38 2024 -0800)
+- returns empty list for nieghbors if level =2 (3c56622, audun myers, Wed Mar 6 10:37:38 2024 -0500)
+- Updating factory to have single dataframe to property store function (fe07fa1, audun myers, Wed Mar 6 10:36:13 2024 -0500)
+- Run linter (80fe95e, Mark Bonicillo, Tue Mar 5 13:26:55 2024 -0800)
+- Fix drawing module (d84d526, Mark Bonicillo, Tue Mar 5 13:10:49 2024 -0800)
+- Remove paper-related doc (76ffef3, Mark Bonicillo, Tue Mar 5 12:58:56 2024 -0800)
+- added outline of hypergraph constructor in hypergraph_outline.py (8943b7d, Brenda Praggastis, Tue Mar 5 11:12:07 2024 -0800)
+- merged develop into branch (ede25b2, Brenda Praggastis, Tue Mar 5 10:29:54 2024 -0800)
+- updated hypergraph outline with suggestions for factory methods (559e695, Brenda Praggastis, Tue Mar 5 10:23:14 2024 -0800)
+- updated test data (e5442db, Brenda Praggastis, Mon Mar 4 14:24:09 2024 -0800)
+- found small error in factory (6382c4d, audun myers, Fri Mar 1 17:10:18 2024 -0500)
+- added multiple fixes discussed in HNX meeting for factory methods (32f93f3, audun myers, Fri Mar 1 17:00:30 2024 -0500)
+- Revert "Add hypergraph_view factory method" (e2858fe, Mark Bonicillo, Wed Feb 28 12:37:19 2024 -0800)
+- Allow DataFramePropertyStore to accept regular or multiindex dfs; change properties to misc_properties (5cdb85c, Mark Bonicillo, Wed Feb 28 12:31:38 2024 -0800)
+- Finished adding all optional args to factory (747ca13, audun myers, Wed Feb 28 13:12:57 2024 -0500)
+- Add hypergraph_view factory method (d90b2c3, Mark Bonicillo, Wed Feb 28 08:30:02 2024 -0800)
+- Update property_store tests (b73e21f, Mark Bonicillo, Mon Feb 26 10:31:47 2024 -0800)
+- added all optional args for factory method (97ff5bd, audun myers, Mon Feb 26 12:06:41 2024 -0500)
+- small changes for better integration with hyp_view and existing code (4857324, Brenda Praggastis, Mon Feb 26 08:55:17 2024 -0800)
+- small modifications to integrate better with existing code and hyp_view (fd73f5b, Brenda Praggastis, Mon Feb 26 08:54:39 2024 -0800)
+- updates incorporating new property and incidence stores (15954cd, Brenda Praggastis, Mon Feb 26 08:53:55 2024 -0800)
+- updates (67b7edd, Brenda Praggastis, Fri Feb 23 15:51:08 2024 -0800)
+- updates (6a21358, Brenda Praggastis, Thu Feb 22 11:38:19 2024 -0800)
+- Update factory.py (1c2881b, audun myers, Fri Feb 23 16:45:17 2024 -0500)
+- Use MultiIndexDataframe for PropertyStore; update tests; add notebook (c9a94c6, Mark Bonicillo, Fri Feb 23 13:35:02 2024 -0800)
+- test nb and data (5e01079, Brenda Praggastis, Wed Feb 21 12:01:27 2024 -0800)
+- updates (ad7d792, Brenda Praggastis, Wed Feb 21 09:24:27 2024 -0800)
+- finished draft dataframe factory method. (c66e952, audun myers, Mon Feb 19 10:33:25 2024 -0500)
+- Implement DataFramePropertyStore; add tests (9a2e0f1, Mark Bonicillo, Fri Feb 16 01:03:21 2024 -0800)
+- updated attrlist (cf8ce22, Brenda Praggastis, Thu Feb 15 12:35:57 2024 -0800)
+- added methods (564abc1, Brenda Praggastis, Wed Feb 14 18:34:05 2024 -0800)
+- hiding files in gitignore (70b3eba, Brenda Praggastis, Wed Feb 14 17:25:41 2024 -0800)
+- slowly adding methods using proxies for incidence store and property store. (8f8f40d, Brenda Praggastis, Wed Feb 14 17:20:17 2024 -0800)
+- comments on incidence store (58d4c68, Brenda Praggastis, Wed Feb 14 11:30:18 2024 -0800)
+- updating view (d8c207e, Brenda Praggastis, Wed Feb 14 10:32:58 2024 -0800)
+- Added the contain_hyper_edges flag to extend hulls (rubber bands) around hyperedge positions. Useful for when the bipartite graph is passed in, e.g. with_additional_edges=H.bipartite() (73f9c2e, Dustin Arendt, Thu Feb 1 14:35:59 2024 -0800)
+- updated tutorial (d7af03f, Brenda Praggastis, Wed Feb 14 17:30:23 2024 -0800)
+- update paper folder (aa22bd5, Brenda Praggastis, Wed Oct 18 13:23:29 2023 -0700)
+- updated paper with orcid and doi ids (57e4075, Brenda Praggastis, Tue Oct 17 10:17:39 2023 -0700)
+- fixed bib error (ffd67a1, Brenda Praggastis, Mon Oct 16 12:45:46 2023 -0700)
+- rm pdf (c26dc10, Brenda Praggastis, Mon Oct 16 12:28:48 2023 -0700)
+- adding Github action (30a91d3, Brenda Praggastis, Mon Oct 16 12:22:23 2023 -0700)
+- adding paper for journal consideration (52e3cec, Brenda Praggastis, Mon Oct 16 12:14:22 2023 -0700)
+- Update factory (079cb3e, Mark Bonicillo, Wed Feb 14 12:46:11 2024 -0800)
+- Update property_store (32eec45, Mark Bonicillo, Wed Feb 14 06:43:48 2024 -0800)
+- updating tests to function correctly. (62f51a1, audun myers, Mon Feb 12 15:04:41 2024 -0500)
+- Coding incidence store and adding incidence store tests (3c09b18, audun myers, Mon Feb 12 12:25:43 2024 -0500)
+- Update property_store, tests; add factory stubs (9d89948, Mark Bonicillo, Tue Feb 6 15:53:49 2024 -0800)
+- updating descriptions on hypergraph and entityset methods (8045e3f, audun myers, Thu Jan 18 10:22:52 2024 -0500)
+- HYP-367 Add factory method stubs for PropertyStoreFactory; update tests; add methods to HarryPotter toy (1128fe2, Mark Bonicillo, Tue Jan 16 16:10:20 2024 -0800)
+- Adding comments at top of each method in hypergraph.py and entityset.py for where new methods will belong in stores. (1ec92ec, audun myers, Wed Jan 17 12:45:42 2024 -0500)
+- update incidence view and hypview (83a3723, Brenda Praggastis, Wed Jan 24 14:04:40 2024 -0800)
+- updated hypview and incidence store (13248dd, Brenda Praggastis, Wed Jan 24 13:59:25 2024 -0800)
+- Adding more detailed stubs (3bbee81, audun myers, Tue Jan 16 11:56:19 2024 -0500)
+- Continued stubbing out incidenceStore (23471bf, audun myers, Tue Jan 16 11:31:20 2024 -0500)
+- HYP-367 Add stubs for PropertyStore (6a0c087, Mark Bonicillo, Mon Jan 15 17:09:09 2024 -0800)
+- Merge pull request #147 from wlruys/networkx3-support-develop (f37c169, Mark Bonicillo, Mon Mar 4 11:02:31 2024 -0800)
+- Update usage of deprecated NetworkX adjacency matrix to graph conversion function. (18b04a4, dialecticDolt, Fri Feb 16 19:55:21 2024 -0600)
+- Pull request #142: Release/v2.2.0 (d31c24d, Bonicillo, Mark A, Fri Mar 1 23:21:35 2024 +0000)
+- Pull request #141: Release/v2.2.0 (706d842, Bonicillo, Mark A, Fri Mar 1 23:01:05 2024 +0000)
+- Pull request #138: Hotfix/joss paper (87be2bc, Bonicillo, Mark A, Wed Feb 14 23:54:01 2024 +0000)
+
+**Full Changelog**:https://github.com/pnnl/HyperNetX/compare/v2.2.0...v2.3
diff --git a/CITATION.cff b/CITATION.cff
new file mode 100644
index 00000000..42f6bbf7
--- /dev/null
+++ b/CITATION.cff
@@ -0,0 +1,68 @@
+cff-version: "1.2.0"
+authors:
+- family-names: Praggastis
+ given-names: Brenda
+ orcid: "https://orcid.org/0000-0003-1344-0497"
+- family-names: Aksoy
+ given-names: Sinan
+ orcid: "https://orcid.org/0000-0002-3466-3334"
+- family-names: Arendt
+ given-names: Dustin
+ orcid: "https://orcid.org/0000-0003-2466-199X"
+- family-names: Bonicillo
+ given-names: Mark
+ orcid: "https://orcid.org/0009-0003-9764-2180"
+- family-names: Joslyn
+ given-names: Cliff
+ orcid: "https://orcid.org/0000-0002-5923-5547"
+- family-names: Purvine
+ given-names: Emilie
+ orcid: "https://orcid.org/0000-0003-2069-5594"
+- family-names: Shapiro
+ given-names: Madelyn
+ orcid: "https://orcid.org/0000-0002-2786-7056"
+- family-names: Yun
+ given-names: Ji Young
+doi: 10.5281/zenodo.10795225
+message: If you use this software, please cite our article in the
+ Journal of Open Source Software.
+preferred-citation:
+ authors:
+ - family-names: Praggastis
+ given-names: Brenda
+ orcid: "https://orcid.org/0000-0003-1344-0497"
+ - family-names: Aksoy
+ given-names: Sinan
+ orcid: "https://orcid.org/0000-0002-3466-3334"
+ - family-names: Arendt
+ given-names: Dustin
+ orcid: "https://orcid.org/0000-0003-2466-199X"
+ - family-names: Bonicillo
+ given-names: Mark
+ orcid: "https://orcid.org/0009-0003-9764-2180"
+ - family-names: Joslyn
+ given-names: Cliff
+ orcid: "https://orcid.org/0000-0002-5923-5547"
+ - family-names: Purvine
+ given-names: Emilie
+ orcid: "https://orcid.org/0000-0003-2069-5594"
+ - family-names: Shapiro
+ given-names: Madelyn
+ orcid: "https://orcid.org/0000-0002-2786-7056"
+ - family-names: Yun
+ given-names: Ji Young
+ date-published: 2024-03-09
+ doi: 10.21105/joss.06016
+ issn: 2475-9066
+ issue: 95
+ journal: Journal of Open Source Software
+ publisher:
+ name: Open Journals
+ start: 6016
+ title: "HyperNetX: A Python package for modeling complex network data
+ as hypergraphs"
+ type: article
+ url: "https://joss.theoj.org/papers/10.21105/joss.06016"
+ volume: 9
+title: "HyperNetX: A Python package for modeling complex network data as
+ hypergraphs"
diff --git a/HNX_Paper/Figures/3graphs.png b/HNX_Paper/Figures/3graphs.png
new file mode 100755
index 00000000..0928c02b
Binary files /dev/null and b/HNX_Paper/Figures/3graphs.png differ
diff --git a/HNX_Paper/Figures/hnxexample.png b/HNX_Paper/Figures/hnxexample.png
new file mode 100755
index 00000000..51b5f941
Binary files /dev/null and b/HNX_Paper/Figures/hnxexample.png differ
diff --git a/HNX_Paper/paper.bib b/HNX_Paper/paper.bib
new file mode 100755
index 00000000..1788525a
--- /dev/null
+++ b/HNX_Paper/paper.bib
@@ -0,0 +1,261 @@
+
+@inproceedings{Joslyn2020DNS,
+ address = {Cham},
+ doi={10.1007/978-3-030-48478-1_1},
+ author = {Joslyn, Cliff A. and Aksoy, Sinan and Arendt, Dustin and Firoz, Jesun and Jenkins, Louis and Praggastis, Brenda and Purvine, Emilie and Zalewski, Marcin},
+ booktitle = {Algorithms and Models for the Web Graph},
+ editor = {Kami{\'{n}}ski, Bogumi{\l} and Pra{\l}at, Pawe{\l} and Szufel, Przemys{\l}aw},
+ isbn = {978-3-030-48478-1},
+ pages = {1--15},
+ publisher = {Springer International Publishing},
+ title = {Hypergraph Analytics of Domain Name System Relationships},
+ year = {2020}}
+
+@article{Molnar2022Application,
+ title={The application of directed hyper-graphs for analysis of models of information systems},
+ doi={10.3390/math10050759},
+ author={Moln{\'a}r, B{\'a}lint and Bencz{\'u}r, Andr{\'a}s},
+ journal={Mathematics},
+ volume={10},
+ number={5},
+ pages={759},
+ year={2022},
+ publisher={MDPI}
+}
+
+/// Tony's work to quickly compute overlap sizes
+@inproceedings{Liu2021Parallel,
+ title={Parallel algorithms for efficient computation of high-order line graphs of hypergraphs},
+ doi={10.1109/hipc53243.2021.00045},
+ author={Liu, Xu T and Firoz, Jesun and Lumsdaine, Andrew and Joslyn, Cliff and Aksoy, Sinan and Praggastis, Brenda and Gebremedhin, Assefaw H},
+ booktitle={2021 IEEE 28th International Conference on High Performance Computing, Data, and Analytics (HiPC)},
+ pages={312--321},
+ year={2021},
+ organization={IEEE}
+}
+
+@article{Zhou2022Topological,
+ title={Topological simplifications of hypergraphs},
+ doi={10.1109/tvcg.2022.3153895},
+ author={Zhou, Youjia and Rathore, Archit and Purvine, Emilie and Wang, Bei},
+ journal={IEEE Transactions on Visualization and Computer Graphics},
+ year={2022},
+ publisher={IEEE}
+}
+
+@article{Aksoy2020Hypernetwork,
+ title={Hypernetwork science via high-order hypergraph walks},
+ doi={10.1140/epjds/s13688-020-00231-0},
+ author={Aksoy, Sinan G and Joslyn, Cliff and Marrero, Carlos Ortiz and Praggastis, Brenda and Purvine, Emilie},
+ journal={EPJ Data Science},
+ volume={9},
+ number={1},
+ pages={16},
+ year={2020},
+ publisher={Springer Berlin Heidelberg}
+}
+
+@article{Pickard2023HAT,
+ title={HAT: Hypergraph analysis toolbox},
+ doi={10.1371/journal.pcbi.1011190},
+ 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}
+}
+
+@misc{Berge1973Graphs,
+ title={Graphs and {H}ypergraphs,(translated by {E}dward {M}inieka)},
+ doi={10.1016/s0924-6509(09)x7013-3},
+ author={Berge, Claude},
+ year={1973},
+ publisher={American Elsevier, New York}
+}
+
+@book{Berge1984Hypergraphs,
+ title={Hypergraphs: combinatorics of finite sets},
+ doi={10.1016/s0924-6509(08)x7007-2},
+ author={Berge, Claude},
+ volume={45},
+ year={1984},
+ publisher={Elsevier}
+}
+
+@article{Feng2021,
+ title={Hypergraph models of biological networks to identify genes critical to pathogenic viral response},
+ doi={10.1186/s12859-021-04197-2},
+ author={Feng, Song and Heath, Emily and Jefferson, Brett and Joslyn, Cliff and Kvinge, Henry and Mitchell, Hugh D and Praggastis, Brenda and Eisfeld, Amie J and Sims, Amy C and Thackray, Larissa B and others},
+ journal={BMC bioinformatics},
+ volume={22},
+ number={1},
+ pages={1--21},
+ year={2021},
+ publisher={BioMed Central}
+}
+
+// uses HNX vis capabilities
+@article{Vazquez2022Growth,
+ title={Growth principles of natural hypergraphs},
+ doi={10.48550/arXiv.2208.03103},
+ author={Vazquez, Alexei},
+ journal={arXiv preprint arXiv:2208.03103},
+ year={2022}
+}
+
+@article{Lotito2023Hypergraphx,
+ title={Hypergraphx: a library for higher-order network analysis},
+ doi={10.1093/comnet/cnad019},
+ author={Lotito, Quintino Francesco and Contisciani, Martina and De Bacco, Caterina and Di Gaetano, Leonardo and Gallo, Luca and Montresor, Alberto and Musciotto, Federico and Ruggeri, Nicol{\`o} and Battiston, Federico},
+ journal={Journal of Complex Networks},
+ volume={11},
+ number={3},
+ pages={cnad019},
+ year={2023},
+ publisher={Oxford University Press}
+}
+
+@article{Praggastis2022SVD,
+ title={The SVD of Convolutional Weights: A CNN Interpretability Framework},
+ doi={10.48550/arXiv.2208.06894},
+ author={Praggastis, Brenda and Brown, Davis and Marrero, Carlos Ortiz and Purvine, Emilie and Shapiro, Madelyn and Wang, Bei},
+ journal={arXiv preprint arXiv:2208.06894},
+ year={2022}
+}
+
+@inproceedings{Joslyn2021,
+ address = {Cham},
+ doi={10.1007/978-3-030-67318-5_25},
+ author = {Joslyn, Cliff A. and Aksoy, Sinan G. and Callahan, Tiffany J. and Hunter, Lawrence E. and Jefferson, Brett and Praggastis, Brenda and Purvine, Emilie and Tripodi, Ignacio J.},
+ booktitle = {Unifying Themes in Complex Systems X},
+ editor = {Braha, Dan and de Aguiar, Marcus A. M. and Gershenson, Carlos and Morales, Alfredo J. and Kaufman, Les and Naumova, Elena N. and Minai, Ali A. and Bar-Yam, Yaneer},
+ isbn = {978-3-030-67318-5},
+ pages = {377--392},
+ publisher = {Springer International Publishing},
+ title = {Hypernetwork Science: From Multidimensional Networks to Computational Topology},
+ year = {2021}}
+
+@article{Torres2021,
+ author = {Torres, Leo and Blevins, Ann S. and Bassett, Danielle and Eliassi-Rad, Tina},
+ doi = {10.1137/20M1355896},
+ eprint = {https://doi.org/10.1137/20M1355896},
+ journal = {SIAM Review},
+ number = {3},
+ pages = {435-485},
+ title = {The Why, How, and When of Representations for Complex Systems},
+ url = {https://doi.org/10.1137/20M1355896},
+ volume = {63},
+ year = {2021},
+ bdsk-url-1 = {https://doi.org/10.1137/20M1355896}}
+
+@article{Kurte2021,
+title = {Phoenix: A Scalable Streaming Hypergraph Analysis Framework},
+author = {Kurte, Kuldeep and Imam, Neena and Hasan, S M Shamimul and Kannan, Ramakrishnan},
+doi = {10.1007/978-3-030-71704-9_1},
+url = {https://www.osti.gov/biblio/1830117},
+issn = {2569--7072},
+place = {United States},
+year = {2021},
+month = {10}
+}
+
+@book{knuth1993,
+ title={The Stanford GraphBase: a platform for combinatorial computing},
+ author={Knuth, Donald Ervin},
+ volume={1},
+ year={1993},
+ publisher={AcM Press New York}
+}
+
+@misc{antonov2023igraph,
+ title={{i}graph enables fast and robust network analysis across programming languages},
+ author={Michael Antonov and Gábor Csárdi and Szabolcs Horvát and Kirill Müller and Tamás Nepusz and Daniel Noom and Maëlle Salmon and Vincent Traag and Brooke Foucault Welles and Fabio Zanini},
+ year={2023},
+ eprint={2311.10260},
+ archivePrefix={arXiv},
+ primaryClass={cs.SI}
+}
+
+@article{csardi2006igraph,
+ title={The {i}graph software package for complex network research},
+ author={Csardi, Gabor and Nepusz, Tamas and others},
+ journal={InterJournal, complex systems},
+ volume={1695},
+ number={5},
+ pages={1--9},
+ year={2006}
+}
+
+@inproceedings{joslyn2018,
+ title={HyperThesis: Topological Hypothesis Management in a Hypergraph Knowledgebase.},
+ author={Joslyn, Cliff A and Robinson, Michael and Smart, J and Agarwal, Khushbu and Bridgeland, David and Brown, Adam and Choudhury, Sutanay and Jefferson, Brett A and Praggastis, Brenda and Purvine, Emilie and others},
+ booktitle={TAC},
+ year={2018}
+}
+
+@article{Landry2023,
+ doi = {10.21105/joss.05162},
+ url = {https://doi.org/10.21105/joss.05162},
+ year = {2023}, publisher = {The Open Journal},
+ volume = {8},
+ number = {85},
+ pages = {5162},
+ author = {Nicholas W. Landry and Maxime Lucas and Iacopo Iacopini and Giovanni Petri and Alice Schwarze and Alice Patania and Leo Torres},
+ title = {XGI: A Python package for higher-order interaction networks}, journal = {Journal of Open Source Software}
+}
+
+@inproceedings{Szufel2019,
+ title={SimpleHypergraphs. jl—novel software framework for modelling and analysis of hypergraphs},
+ doi={10.1007/978-3-030-25070-6_9},
+ author={Antelmi, Alessia and Cordasco, Gennaro and Kami{\'n}ski, Bogumi{\l} and Pra{\l}at, Pawe{\l} and Scarano, Vittorio and Spagnuolo, Carmine and Szufel, Przemyslaw},
+ booktitle={Algorithms and Models for the Web Graph: 16th International Workshop, WAW 2019, Brisbane, QLD, Australia, July 6--7, 2019, Proceedings 16},
+ pages={115--129},
+ year={2019},
+ organization={Springer}
+}
+
+@article{Colby2023,
+ author = {Sean M Colby and Madelyn R Shapiro and Andy Lin and Aivett Bilbao and Corey D Broeckling and Emilie Purvine and Cliff A Joslyn},
+ doi = {10.1101/2023.09.29.560191},
+ elocation-id = {2023.09.29.560191},
+ eprint = {https://www.biorxiv.org/content/early/2023/10/02/2023.09.29.560191.full.pdf},
+ journal = {bioRxiv},
+ publisher = {Cold Spring Harbor Laboratory},
+ title = {Introducing Molecular Hypernetworks for Discovery in Multidimensional Metabolomics Data},
+ url = {https://www.biorxiv.org/content/early/2023/10/02/2023.09.29.560191},
+ year = {2023},
+ bdsk-url-1 = {https://www.biorxiv.org/content/early/2023/10/02/2023.09.29.560191},
+ bdsk-url-2 = {https://doi.org/10.1101/2023.09.29.560191}}
+
+@software{reback2020pandas,
+ author = {{The pandas development team}},
+ title = {{pandas-dev/pandas: Pandas}},
+ month = feb,
+ year = 2020,
+ publisher = {Zenodo},
+ version = {latest},
+ doi = {10.5281/zenodo.3509134},
+ url = {https://doi.org/10.5281/zenodo.3509134}
+}
+
+@InProceedings{ mckinney-proc-scipy-2010,
+ author = { {W}es {M}c{K}inney },
+ title = { {D}ata {S}tructures for {S}tatistical {C}omputing in {P}ython },
+ booktitle = { {P}roceedings of the 9th {P}ython in {S}cience {C}onference },
+ pages = { 56 - 61 },
+ year = { 2010 },
+ editor = { {S}t\'efan van der {W}alt and {J}arrod {M}illman },
+ doi = { 10.25080/Majora-92bf1922-00a }
+}
+
+@InProceedings{SciPyProceedings_11,
+ author = {Aric A. Hagberg and Daniel A. Schult and Pieter J. Swart},
+ title = {Exploring Network Structure, Dynamics, and Function using NetworkX},
+ booktitle = {Proceedings of the 7th Python in Science Conference},
+ pages = {11 - 15},
+ address = {Pasadena, CA USA},
+ year = {2008},
+ editor = {Ga\"el Varoquaux and Travis Vaught and Jarrod Millman},
+}
diff --git a/HNX_Paper/paper.md b/HNX_Paper/paper.md
new file mode 100755
index 00000000..95f1087d
--- /dev/null
+++ b/HNX_Paper/paper.md
@@ -0,0 +1,126 @@
+---
+title: 'HyperNetX: A Python package for modeling complex network data as hypergraphs'
+tags:
+- Python
+- hypergraph
+- network science
+- simplicial-complexes
+- knowledge graph
+- simplicial-homology
+- s-linegraph
+- property hypergraph
+authors:
+- name: Brenda Praggastis
+ orcid: 0000-0003-1344-0497
+ affiliation: "1"
+- name: Sinan Aksoy
+ orcid: 0000-0002-3466-3334
+ affiliation: "1"
+- name: Dustin Arendt
+ orcid: 0000-0003-2466-199X
+ affiliation: "1"
+- name: Mark Bonicillo
+ affiliation: "1"
+- name: Cliff Joslyn
+ orcid: 0000-0002-5923-5547
+ affiliation: "1"
+- name: Emilie Purvine
+ orcid: 0000-0003-2069-5594
+ affiliation: "1"
+- name: Madelyn Shapiro
+ orcid: 0000-0002-2786-7056
+ affiliation: "1"
+- name: Ji Young Yun
+ affiliation: "1"
+affiliations:
+- name: Pacific Northwest National Laboratory, USA
+ index: 1
+
+date: 21 June 2023
+bibliography: paper.bib
+
+---
+
+# Summary
+HyperNetX (HNX) is an open source Python library for the analysis and visualization of complex network data modeled as hypergraphs.
+Initially released in 2019, HNX facilitates exploratory data analysis of complex networks using algebraic topology, combinatorics, and generalized hypergraph and graph theoretical methods on structured data inputs.
+With its 2023 release, the library supports attaching metadata, numerical and categorical, to nodes (vertices) and hyperedges, as well as to node-hyperedge pairings (incidences).
+HNX has a customizable Matplotlib-based visualization module as well as HypernetX-Widget, its JavaScript addon for interactive exploration and visualization of hypergraphs within Jupyter Notebooks. Both packages are available on GitHub and PyPI. With a growing community of users and collaborators, HNX has become a preeminent tool for hypergraph analysis.
+
+![HNX-Widget is an add-on for the Jupyter Notebook
+computational environment, enabling users to view and interactively
+explore hypergraphs.
+The main features of the tool are: 1) adjustable layout 2) advanced
+selection and 3) visual encoding of node and edge properties.
+Metadata may be attached to the tool by providing tabular data via two optional data frames indexed by node and hyperedge identifiers. Above is an HNX-Widget visualization of a Scene to Character mapping from the LesMis dataset [@knuth1993].](Figures/hnxexample.png){height="225pt"}
+
+
+# Statement of need
+For more than a century, graph theory has provided powerful methods for studying network relationships among abstract entities.
+Since the early 2000's, software packages such as NetworkX [@SciPyProceedings_11] and `igraph` [@csardi2006igraph;@antonov2023igraph] have
+made these theoretical tools available to data scientists for studying large data sets.
+Graphs represent pairwise interactions between entities, but for many network datasets this is a severe limitation.
+In 1973, hypergraphs were introduced by Claude Berge [@Berge1973Graphs] as a strict generalization of graphs: a hyperedge in a hypergraph can contain any number of nodes, including 1, 2, or more.
+Hypergraphs have been used to model complex network datasets in
+areas such as the biological sciences, information systems, the power grid, and cyber security.
+Hypergraphs strictly generalize graphs (all graphs are (2-uniform) hypergraphs), and thus can represent additional data complexity and have more mathematical properties to exploit (for example, hyperedges can be contained in other hyperedges). As mathematical set systems, simplicial and homological methods from
+Algebraic Topology are well suited to aid in their analysis [@Joslyn2021;@Torres2021].
+With the development of hypergraph modeling methods, new software was required to support
+experimentation and exploration, which prompted the development of HyperNetX.
+
+## Related Software
+Due to the diversity of hypergraph modeling applications, hypergraph software libraries are
+often bootstrapped using data structures and methods most appropriate to their usage.
+In 2020 SimpleHypergraph.jl was made available for high performance computing on hypergraphs using Julia.
+The library offers a suite of tools for centrality analysis and community detection and integrates its own
+visualization tools with those offered by HNX [@Szufel2019]. In 2021 CompleX Group Interactions (XGI) was released.
+Originally developed to efficiently discover spreading processes in complex social systems, the library now offers
+a statistics package as well as a full suite of hypergraph analysis and visualization tools[@Landry2023].
+More recently, in 2023 HyperGraphX (HGX) was released, again with a full suite of tools for community detection
+as well as general hypergraph analytics [@Lotito2023Hypergraphx].
+A nice compendium of many of the hypergraph libraries created in the last decade can be found in @Kurte2021.
+
+HNX leads the effort to share library capabilities by specifying a Hypergraph Interchange Format (HIF)
+for storing hypergraph data as a JSON object. Since hypergraphs can store metadata on its nodes,
+hyperedges, and incidence pairs, a standardized format makes it easy to share hypergraphs across libraries.
+
+![Visualizations from hypergraph libraries based on the bipartite graph seen in grey
+ under the HyperNetX visualization (left side): XGI (Center), @Landry2023 and SimpleHypergraph (Right), @Szufel2019.](Figures/3graphs.png)
+
+# Overview of HNX
+HNX serves as a platform for the collaboration and sharing of hypergraph
+methods within the research community.
+Originally intended to generalize many of the methods from NetworkX
+to hypergraphs, HNX now has implementations for many hypergraph-specific metrics.
+While graph paths can be measured by length,
+hypergraph paths also have a width parameter *s*, given by the minimum intersection size
+of incident hyperedges in the path [@Aksoy2020Hypernetwork].
+HNX uses this *s* parameter in many of
+its core methods as well as in its *s-*centrality module.
+As set systems, hypergraphs can be viewed as subsets of abstract simplicial
+complexes – combinatorial projections of geometric objects constructed from points, line
+segments, triangles, tetrahedrons, and their higher dimensional analogues.
+HNX's Simplicial Homology module identifies and computes the *voids* of different dimensions
+in the simplicial complexes generated by modestly sized hypergraphs.
+These objects, which are used for defining the *Homology Groups*
+studied by Algebraic Topologists, offer new metrics for exploratory
+data science.
+
+As a collaborative platform, HNX contains contributed modules
+and tutorials in the form of Jupyter notebooks
+for Laplacian clustering, clustering and modularity, synthetic
+generation of hypergraphs, and Contagion Theory.
+In its latest release, HNX 2.0 uses Pandas dataframes[@reback2020pandas;@mckinney-proc-scipy-2010] as its underlying data structure,
+making the nodes and hyperedges of a hypergraph as accessible as the
+cells in a dataframe.
+This simple design allows HNX to import data from semantically
+loaded graphs such as property graphs and knowledge graphs,
+in order to model and explore their higher order relationships.
+Because it is open source, HNX provides a unique opportunity for
+hypergraph researchers to implement their own methods built from
+HNX and contribute them as modules and Jupyter tutorials to the HNX user community.
+
+## Projects using HNX
+HNX was created by the Pacific Northwest National Laboratory. It has provided data analysis and visualization support for academic papers in subject areas such as biological systems [@Feng2021;@Colby2023], cyber security [@Joslyn2020DNS], information systems [@Molnar2022Application], neural networks [@Praggastis2022SVD], knowledge graphs [@joslyn2018], and the foundations of hypergraph theory [@Vazquez2022Growth].
+
+# References
diff --git a/HNX_Paper/paper.pdf b/HNX_Paper/paper.pdf
new file mode 100755
index 00000000..b8c29288
Binary files /dev/null and b/HNX_Paper/paper.pdf differ
diff --git a/HNX_Paper/paper.tex b/HNX_Paper/paper.tex
new file mode 100755
index 00000000..a3ceb8fd
--- /dev/null
+++ b/HNX_Paper/paper.tex
@@ -0,0 +1,122 @@
+\documentclass{article}
+\usepackage[utf8]{inputenc}
+
+\title{HyperNetX: A Python package for modeling complex network data as hypergraphs}
+\author{Brenda Praggastis
+ \and Sinan Aksoy
+ \and Dustin Arendt
+ \and Mark Bonicillo
+ \and Cliff Joslyn
+ \and Emilie Purvine
+ \and Madelyn Shapiro
+ \and Ji Young Yun}
+
+\date{June 2023}
+
+\usepackage{natbib}
+\usepackage{graphicx}
+
+\begin{document}
+
+\maketitle
+
+\abstract{
+HyperNetX (HNX) is an open source Python library for the analysis and visualization of complex network data modeled as hypergraphs.
+Initially released in 2019, HNX facilitates exploratory data analysis of complex networks using algebraic topology, combinatorics, and generalized hypergraph and graph theoretical methods on structured data inputs.
+With its 2023 release, the library supports attaching metadata, numerical and categorical, to nodes (vertices) and hyperedges, as well as to node-hyperedge pairings (incidences).
+HNX has a customizable Matplotlib-based visualization module as well as HypernetX-Widget, its JavaScript addon for interactive exploration and visualization of hypergraphs within Jupyter Notebooks. Both packages are available on GitHub and PyPI. With a growing community of users and collaborators, HNX has become a preeminent tool for hypergraph analysis.
+}
+
+\begin{figure}[h!]
+ \centering
+ \includegraphics[height=225pt]{Figures/hnxexample.png}
+ \caption{HNX-Widget visualization of a Scene to Character mapping from the LesMis dataset \cite{knuth1993}.}
+ \label{fig:hnxexample}
+ \end{figure}
+
+\section{Statement of need}
+For more than a century, graph theory has provided powerful methods for studying network relationships among abstract entities.
+Since the early 2000's, software packages such as NetworkX \cite{hagberg2020}and Igraph \cite{csardi2006} have
+made these theoretical tools available to data scientists for studying large data sets.
+Graphs represent pairwise interactions between entities, but for many network datasets this is a severe limitation.
+In 1973, hypergraphs were introduced by Claude Berge \cite{Berge1973Graphs}as a strict generalization of graphs: a hyperedge in a hypergraph can contain any number of nodes, including 1, 2, or more.
+Hypergraphs have been used to model complex network datasets in
+areas such as the biological sciences, information systems, the power grid, and cyber security.
+Hypergraphs strictly generalize graphs (all graphs are (2-uniform) hypergraphs), and thus can represent additional data complexity and have more mathematical properties to exploit (for example, hyperedges can be contained in other hyperedges). As mathematical set systems, simplicial and homological methods from
+Algebraic Topology are well suited to aid in their analysis \cite{Joslyn2021,Torres2021}.
+With the development of hypergraph modeling methods, new software was required to support
+experimentation and exploration, which prompted the development of HyperNetX.
+
+\section{Related Software}
+Due to the diversity of hypergraph modeling applications, hypergraph software libraries are
+often bootstrapped using data structures and methods most appropriate to their usage.
+A nice compendium of many of the hypergraph libraries created in the last decade can be found in \cite{Kurte2021}.
+HNX leads the effort to share library capabilities by specifying a Hypergraph Interchange Format (HIF)
+for storing hypergraph data as a JSON object. Since hypergraphs can store metadata on its nodes,
+hyperedges, and incidence pairs, a standardized format makes it easy to share hypergraphs across libraries.
+
+\begin{figure}[h!]
+ \centering
+ \includegraphics[]{Figures/3graphs.png}
+ \caption{Visualizations from hypergraph libraries based on the bipartite graph seen in grey
+ under the HyperNetX visualization (left side): XGI (Center), \cite{Landry2023} and SimpleHypergraph (Right), \cite{Szufel2019}.}
+ \label{fig:3graphs}
+ \end{figure}
+
+\section{Overview of HNX}
+HNX serves as a platform for the collaboration and sharing of hypergraph
+methods within the research community.
+Originally intended to generalize many of the methods from NetworkX
+to hypergraphs, HNX now has implementations for many hypergraph-specific metrics.
+While graph paths can be measured by length,
+hypergraph paths also have a width parameter *s*, given by the minimum intersection size
+of incident hyperedges in the path \cite{Aksoy2020Hypernetwork].
+HNX uses this *s* parameter in many of
+its core methods as well as in its *s-*centrality module.
+As set systems, hypergraphs can be viewed as subsets of abstract simplicial
+complexes – combinatorial projections of geometric objects constructed from points, line
+segments, triangles, tetrahedrons, and their higher dimensional analogues.
+HNX's Simplicial Homology module identifies and computes the *voids* of different dimensions
+in the simplicial complexes generated by modestly sized hypergraphs.
+These objects, which are used for defining the \textit{Homology Groups}
+studied by Algebraic Topologists, offer new metrics for exploratory
+data science.
+
+As a collaborative platform, HNX contains contributed modules
+and tutorials in the form of Jupyter notebooks
+for Laplacian clustering, clustering and modularity, synthetic
+generation of hypergraphs, and Contagion Theory.
+In its latest release, HNX 2.0 uses Pandas dataframes as its underlying data structure,
+making the nodes and hyperedges of a hypergraph as accessible as the
+cells in a dataframe.
+This simple design allows HNX to import data from semantically
+loaded graphs such as property graphs and knowledge graphs,
+in order to model and explore their higher order relationships.
+Because it is open source, HNX provides a unique opportunity for
+hypergraph researchers to implement their own methods built from
+HNX and contribute them as modules and Jupyter tutorials to the HNX user community.
+
+\section{HNX-Widget: Interactive Diagrams of Hypergraphs}
+HNX interfaces with an add-on widget for the Jupyter Notebook
+computational environment, enabling users to view and interactively
+explore hypergraphs, see Figure 1.
+The main features of the tool are: 1) adjustable layout 2) advanced
+selection and 3) visual encoding of node and edge properties.
+
+The primary tool of the widget is an Euler diagram visualization approach that shows nodes as circles and hyperedges as closed curves surrounding the nodes/circles they contain. The tool uses a force directed layout of the underlying bipartite representation to determine the position of the nodes. Hyperedges are then drawn as convex hulls given the node positions. To remove overlapping hyperedges the user and can move and pin nodes as desired.
+Selection of nodes and hyperedges is available via clicking, brushing, and advanced methods. For example, the set of selected nodes can be expanded by selecting all nodes contained by selected edges, and vice versa.
+
+%
+
+%
+%
+
+
+Metadata may be attached to the tool by providing tabular data via two optional data frames indexed by node and hyperedge identifiers. Single rows from these tables become visible to the user in a tooltip when they hover over a node or hyperedge in this tool. The user can configure the tool to encode the node size or color and the hyperedge color using a column in these data tables.
+
+\cite{Projects using HNX}
+HNX was created by the Pacific Northwest National Laboratory. It has provided data analysis and visualization support for academic papers in subject areas such as biological systems \cite{Feng2021;@Colby2023], cyber security \cite{Joslyn2020DNS], information systems \cite{Molnar2022Application], neural networks \cite{Praggastis2022SVD], knowledge graphs \cite{joslyn2018], and the foundations of hypergraph theory \cite{Vazquez2022Growth].
+
+\bibliographystyle{plain}
+\bibliography{paper}
+\end{document}
diff --git a/LICENSE.rst b/LICENSE.rst
index 5e8f9e29..b6a0aee2 100644
--- a/LICENSE.rst
+++ b/LICENSE.rst
@@ -5,7 +5,7 @@ License
HyperNetX
-Copyright 2018, 2023, Battelle Memorial Institute
+Copyright 2018, 2023, 2024, Battelle Memorial Institute
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
diff --git a/LONG_DESCRIPTION.rst b/LONG_DESCRIPTION.rst
index 1c7ed11e..4609d9be 100644
--- a/LONG_DESCRIPTION.rst
+++ b/LONG_DESCRIPTION.rst
@@ -24,37 +24,27 @@ Documentation is available at: https://pnnl.github.io/HyperNetX
For questions and comments contact the developers directly at: hypernetx@pnnl.gov
-New Features in Version 2.0
----------------------------
+HyperNetX 2.3
+=============
-HNX 2.0 now accepts metadata as core attributes of the edges and nodes of a
-hypergraph. While the library continues to accept lists, dictionaries and
-dataframes as basic inputs for hypergraph constructions, both cell
-properties and edge and node properties can now be easily added for
-retrieval as object attributes.
+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. Updating is recommended.
-The core library has been rebuilt to take advantage of the flexibility and speed of Pandas Dataframes.
-Dataframes offer the ability to store and easily access hypergraph metadata. Metadata can be used for filtering objects, and characterize their
-distributions by their attributes.
-
-**Version 2.0 is not backwards compatible. Objects constructed using version
-1.x can be imported from their incidence dictionaries.**
+**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
~~~~~~~~~~~~~~~~~~~~~~~~~
-#. The Hypergraph constructor now accepts nested dictionaries with incidence cell properties, pandas.DataFrames, and 2-column Numpy arrays.
-#. Additional constructors accept incidence matrices and incidence dataframes.
-#. Hypergraph constructors accept cell, edge, and node metadata.
-#. Metadata available as attributes on the cells, edges, and nodes.
-#. User-defined cell weights and default weights available to incidence matrix.
-#. Meta data persists with restrictions and removals.
-#. Meta data persists onto s-linegraphs as node attributes of Networkx graphs.
-#. New hnxwidget available using `pip install hnxwidget`.
-
+#. We've added new functionality to Hypergraphs; you can add and remove nodes, edges, and incidences on Hypergraph.
+#. Arithmetic operations have also been added to Hypergraph: sum, difference, union, intersection
+#. We've also added a new tutorial on basic hypergraph arithmetic operations
+#. Under the hood, the EntitySet has been replaced by HypergraphView, new factory methods have been created to support
+the Hypergraph constructor, and internal classes such as IncidenceStore and PropertyStore help maintain the structure
+and attributes of a Hypergraph
What's Changed
~~~~~~~~~~~~~~~~~~~~~~~~~
-#. 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.
-#. Methods for adding nodes and hyperedges are currently not supported.
-#. The `nwhy` optimizations are no longer supported.
-#. Entity and EntitySet classes are being moved to the background. The Hypergraph constructor does not accept either.
+#. Documentation has received a major update; the Glossary and docstrings of Hypergraph have been updated.
+#. HNX now requires Python ^3.10,<=3.12
+#. We've upgraded all the underlying core libraries to the latest versions.
diff --git a/Makefile b/Makefile
index 42b60458..9d9dd79a 100644
--- a/Makefile
+++ b/Makefile
@@ -1,131 +1,125 @@
SHELL = /bin/bash
-
VENV = venv-hnx
PYTHON3 = python3
+############# Manage Environments #############
-## Lint
+## Environment using Pip
+.PHONY: venv
+venv: clean-venv
+ @$(PYTHON3) -m venv $(VENV);
-.PHONY: lint
-lint: pylint flake8 mypy
+.PHONY: clean-venv
+clean-venv:
+ rm -rf $(VENV)
-.PHONY: pylint
-pylint:
- @$(PYTHON3) -m pylint --recursive=y --persistent=n --verbose hypernetx
+.PHONY: install
+install:
+ @$(PYTHON3) -m pip install --upgrade pip
+ @$(PYTHON3) -m pip install -e .
+ @$(PYTHON3) -m pip install -r requirements.txt
-.PHONY: mypy
-mypy:
- @$(PYTHON3) -m mypy hypernetx || true
+## Environment using Poetry
-.PHONY: flake8
-flake8:
- @$(PYTHON3) -m flake8 hypernetx --exit-zero
+.PHONY: develop
+develop: clean-poetry-env
+ poetry shell
+ poetry install --with test
-.PHONY: format
-format:
- @$(PYTHON3) -m black hypernetx
+.PHONY: requirements.txt
+requirements.txt:
+ poetry export --format requirements.txt --output requirements.txt --without-hashes --with test,widget,tutorials,docs
-## Tests
-
-.PHONY: pre-commit
-pre-commit:
- pre-commit install
- pre-commit run --all-files
+############# Running Tests, linters #############
+## Tests
.PHONY: test
test:
- coverage run --source=hypernetx -m pytest
+ coverage run --source=hypernetx -m pytest tests
coverage report -m
-.PHONY: test-ci
-test-ci:
- @$(PYTHON3) -m tox
+.PHONY: test-core
+test-core:
+ coverage run --source=hypernetx/classes -m pytest tests/classes --verbose
+ coverage report -m
-.PHONY: test-ci-stash
-test-ci-stash: lint-deps lint pre-commit test-deps test-ci
+## Tests using Tox
+## Includes linting, running tests on jupyter notebooks
+.PHONY: test-tox
+test-tox:
+ @$(PYTHON3) -m tox --parallel
-.PHONY: test-ci-github
-test-ci-github: lint-deps lint pre-commit ci-github-deps test-deps test-ci
+### Tests using Poetry + Tox
+### Used by Bamboo CI Pipeline, Github Workflows CI Pipeline
+.PHONY: test-ci-stash
+test-ci-stash: install-poetry-stash run-poetry-tox clean-poetry-env
-## Continuous Deployment
-## Assumes that scripts are run on a container or test server VM
-### Publish to PyPi
+.PHONY: build-docs-stash
+build-docs-stash: install-poetry-stash run-build-docs clean-poetry-env
-.PHONY: publish-deps
-publish-deps:
- @$(PYTHON3) -m pip install -e .[packaging] --use-pep517
+.PHONY: install-poetry-stash
+install-poetry-stash:
+ pip install poetry==1.8.2 tox
-.PHONY: build-dist
-build-dist: publish-deps clean
- @$(PYTHON3) -m build --wheel --sdist
- @$(PYTHON3) -m twine check dist/*
-
-## Assumes the following environment variables are set: TWINE_USERNAME, TWINE_PASSWORD, TWINE_REPOSITORY_URL,
-## See https://twine.readthedocs.io/en/stable/#environment-variables
-.PHONY: publish-to-pypi
-publish-to-pypi: publish-deps build-dist
- @echo "Publishing to PyPi"
- $(PYTHON3) -m twine upload dist/*
+.PHONY: run-poetry-tox
+run-poetry-tox:
+ tox --parallel
+.PHONY: run-build-docs
+run-build-docs:
+ tox -e build-docs
-### Update version
+.PHONY: clean-poetry-env
+clean-poetry-env:
+ poetry env remove --all
-.PHONY: version-deps
-version-deps:
- @$(PYTHON3) -m pip install .[releases] --use-pep517
+## Lint
+.PHONY: lint
+lint: pylint flake8
+.PHONY: pylint
+pylint:
+ @$(PYTHON3) -m pylint --recursive=y --persistent=n --verbose hypernetx
-### Documentation
+# Todo: fix flake8 errors and remove --exit-zero
+.PHONY: flake8
+flake8:
+ @$(PYTHON3) -m flake8 hypernetx --exit-zero
-.PHONY: docs-deps
-docs-deps:
- @$(PYTHON3) -m pip install .[documentation] --use-pep517
+.PHONY: pre-commit
+pre-commit:
+ pre-commit install
+ pre-commit run --all-files
+############# Packaging and Publishing to PyPi #############
+## Uses Poetry to manage packaging and publishing
+## Targets are included as a backup in case the Github Workflows CI can't publish to PyPi and we need to do it manually
+## Assumes the following environment variables are set: PYPI_API_TOKEN
+.PHONY: publish-to-pypi
+publish-to-pypi: build check-long-desc
+ @echo "Publishing to PyPi"
+ poetry config pypi-token.pypi PYPI_API_TOKEN
+ poetry config repositories.pypi https://pypi.org/simple/
+ poetry publish --dry-run
+ #poetry publish
-## Tutorials
+.PHONY: build
+build: clean
+ poetry build
-.PHONY: tutorial-deps
-tutorial-deps:
- @$(PYTHON3) -m pip install .[tutorials] .[widget] --use-pep517
+.PHONY: check-long-desc
+check-long-desc:
+ poetry run pip install twine
+ poetry run twine check dist/*
+############# Misc #############
.PHONY: tutorials
tutorials:
jupyter notebook tutorials
-
-## Environment
-
-.PHONY: clean-venv
-clean-venv:
- rm -rf $(VENV)
-
.PHONY: clean
clean:
- rm -rf .out .pytest_cache .tox *.egg-info dist build
-
-.PHONY: venv
-venv: clean-venv
- @$(PYTHON3) -m venv $(VENV);
-
-.PHONY: github-ci-deps
-ci-github-deps:
- @$(PYTHON3) -m pip install 'pytest-github-actions-annotate-failures>=0.1.7'
-
-.PHONY: lint-deps
-lint-deps:
- @$(PYTHON3) -m pip install .[lint] --use-pep517
-
-.PHONY: format-deps
-format-deps:
- @$(PYTHON3) -m pip install .[format] --use-pep517
-
-.PHONY: test-deps
-test-deps:
- @$(PYTHON3) -m pip install .[testing] --use-pep517
-
-.PHONY: all-deps
-all-deps:
- @$(PYTHON3) -m pip install .[all] --use-pep517
+ rm -rf .out .pytest_cache .tox *.egg-info dist build _build pytest.xml pytest_notebooks.xml .coverage
diff --git a/README.md b/README.md
index 344a942c..55e60eaf 100644
--- a/README.md
+++ b/README.md
@@ -1,11 +1,11 @@
-
-
HyperNetX
==========
+
+
[![Pytest](https://github.com/pnnl/HyperNetX/actions/workflows/ci.yml/badge.svg)](https://github.com/pnnl/HyperNetX/actions/workflows/ci.yml)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![linting: pylint](https://img.shields.io/badge/linting-pylint-yellowgreen)](https://github.com/PyCQA/pylint)
-
+[![CITATION.cff](https://github.com/pnnl/HyperNetX/actions/workflows/cff.yml/badge.svg)](https://github.com/pnnl/HyperNetX/actions/workflows/cff.yml)
The HyperNetX library provides classes and methods for the analysis
and visualization of complex network data modeled as hypergraphs.
@@ -28,35 +28,31 @@ Documentation is available at: https://pnnl.github.io/HyperNetX
For questions and comments contact the developers directly at: hypernetx@pnnl.gov
-New Features in Version 2.0
-===========================
-
-HNX 2.0 now accepts metadata as core attributes of the edges and nodes of a
-hypergraph. While the library continues to accept lists, dictionaries and
-dataframes as basic inputs for hypergraph constructions, both cell
-properties and edge and node properties can now be easily added for
-retrieval as object attributes.
+Summary - Release highlights - HNX 2.3
+--------------------------------------
-The core library has been rebuilt to take advantage of the flexibility and speed of Pandas Dataframes.
-Dataframes offer the ability to store and easily access hypergraph metadata. Metadata can be used for filtering objects, and characterize their
-distributions by their attributes.
+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.0 is not backwards compatible. Objects constructed using version
-1.x can be imported from their incidence dictionaries.**
+**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. The Hypergraph constructor now accepts nested dictionaries with incidence cell properties, pandas.DataFrames, and 2-column Numpy arrays.
-1. Additional constructors accept incidence matrices and incidence dataframes.
-1. Hypergraph constructors accept cell, edge, and node metadata.
-1. Metadata available as attributes on the cells, edges, and nodes.
-1. User-defined cell weights and default weights available to incidence matrix.
-1. Meta data persists with restrictions and removals.
-1. Meta data persists onto s-linegraphs as node attributes of Networkx graphs.
-1. New hnxwidget available using `pip install hnxwidget`.
+~~~~~~~~~~~~~~~~~~~~~~~~~
+#. Hypergraph now supports adding and removing edges, nodes, and incidences
+#. Hypergraph also supports the sum, difference, union, and intersection of a Hypergraph to another Hypergraph
+#. New factory methods to support the Hypergraph constructor
+#. EntitySet has been replaced by HypergraphView
+#. IncidenceStore and PropertyStore are new classes that maintain the structure and attributes of a Hypergraph
+#. Hypergraph constructors accept cell, edge, and node metadata.
What's Changed
+~~~~~~~~~~~~~~~~~~~~~~~~~
+#. HNX now requires Python ^3.10,<=3.12
+#. HNX core libraries have been updated
+#. Updated tutorials
--------------
1. 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.
1. Methods for adding nodes and hyperedges are currently not supported.
@@ -65,48 +61,48 @@ What's Changed
-Tutorials
-=========
+Tutorials Available for Colab
+=============================
Google Colab
------------
-
+
- Tutorial 1 - HNX Basics
+ Basic 1 - HNX Basics
-
+
-
+
- Tutorial 2 - Visualization Methods
+ Basic 2 - Visualization Methods
-
+
-
+
- Tutorial 3 - LesMis Case Study
+ Basic 3 - LesMis Case Study
-
+
-
+
- Tutorial 4 - LesMis Visualizations-Book Tour
+ Basic 4 - LesMis Visualizations-Book Tour
-
+
-
+
- Tutorial 5 - s-Centrality
+ Basic 5 - HNX attributed hypergraph
-
+
-
+
- Tutorial 6 - Homology mod2 for TriLoop Example
+ Basic 6 - Hypergraph Arithmetic.ipynb
-
+
Jupyter Notebooks
@@ -190,29 +186,71 @@ Ensure that you have [git](https://git-scm.com/book/en/v2/Getting-Started-Instal
```shell
git clone https://github.com/pnnl/HyperNetX.git
cd HyperNetX
+
+# Create a virtual environment
make venv
source venv-hnx/bin/activate
-pip install .
+
+# install required dependencies
+make install
```
Development
===========
Install an editable version
----------------------------
-
```
pip install -e .
```
-Install an editable version with supported applications
--------------------------------------------------------
+Install additional dependencies to support testing and jupyter notebooks:
+```
+pip install -r requirements.txt
+```
-```shell
-pip install -e .['all']
+You can also install all these requirements in one Make target:
+
+```
+make install
+```
+
+Poetry
+======
+
+This library uses [Poetry](https://python-poetry.org/docs/) to manage dependencies and packaging. Poetry can also be
+used to manage your environment for development.
+
+Prerequisites
+-------------
+
+* [Install Poetry](https://python-poetry.org/docs/#installation)
+
+
+Configure Poetry
+----------------
-# for zsh users
-pip install -e .'[all]'
+[Configure your Poetry](https://python-poetry.org/docs/configuration/) to create the virtual environment in your project directory:
+```
+poetry config virtualenvs.in-project true
+
+# check the poetry configuration
+poetry config --list
+```
+
+Set up virtual environment
+----------------------------
+
+Create and activate a virtual environment.
+```
+poetry shell
+```
+
+NOTE: If you plan to use Poetry to manage your virtual environment, you can activate the virtual environment
+using poerty: `poetry shell`. Another option is to directly
+
+Install required dependencies and HyperNetX in editable mode.
+```
+poetry install
```
Install support for testing
@@ -221,7 +259,7 @@ Install support for testing
> ℹ️ **NOTE:** This project has a pytest configuration file named 'pytest.ini'. By default, pytest will use those configuration settings to run tests.
```shell
-make test-deps
+poetry install --with test
# run tests
python -m pytest
@@ -237,17 +275,13 @@ open htmlcov/index.html
Install support for tutorials
-----------------------------
-``` shell
-make tutorial-deps
+```
+poetry install --with tutorials
# open Jupyter notebooks in a browser
make tutorials
```
-
-
-
-
Code Quality
------------
HyperNetX uses a number of tools to maintain code quality:
@@ -257,12 +291,12 @@ HyperNetX uses a number of tools to maintain code quality:
Before using these tools, ensure that you install Pylint in your environment:
-```shell
-make lint-deps
+```
+poetry install --with lint
```
-
-### Pylint
+Pylint
+------
[Pylint](https://pylint.pycqa.org/en/latest/index.html) is a static code analyzer for Python-based projects. From the [Pylint docs](https://pylint.pycqa.org/en/latest/index.html#what-is-pylint):
@@ -282,37 +316,31 @@ pylint hypernetx --output=pylint-results.txt
For more information on configuration, see https://pylint.pycqa.org/en/latest/user_guide/configuration/index.html
-### Black
-
+Black
+-----
[Black](https://black.readthedocs.io/en/stable/) is a PEP 8 compliant formatter for Python-based project. This tool is highly opinionated about how Python should be formatted and will automagically reformat your code.
```shell
-make format-deps
black hypernetx
```
Documentation
-===============
+-------------
-Build and view documentation locally
----------------------------
+Build and view documentation locally:
```
-make docs-deps
+poetry install --with docs
cd docs
make html
open docs/build/html/index.html
```
-Editing documentation
-----------------------
-
When editing documentation, you can auto-rebuild the documentation locally so that you can view your document changes
live on the browser without having to rebuild every time you have a change.
```
-make docs-deps
cd docs
make livehtml
```
@@ -353,7 +381,7 @@ gh run list --workflow=ci.yml --repo pnnl/HyperNetX
Versioning
-----------
+==========
This project uses [`commitizen`](https://github.com/commitizen-tools/commitizen) to manage versioning.
The files where "version" will be updated are listed in the '.cz.toml' file. To create a new version and the associated tag,
@@ -361,7 +389,7 @@ run the following commands:
```shell
# Install commitizen tool to environment
-make version-deps
+pip install commitizen
# Updates version; values for '--increment' can be MAJOR, MINOR, or PATCH
# Autocreates a tag and commit for the updated version
diff --git a/docs/Makefile b/docs/Makefile
index c0117614..bcf2f76b 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -28,7 +28,7 @@ help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
html: clean
- $(SPHINXAPIDOC) -f -o "$(SOURCEDIR)"/classes ../hypernetx/classes
+ $(SPHINXAPIDOC) --module-first -f -o "$(SOURCEDIR)"/classes ../hypernetx/classes
$(SPHINXAPIDOC) -f -o "$(SOURCEDIR)"/algorithms ../hypernetx/algorithms
$(SPHINXAPIDOC) -f -o "$(SOURCEDIR)"/drawing ../hypernetx/drawing
$(SPHINXAPIDOC) -f -o "$(SOURCEDIR)"/reports ../hypernetx/reports
diff --git a/docs/source/classes/classes.rst b/docs/source/classes/classes.rst
index f6e8cb3f..95e8fcca 100644
--- a/docs/source/classes/classes.rst
+++ b/docs/source/classes/classes.rst
@@ -1,21 +1,26 @@
classes package
===============
+.. automodule:: classes
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
Submodules
----------
-classes.entityset module
-------------------------
+classes.factory module
+----------------------
-.. automodule:: classes.entityset
+.. automodule:: classes.factory
:members:
:undoc-members:
:show-inheritance:
-classes.helpers module
-----------------------
+classes.hyp\_view module
+------------------------
-.. automodule:: classes.helpers
+.. automodule:: classes.hyp_view
:members:
:undoc-members:
:show-inheritance:
@@ -28,10 +33,18 @@ classes.hypergraph module
:undoc-members:
:show-inheritance:
-Module contents
----------------
+classes.incidence\_store module
+-------------------------------
-.. automodule:: classes
+.. automodule:: classes.incidence_store
+ :members:
+ :undoc-members:
+ :show-inheritance:
+
+classes.property\_store module
+------------------------------
+
+.. automodule:: classes.property_store
:members:
:undoc-members:
:show-inheritance:
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 24d8e3f6..e499dd0c 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -19,13 +19,13 @@
import os
-__version__ = "2.2.0"
+__version__ = "2.3.0"
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
-sys.path.insert(0 , os.path.abspath("../../hypernetx"))
+sys.path.insert(0, os.path.abspath("../../hypernetx"))
# -- Project information -----------------------------------------------------
@@ -57,7 +57,7 @@
"sphinx.ext.napoleon",
"sphinx.ext.todo",
"sphinx.ext.viewcode",
- 'sphinx_copybutton',
+ "sphinx_copybutton",
]
# Add any paths that contain templates here, relative to this directory.
@@ -79,7 +79,7 @@
#
# This is also used if you do content translation via gettext catalogs.
# Usually you set "language" from the command line for these cases.
-language = 'en'
+language = "en"
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
@@ -239,8 +239,8 @@
(
master_doc,
"HyperNetX.tex",
- u"HyperNetX Documentation",
- u"Brenda Praggastis, Dustin Arendt",
+ "HyperNetX Documentation",
+ "Brenda Praggastis, Dustin Arendt",
"manual",
),
]
@@ -270,7 +270,7 @@
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
-man_pages = [(master_doc, "hypernetx", u"HyperNetX Documentation", [author], 1)]
+man_pages = [(master_doc, "hypernetx", "HyperNetX Documentation", [author], 1)]
# If true, show URL addresses after external links.
# man_show_urls = False
@@ -285,7 +285,7 @@
(
master_doc,
"HyperNetX",
- u"HyperNetX Documentation",
+ "HyperNetX Documentation",
author,
"HyperNetX",
"One line description of project.",
@@ -377,7 +377,7 @@
# Remove the command prompts such as >>> when copying code snippets from copybutton
# see https://sphinx-copybutton.readthedocs.io/en/latest/use.html
-copybutton_exclude = '.linenos, .gp'
+copybutton_exclude = ".linenos, .gp"
# tables and code-blocks are automatically numbered if they have a caption.
# See https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-numfig
diff --git a/docs/source/glossary.rst b/docs/source/glossary.rst
index c927c49b..b690b629 100644
--- a/docs/source/glossary.rst
+++ b/docs/source/glossary.rst
@@ -1,125 +1,202 @@
.. _glossary:
-=====================
-Glossary of HNX terms
-=====================
+===================
+HNX Data Structures
+===================
+.. figure:: images/code_structure.png
+ :width: 300px
+ :align: right
+
+ Code structure for HNX.
-The HNX library centers around the idea of a :term:`hypergraph`. This glossary provides a few key terms and definitions.
+The HNX library centers around the idea of a :term:`hypergraph`.
+There are many definitions of a *hypergraph*. In HNX a hypergraph
+is a tuple of three sets, :math:`H = (V, E, \mathcal{I})`.
+- :math:`V`, a set of *nodes* (aka hypernodes, vertices), distinguished by unique identifiers
+- :math:`E` a set of *edges* (aka hyperedges), distinguished by unique identifiers
+- :math:`\mathcal{I}`, a set of *incidences*, which form a subset of :math:`E \times V`, distinguished by the pairing of unique identifiers of edges in :math:`E` and nodes in :math:`V`
-.. glossary::
- :sorted:
+The incidences :math:`\mathcal{I}` can be described by a Boolean function, :math:`\mathcal{I}_B : E \times V \rightarrow \{0, 1\}`, indicating whether or not a pair is included in the hypergraph.
+In HNX we instantiate :math:`H = (V, E, \mathcal{I})` using three *hypergraph views.* We can visualize this through a high
+level diagram of our current code structure shown in Fig. 1. Here we begin with data (e.g., data frame, dictionary,
+list of lists, etc.) that is digested via the appropriate factory method to construct property stores for nodes,
+edges, and incidences as well as an incidence store that captures the hypergraph structure.
+These four objects are then used to create three hypergraph views that the hypergraph object
+uses to access and analyze the hypergraph structure and attributes.
- .. // scan hypergraph.py
- Entity and Entity set
- Class in entity.py.
- HNX stores many of its data structures inside objects of type Entity. Entities help to insure safe behavior, but their use is primarily technical, not mathematical.
+=====================
+Glossary of HNX terms
+=====================
- hypergraph
- The term *hypergraph* can have many different meanings. In HNX, it means a tuple (Nodes, Edges, Incidence), where Nodes and Edges are sets, and Incidence is a function that assigns a value of True or False to every pair (n,e) in the Cartesian product Nodes x Edges. We call
- - Nodes the set of nodes
- - Edges the set of edges
- - Incidence the incidence function
- *Note* Another term for this type of object is a *multihypergraph*. The ability to work with multihypergraphs efficiently is a distinguishing feature of HNX!
+**Note: For all definitions below, assume** :math:`H = (V, E, \mathcal{I})` **is a
+hypergraph.**
- incidence
- A node n is incident to an edge e in a hypergraph (Nodes, Edges, Incidence) if Incidence(n,e) = True.
- !!! -- give the line of code that would allow you to evaluate
+.. glossary::
+ :sorted:
- incidence matrix
- A rectangular matrix constructed from a hypergraph (Nodes, Edges, Incidence) where the elements of Nodes index the matrix rows, and the elements of Edges index the matrix columns. Entry (n,e) in the incidence matrix is 1 if n and e are incident, and is 0 otherwise.
+
+ PropertyStore
+ Class in property_store.py. Each of the basic sets in a hypergraph, (Nodes, Edges, Incidences), have metadata stored in a
+ PropertyStore. By storing the data and metadata in a single place, updates and references have a single source of
+ truth.
- edge nodes (aka edge elements)
- The nodes (or elements) of an edge e in a hypergraph (Nodes, Edges, Incidence) are the nodes that are incident to e.
+ hypergraph
+ A hypergraph is a tuple of three sets, :math:`H = (V, E, \mathcal{I})`.
+
+ - :math:`V`, a set of *nodes* (aka hypernodes, vertices), distinguished by unique identifiers
+ - :math:`E` a set of *edges* (aka hyperedges), distinguished by unique identifiers
+ - :math:`\mathcal{I}`, a set of *incidences*, which form a subset of :math:`E \times V`, distinguished by the pairing of unique identifiers of edges in :math:`E` and nodes in :math:`V`
+
+ multihypergraph
+ HNX hypergraphs may be multihypergraphs. A multihypergraph is a hypergraph that allows distinct edges to contain the same set of *elements* and distinct nodes to belong to the same set of edges (aka *memberships*). When collapsing a hypergraph,
+ edges incident with the same set of nodes or nodes incident with the same set of edges are collapsed to single objects.
+
+ IncidenceStore
+ Class in incidence_store.py holding the set of ordered pairs of Edges and Nodes belonging to the hypergraph. The :term:`elements` and
+ :term:`memberships` are inferred from the :term:`incidences` held in the IncidenceStore.
+
+ HypergraphView
+ Class in hyp_view.py tying the properties of hypergraph objects held in the :term:`PropertyStore` class, which holds metadata, with their ids
+ held in the :term:`IncidenceStore` class, which holds the Hypergraph relationships.
+ The PropertyStores are unaware of the IncidenceStore and vice versa.
+
+ elements
+ The elements of an edge is the set of nodes incident to the edge in the Hypergraph.
+
+ memberships
+ The memberships of a node is the set of edges incident to the node in the Hypergraph.
+
+ incidences
+ The ordered pairs in :math:`\mathcal{I} \subset E \times V`, which define the relationships in the hypergraph.
+ The incidences :math:`\mathcal{I}` of a hypergraph provide the minimal amount of data required to instantiate the hypergraph.
+ The Edges :math:`E` and Nodes :math:`V` of a Hypergraph can be inferred from the pairs :math:`(e,v)` in the Incidences.
+
+ Each incidence uniquely identifies a single edge and node.
+ Each incidence has metadata assigned to it. Incidences
+ in a hypergraph are assigned a weight either by default or specified by a user.
+ If :math:`(e,v) \in \mathcal{I}` then :math:`e` *contains* :math:`v`, :math:`v` is an
+ :term:`element ` of :math:`e`, and :math:`v` has :term:`membership ` in :math:`e`.
+
+ incidence matrix
+ A rectangular matrix constructed from a hypergraph, :math:`H = (V, E, \mathcal{I})`. The rows of the matrix are indexed by :math:`V`.
+ The columns of the matrix are indexed by :math:`E`. An entry in the matrix at
+ position :math:`(v,e)` for some :math:`v \in V` and :math:`e \in E` is nonzero if and only if :math:`(e,v) \in I`.
+ A *weighted* incidence matrix uses the incidence weight associated with :math:`(e,v)` for the nonzero entry. An *unweighted* incidence
+ matrix has the integer :math:`1` in all nonzero entries.
+
+
+ edges
+ hyperedges
+ A set of objects distinguished by unique identifiers (uids). Each edge has
+ metadata associated with it. Edges are assigned a weight either by default or
+ specified by the user. Edges contain nodes. Nodes are :term:`elements` of edges.
+
+ nodes
+ vertices
+ hypernodes
+ A set of objects distinguished by unique identifiers (uids). Each node has
+ metadata associated with it. Nodes are assigned a weight either by default or
+ specified by the user. Nodes belong to edges. Nodes have :term:`memberships` in edges.
subhypergraph
- A subhypergraph of a hypergraph (Nodes, Edges, Incidence) is a hypergraph (Nodes', Edges', Incidence') such that Nodes' is a subset of Nodes, Edges' is a subset of Edges, and every incident pair (n,e) in (Nodes', Edges', Incidence') is also incident in (Nodes, Edges, Incidence)
-
- subhypergraph induced by a set of nodes
- An induced subhypergraph of a hypergraph (Nodes, Edges, Incidence) is a subhypergraph (Nodes', Edges', Incidence') where a pair (n,e) is incident if and only if it is incident in (Nodes, Edges, Incidence)
+ A subhypergraph of a hypergraph, :math:`H = (V, E, \mathcal{I})`, is a hypergraph, :math:`H' = (V', E', \mathcal{I'})` such that :math:`(e',v') \in \mathcal{I'}` if and only if :math:`e' \in E' \subset E`, :math:`v' \in V' \subset V` and :math:`(e,v) \in \mathcal{I}`.
degree
- Given a hypergraph (Nodes, Edges, Incidence), the degree of a node in Nodes is the number of edges in Edges to which the node is incident.
+ Given a hypergraph :math:`H = (V, E, \mathcal{I})`, the degree of a node in :math:`V` is the number of edges in :math:`E` to which the node is incident.
See also: :term:`s-degree`
dual
- The dual of a hypergraph (Nodes, Edges, Incidence) switches the roles of Nodes and Edges. More precisely, it is the hypergraph (Edges, Nodes, Incidence'), where Incidence' is the function that assigns Incidence(n,e) to each pair (e,n). The :term:`incidence matrix` of the dual hypergraph is the transpose of the incidence matrix of (Nodes, Edges, Incidence).
+ The dual of a hypergraph exchanges the roles of the edges and nodes in the hypergraph.
+ For a hypergraph :math:`H = (V, E, \mathcal{I})` the dual is
+ :math:`H_D = (E, V, \mathcal{I}^T)` where the ordered pairs in :math:`\mathcal{I}^T` are the transposes of the ordered pairs in :math:`\mathcal{I}`. The :term:`incidence matrix` of :math:`H_D` is the transpose of the incidence matrix of :math:`H`.
toplex
- A toplex in a hypergraph (Nodes, Edges, Incidence ) is an edge e whose node set isn't properly contained in the node set of any other edge. That is, if f is another edge and ever node incident to e is also incident to f, then the node sets of e and f are identical.
+ A toplex in a hypergraph, :math:`H = (V, E, \mathcal{I})`, is an edge :math:`e \in E` whose set of elements is not properly contained in any other edge in :math:`E`. That is, if :math:`f \in E` and the elements of :math:`e` are all elements of :math:`f` then the elements of :math:`f` are all elements of :math:`e`.
simple hypergraph
A hypergraph for which no edge is completely contained in another.
--------------
-S-line graphs
--------------
+ s-adjacent
+ For a hypergraph, :math:`H = (V, E, \mathcal{I})`, and positive integer s,
+ two nodes in :math:`V` are s-adjacent if there are at least s edges in :math:`E`, which contain both of them.
-HNX offers a variety of tool sets for network analysis, including s-line graphs.
+ s-edge-adjacent
+ For a hypergraph, :math:`H = (V, E, \mathcal{I})`, and positive integer s,
+ two edges in :math:`E` are s-edge-adjacent if
+ they there are at least s nodes in :math:`V` belonging to both of them.
+ Another way of saying this is two edges are s-edge-adjacent if
+ they are s-adjacent in the dual of :math:`H`.
s-adjacency matrix
- For a hypergraph (Nodes, Edges, Incidence) and positive integer s, a square matrix where the elements of Nodes index both rows and columns. The matrix can be weighted or unweighted. Entry (i,j) is nonzero if and only if node i and node j are incident to at least s edges in common. If it is nonzero, then it is equal to the number of shared edges (if weighted) or 1 (if unweighted).
+ For a positive integer s, a square matrix for a hypergraph, :math:`H = (V, E, \mathcal{I})`, indexed by :math:`V` such that an
+ entry :math:`(v_1,v_2)` is nonzero if only if :math:`v_1, v_2 \in V` are s-adjacent. An s-adjacency matrix can be weighted or unweighted, in which case all entries are 0's and 1's.
s-edge-adjacency matrix
- For a hypergraph (Nodes, Edges, Incidence) and positive integer s, a square matrix where the elements of Edges index both rows and columns. The matrix can be weighted or unweighted. Entry (i,j) is nonzero if and only if edge i and edge j share to at least s nodes, and is equal to the number of shared nodes (if weighted) or 1 (if unweighted).
+ An s-edge-adjacency matrix is the s-adjacency matrix for the dual
+ of :math:`H`.
s-auxiliary matrix
- For a hypergraph (Nodes, Edges, Incidence) and positive integer s, the submatrix of the :term:`s-edge-adjacency matrix ` obtained by restricting to rows and columns corresponding to edges of size at least s.
+ s-edge-auxiliary matrix
+ For a hypergraph, :math:`H = (V, E, \mathcal{I})`, and positive integer s, the submatrix of the :term:`s-adjacency matrix` or the :term:`s-edge-adjacency matrix` obtained by removing all 0-rows and 0-columns.
s-node-walk
- For a hypergraph (Nodes, Edges, Incidence) and positive integer s, a sequence of nodes in Nodes such that each successive pair of nodes share at least s edges in Edges.
+ For a hypergraph, :math:`H = (V, E, \mathcal{I})`, and positive integer s, a sequence of nodes in :math:`V` such that each successive pair of nodes are s-adjacent. The length of the
+ s-node-walk is the number of adjacent pairs in the sequence.
s-edge-walk
- For a hypergraph (Nodes, Edges, Incidence) and positive integer s, a sequence of edges in Edges such that each successive pair of edges intersects in at least s nodes in Nodes.
+ For a hypergraph, :math:`H = (V, E, \mathcal{I})`, and positive integer s, a sequence of edges in :math:`E` such that each successive pair of edges are s-edge-adjacent. The length of the
+ s-edge-walk is the number of adjacent pairs in the sequence.
s-walk
- Either an s-node-walk or an s-edge-walk.
-
- s-connected component, s-node-connected component
- For a hypergraph (Nodes, Edges, Incidence) and positive integer s, an s-connected component is a :term:`subhypergraph` induced by a subset of Nodes with the property that there exists an s-walk between every pair of nodes in this subset. An s-connected component is the maximal such subset in the sense that it is not properly contained in any other subset satisfying this property.
+ Either an s-node-walk or an s-edge-walk. The length of the
+ s-walk is the number of adjacent pairs in the sequence.
+ s-connected component
+ s-node-connected component
s-edge-connected component
- For a hypergraph (Nodes, Edges, Incidence) and positive integer s, an s-edge-connected component is a :term:`subhypergraph` induced by a subset of Edges with the property that there exists an s-edge-walk between every pair of edges in this subset. An s-edge-connected component is the maximal such subset in the sense that it is not properly contained in any other subset satisfying this property.
+ For a hypergraph, :math:`H = (V, E, \mathcal{I})`, and positive integer s, an s-connected component is a :term:`subhypergraph` induced by a subset of :math:`V` with the property that there exists an s-walk between every pair of nodes in this subset.
+ An s-connected component is the maximal such subset in the sense that it is not properly contained in any other subset satisfying this property.
- s-connected, s-node-connected
- A hypergraph is s-connected if it has one s-connected component.
+ An s-node-connected component is an s-connected component. An
+ s-edge-connected component is an s-connected component of the dual
+ of :math:`H`.
+ s-connected
+ s-node-connected
s-edge-connected
- A hypergraph is s-edge-connected if it has one s-edge-connected component.
+ A hypergraph is s-connected if it has one s-connected component.
+ Similarly for s-node-connected and s-edge-connected.
+
+ s-degree
+ For a hypergraph, :math:`H = (V, E, \mathcal{I})`, and positive integer s, the s-degree of a node, :math:`v \in V` is the number of edges in :math:`E` of size at least s to which :math:`v` belongs. See also: :term:`degree`
s-distance
- For a hypergraph (Nodes, Edges, Incidence) and positive integer s, the s-distances between two nodes in Nodes is the length of the shortest :term:`s-node-walk` between them. If no s-node-walks between the pair of nodes exists, the s-distance between them is infinite. The s-distance
- between edges is the length of the shortest :term:`s-edge-walk` between them. If no s-edge-walks between the pair of edges exist, then s-distance between them is infinite.
+ For a hypergraph, :math:`H = (V, E, \mathcal{I})`, and positive integer s, the s-distances between two nodes in :math:`V` is the length of the shortest :term:`s-node-walk` between them.
+ If no s-node-walk between the pair of nodes exists, the s-distance between them is infinite.
+
+ s-edge-distance
+ The s-edge-distance
+ between two edges in :math:`E` is the length of the shortest :term:`s-edge-walk` between them. If no s-edge-walk between the pair of edges exists, then s-distance between them is infinite.
s-diameter
- For a hypergraph (Nodes, Edges, Incidence) and positive integer s, the s-diameter is the maximum s-Distance over all pairs of nodes in Nodes.
+ For a hypergraph, :math:`H = (V, E, \mathcal{I})`, and positive integer s, the s-diameter is the maximum s-distance over all pairs of nodes in :math:`V`.
- s-degree
- For a hypergraph (Nodes, Edges, Incidence) and positive integer s, the s-degree of a node is the number of edges in Edges of size at least s to which node belongs. See also: :term:`degree`
s-edge
- For a hypergraph (Nodes, Edges, Incidence) and positive integer s, an s-edge is any edge of size at least s.
+ For a hypergraph, :math:`H = (V, E, \mathcal{I})`, and positive integer s, an s-edge is any edge :math:`e \in E` of size at least s, where the
+ size of :math:`e` equals the number of nodes in :math:`V` belonging to :math:`e`.
s-linegraph
- For a hypergraph (Nodes, Edges, Incidence) and positive integer s, an s-linegraph is a graph representing
- the node to node or edge to edge connections according to the *width* s of the connections.
- The node s-linegraph is a graph on the set Nodes. Two nodes in Nodes are incident in the node s-linegraph if they
- share at lease s incident edges in Edges; that is, there are at least s elements of Edges to which they both belong.
- The edge s-linegraph is a graph on the set Edges. Two edges in Edges are incident in the edge s-linegraph if they
- share at least s incident nodes in Nodes; that is, the edges intersect in at least s nodes in Nodes.
-
- .. Bipartite Condition
- .. Condition imposed on instances of the class EntitySet.
- .. *Entities that are elements of the same EntitySet, may not contain each other as elements.*
- .. The elements and children of an EntitySet generate a specific partition for a bipartite graph.
- .. The partition is isomorphic to a Hypergraph where the elements correspond to hyperedges and
- .. the children correspond to the nodes. EntitySets are the basic objects used to construct dynamic hypergraphs
- .. in HNX. See methods :py:meth:`classes.hypergraph.Hypergraph.bipartite` and :py:meth:`classes.hypergraph.Hypergraph.from_bipartite`.
+ For a hypergraph, :math:`H = (V, E, \mathcal{I})`, and positive integer s, an s-linegraph :math:`G` is a graph representing
+ the node to node or edge to edge connections defined by the :term:`s-adjacency matrices`.
+ The node s-linegraph, :math:`G_V` is a graph on the set :math:`V`. Two nodes in :math:`V` are incident in :math:`G_V` if they are :term:`s-adjacent`.
+ The edge s-linegraph, :math:`G_E` is a graph on the set :math:`E`. Two edges in :math:`E` are incident in :math:`G_E` if they are :term:`s-edge-adjacent`.
diff --git a/docs/source/hypconstructors.rst b/docs/source/hypconstructors.rst
index 7596fcc7..062e569e 100644
--- a/docs/source/hypconstructors.rst
+++ b/docs/source/hypconstructors.rst
@@ -9,7 +9,7 @@ An hnx.Hypergraph H = (V,E) references a pair of disjoint sets:
V = nodes (vertices) and E = (hyper)edges.
HNX allows for multi-edges by distinguishing edges by
-their identifiers instead of their contents. For example, if
+their unique identifiers instead of their contents. For example, if
V = {1,2,3} and E = {e1,e2,e3},
where e1 = {1,2}, e2 = {1,2}, and e3 = {1,2,3},
the edges e1 and e2 contain the same set of nodes and yet
@@ -28,6 +28,15 @@ the hypergraph. Cell properties for the incidence pairs can be defined within
the setsystem or in a separate pandas.Dataframe or dict.
Edge and node properties are defined with a pandas.DataFrame or dict.
+A hypergraph is defined by its relationships. While the
+nodes and edges are distinct objects with their own properties, it is only
+when they are in a relationship (i.e. incidence pair) that nodes and egdges are viewable
+within the hypergraph structure. Consequently, hypergraph metrics and combinatorics do not
+use "isolated" nodes or "empty" edges. For example, while `node_properties` could
+contain any number of node identifiers, only nodes belonging to an edge
+in the hypergraph are counted when computing the size and shape of the
+hypergraph.
+
SetSystems
----------
There are five types of setsystems currently accepted by the library.
@@ -35,28 +44,39 @@ There are five types of setsystems currently accepted by the library.
1. **iterable of iterables** : Barebones hypergraph, which uses Pandas default
indexing to generate hyperedge ids. Elements must be hashable.: ::
- >>> H = Hypergraph([{1,2},{1,2},{1,2,3}])
+ >>> list_of_lists = [['book','candle','cat'],['book','coffee cup'],['coffee cup','radio']]
+ >>> H = Hypergraph(list_of_lists)
2. **dictionary of iterables** : The most basic way to express many-to-many
relationships providing edge ids. The elements of the iterables must be
hashable): ::
- >>> H = Hypergraph({'e1':[1,2],'e2':[1,2],'e3':[1,2,3]})
+ >>> scenes_dictionary = {
+ >>> 0: ('FN', 'TH'),
+ >>> 1: ('TH', 'JV'),
+ >>> 2: ('BM', 'FN', 'JA'),
+ >>> 3: ('JV', 'JU', 'CH', 'BM'),
+ >>> 4: ('JU', 'CH', 'BR', 'CN', 'CC', 'JV', 'BM'),
+ >>> 5: ('TH', 'GP'),
+ >>> 6: ('GP', 'MP'),
+ >>> 7: ('MA', 'GP'),
+ >>> 8: ('FN', 'TH')}
+ >>> H = hnx.Hypergraph(scenes_dictionary)
3. **dictionary of dictionaries** : allows cell properties to be assigned
to a specific (edge, node) incidence. This is particularly useful when
there are variable length dictionaries assigned to each pair: ::
- >>> d = {'e1':{ 1: {'w':0.5, 'name': 'related_to'},
- >>> 2: {'w':0.1, 'name': 'related_to',
- >>> 'startdate': '05.13.2020'}},
- >>> 'e2':{ 1: {'w':0.52, 'name': 'owned_by'},
- >>> 2: {'w':0.2}},
- >>> 'e3':{ 1: {'w':0.5, 'name': 'related_to'},
- >>> 2: {'w':0.2, 'name': 'owner_of'},
- >>> 3: {'w':1, 'type': 'relationship'}}
-
- >>> H = Hypergraph(d, cell_weight_col='w')
+ >>> nested_dictionary = {
+ >>> 0: {'FN':{'time':'early', 'weight': 7}, 'TH':{'time':'late'}},
+ >>> 1: {'TH':{'subject':'war'}, 'JV':{'observed_by':'someone'}},
+ >>> 2: {'BM':{}, 'FN':{}, 'JA':{'role':'policeman'}},
+ >>> 3: {'JV':{'was_carrying':'stick'}, 'JU':{}, 'CH':{}, 'BM':{'state':'intoxicated', 'color':'pinkish'}},
+ >>> 4: {'JU':{'weight':15}, 'CH':{}, 'BR':{'state':'worried'}, 'CN':{}, 'CC':{}, 'JV':{}, 'BM':{}},
+ >>> 5: {'TH':{}, 'GP':{}},
+ >>> 6: {'GP':{}, 'MP':{}},
+ >>> 7: {'MA':{}, 'GP':{'accompanied_by':'dog', 'weight':15, 'was_singing': 'Frère Jacques'}}}
+ >>> H = hnx.Hypergraph(nested_dictionary)
4. **pandas.DataFrame** For large datasets and for datasets with cell
properties it is most efficient to construct a hypergraph directly from
@@ -76,26 +96,29 @@ There are five types of setsystems currently accepted by the library.
+-----------+-----------+-----------+-----------------------------------+
| e2 | 1 | 0.52 | {"name":"owned_by"} |
+-----------+-----------+-----------+-----------------------------------+
- | e2 | 2 | 0.2 | |
- +-----------+-----------+-----------+-----------------------------------+
- | ... | ... | ... | {...} |
- +-----------+-----------+-----------+-----------------------------------+
The first row of the dataframe is used to reference each column. ::
- >>> H = Hypergraph(df,edge_col="col1",node_col="col2",
- >>> cell_weight_col="w",misc_cell_properties="col3")
+ >>> import pandas as pd
+ >>> d = {'col1': ['e1', 'e1', 'e2'],
+ >>> 'col2': [1, 2, 1],
+ >>> 'w': [0.5, 0.1, 0.52],
+ >>> 'col3':[{'name': 'related_to'}, {'name': 'related_to', 'startdate':'05.13.2020'}, {'name': 'owned_by'}]}
+ >>> df = pd.DataFrame(d)
+ >>> H = hnx.Hypergraph(df, edge_col="col1", node_col="col2",
+ >>> cell_weight_col="w", misc_cell_properties_col="col3")
5. **numpy.ndarray** For homogeneous datasets given in a *n x 2* ndarray a
- pandas dataframe is generated and column names are added from the
- edge_col and node_col arguments. Cell properties containing multiple data
- types are added with a separate dataframe or dict and passed through the
- cell_properties keyword. ::
+ pandas dataframe is generated. In this case, the constructor will
+ only accept properties for the edges and nodes using the
+ edge and node uids listed in the array, although incidence properties can
+ be added after construction::
- >>> arr = np.array([['e1','1'],['e1','2'],
- >>> ['e2','1'],['e2','2'],
- >>> ['e3','1'],['e3','2'],['e3','3']])
- >>> H = hnx.Hypergraph(arr, column_names=['col1','col2'])
+ >>> import numpy as np
+ >>> np_array = np.array([['A','a'],['A','b'],['A','c'],['B','a'],['B','d'],['C','c'],['C','d']])
+ >>> H = hnx.Hypergraph(np_array)
+ >>> H.incidences[('A','a')].color = 'red'
+ >>> H.dataframe
Edge and Node Properties
@@ -105,11 +128,11 @@ keywords: **edge_properties, node_properties, properties**.
Properties may be passed as dataframes or dicts.
The first column or index of the dataframe or keys of the dict keys
correspond to the edge and/or node identifiers.
-If properties are specific to an id, they may be stored in a single
+If properties are specific to a unique id, they may be stored in a single
object and passed to the **properties** keyword. For example:
+-----------+-----------+---------------------------------------+
-| id | weight | properties |
+| uid | weight | properties |
+-----------+-----------+---------------------------------------+
| e1 | 5.0 | {'type':'event'} |
+-----------+-----------+---------------------------------------+
@@ -126,34 +149,15 @@ object and passed to the **properties** keyword. For example:
A properties dictionary should have the format: ::
- dp = {id1 : {prop1:val1, prop2,val2,...}, id2 : ... }
-
-A properties dataframe may be used for nodes and edges sharing ids
-but differing in cell properties by adding a level index using 0
-for edges and 1 for nodes:
-
-+-----------+-----------+-----------+---------------------------+
-| level | id | weight | properties |
-+-----------+-----------+-----------+---------------------------+
-| 0 | e1 | 5.0 | {'type':'event'} |
-+-----------+-----------+-----------+---------------------------+
-| 0 | e2 | 0.52 | {"name":"owned_by"} |
-+-----------+-----------+-----------+---------------------------+
-| ... | ... | ... | {...} |
-+-----------+-----------+-----------+---------------------------+
-| 1 | 1.2 | {'color':'red'} |
-+-----------+-----------+-----------+---------------------------+
-| 2 | .003 | {'name':'Fido','color':'brown'} |
-+-----------+-----------+-----------+---------------------------+
-| ... | ... | ... | {...} |
-+-----------+-----------+-----------+---------------------------+
-
+ dp = {uid1 : {prop1:val1, prop2,val2,...}, uid2 : ... }
Weights
-------
The default key for cell and object weights is "weight". The default value
-is 1. Weights may be assigned and/or a new default prescribed in the
-constructor using **cell_weight_col** and **cell_weights** for incidence pairs,
-and using **edge_weight_prop, node_weight_prop, weight_prop,
-default_edge_weight,** and **default_node_weight** for node and edge weights.
\ No newline at end of file
+is 1. Weights may be assigned from a column in the dataframe by specifying the
+column and/or a new default in the
+constructor using **cell_weight_col** and **default_cell_weight** for incidence pairs,
+and using **edge_weight_prop_col, default_edge_weight** for edges,
+**node_weight_prop_col, default_node_weight** for nodes,
+and **weight_prop_col, default_weight** for a shared property dataframe.
diff --git a/docs/source/hypergraph101.rst b/docs/source/hypergraph101.rst
index 02f0b5aa..bb79b76e 100644
--- a/docs/source/hypergraph101.rst
+++ b/docs/source/hypergraph101.rst
@@ -114,7 +114,7 @@ if the vertex :math:`v_i` is in edge :math:`e_j`.
- 0
-.. _label3:
+.. _f2:
.. figure:: images/biblio_hg.png
:class: with-border
:width: 400
@@ -296,7 +296,7 @@ can also measure the size of the intersection
define its **width** :math:`s(W) = \min_{0 \le i \le N} s_i` as the size
of the smallest such intersection. When a walk :math:`W` has width
:math:`s`, we call it an :math:`s`-walk. It follows that all walks
-in a graph are 1-walks with width 1. In Fig. `5 <#swalks>`__ we see two
+in a graph are 1-walks with width 1. In :numref:`f5` we see two
walks in a hypergraph. While both have length 2 (counting edgewise, and
recalling origin zero), the one on the left has width 1, and that on the
right width 3.
@@ -369,7 +369,7 @@ one is included in the other, or their intersection is included in both.
This creates a partial order, establishing a further one-to-one mapping
to a variety of lattice structures and dual lattice structures relating
how groups of vertices are included in groups of edges, and vice versa.
-Fig. refex shows the **concept lattice** [3], perhaps the most important
+:numref:`f7` shows the **concept lattice** [3], perhaps the most important
of these structures, determined by our example.
.. _f7:
diff --git a/docs/source/images/code_structure.png b/docs/source/images/code_structure.png
new file mode 100644
index 00000000..5ee964c6
Binary files /dev/null and b/docs/source/images/code_structure.png differ
diff --git a/docs/source/index.rst b/docs/source/index.rst
index a4f74479..df2b8110 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -37,7 +37,12 @@ Our shared values as software developers guide us in our day-to-day interactions
Contact us
----------
-Questions and comments are welcome! Contact us at
+Questions and comments are welcome!
+
+Add discussion topics and comments at
+ https://github.com/pnnl/HyperNetX/discussions
+
+Contact us directly at
hypernetx@pnnl.gov
Contents
diff --git a/docs/source/install.rst b/docs/source/install.rst
index eb59e085..0c857bb0 100644
--- a/docs/source/install.rst
+++ b/docs/source/install.rst
@@ -2,10 +2,6 @@
Installing HyperNetX
********************
-
-Installation
-############
-
The recommended installation method for most users is to create a virtual environment
and install HyperNetX from PyPi.
@@ -17,7 +13,7 @@ HyperNetX may be cloned or forked from Github_.
Prerequisites
######################
-HyperNetX officially supports Python 3.8, 3.9, 3.10 and 3.11.
+HyperNetX officially supports Python 3.10, 3.11, and 3.12.
Create a virtual environment
@@ -26,7 +22,7 @@ Create a virtual environment
Using Anaconda
*************************
- >>> conda create -n venv-hnx python=3.8 -y
+ >>> conda create -n venv-hnx python=3.11 -y
>>> conda activate venv-hnx
Using venv
@@ -56,43 +52,35 @@ To deactivate your environment, use:
>>> .\env-hnx\Scripts\deactivate
-Installing Hypernetx
-####################
+Installation
+############
-Regardless of how you install HyperNetX, ensure that your environment is activated and that you are running Python >=3.8.
+Regardless of how you install HyperNetX, ensure that your environment is activated and that you are running Python ^3.10,<=3.12.
Installing from PyPi
-*************************
+********************
>>> pip install hypernetx
-If you want to use supported applications built upon HyperNetX (e.g. ``hypernetx.algorithms.hypergraph_modularity`` or
-``hypernetx.algorithms.contagion``), you can install HyperNetX with those supported applications by using
-the following command:
-
- >>> pip install hypernetx[all]
-
-If you are using zsh as your shell, use single quotation marks around the square brackets:
-
- >>> pip install hypernetx'[all]'
Installing from Source
-*************************
+**********************
+
+The source code provides a Makefile to simplify the installation process. Ensure that you have ``make`` and ``git`` installed.
-Ensure that you have ``git`` installed.
>>> git clone https://github.com/pnnl/HyperNetX.git
>>> cd HyperNetX
>>> make venv
>>> source venv-hnx/bin/activate
- >>> pip install .
+ >>> make install
Post-Installation Actions
-##########################
+#########################
Interact with HyperNetX in a REPL
-********************************************
+*********************************
Ensure that your environment is activated and that you run ``python`` on your terminal to open a REPL:
@@ -100,7 +88,7 @@ Ensure that your environment is activated and that you run ``python`` on your te
>>> data = { 0: ('A', 'B'), 1: ('B', 'C'), 2: ('D', 'A', 'E'), 3: ('F', 'G', 'H', 'D') }
>>> H = hnx.Hypergraph(data)
>>> list(H.nodes)
- ['G', 'F', 'D', 'A', 'B', 'H', 'C', 'E']
+ ['A', 'B', 'C', 'D', 'E', 'F', 'G', 'H']
>>> list(H.edges)
[0, 1, 2, 3]
>>> H.shape
@@ -108,7 +96,7 @@ Ensure that your environment is activated and that you run ``python`` on your te
Other Actions if installed from source
-********************************************
+**************************************
If you have installed HyperNetX from source, you can perform additional actions such as viewing the provided Jupyter notebooks
or building the documentation locally.
@@ -121,7 +109,6 @@ Viewing jupyter notebooks
The following command will automatically open the notebooks in a browser.
- >>> make tutorial-deps
>>> make tutorials
@@ -130,9 +117,6 @@ Building documentation
The following commands will build and open a local version of the documentation in a browser:
- >>> make docs-deps
>>> cd docs
>>> make html
>>> open build/index.html
-
-
diff --git a/docs/source/modularity.rst b/docs/source/modularity.rst
index d77f4446..ebf2ec31 100644
--- a/docs/source/modularity.rst
+++ b/docs/source/modularity.rst
@@ -38,27 +38,27 @@ Modularity
Given hypergraph HG and a partition A of its vertices, hypergraph modularity is a measure of the quality of this partition.
Random partitions typically yield modularity near zero (it can be negative) while positive modularity is indicative of the presence
-of dense communities, or modules. There are several variations for the definition of hypergraph modularity, and the main difference lies in the
-weight given to different edges given their size $d$ and purity $c$. Modularity is computed via::
+of dense communities or modules. There are several variations for the definition of hypergraph modularity, and the main difference lies in the
+weight given to different edges given their size :math:`d` and purity :math:`c`. Modularity is computed via::
- q = hmod.modularity(HG, A, wdc=hmod.linear)
+ q = hmod.modularity(HG, A, wdc=hmod.linear)
-where the 'wdc' parameter points to a function that controls the weights (details below).
+where the `wdc` parameter points to a function that controls the weights (details below).
-In a graph, an edge only links 2 nodes, so given partition A, an edge is either within a community (which increases the modularity)
-or between communities. With hypergraphs, we consider edges of size $d=2$ or more. Given some vertex partition A and some $d$-edge $e$, let $c$ be the number of nodes
-that belong to the most represented part in $e$; if $c > d/2$, we consider this edge to be within the part.
-Hyper-parameters $0 \le w(d,c) \le 1$ control the weight
+In a graph, an edge only links two nodes; so given partition A, an edge is either within a community (which increases the modularity)
+or between communities. With hypergraphs, we consider edges of size :math:`d=2` or more. Given some vertex partition A and some :math:`d`-edge :math:`e`, let :math:`c` be the number of nodes
+that belong to the most represented part in :math:`e`; if :math:`c > d/2`, we consider this edge to be within the part.
+Hyper-parameters :math:`0 \le w(d,c) \le 1` control the weight
given to such edges. Three functions are supplied in this submodule, namely:
**linear**
- $w(d,c) = c/d$ if $c > d/2$, else $0$.
+ :math:`w(d,c) = c/d` if :math:`c > d/2`, else :math:`0`.
**majority**
- $w(d,c) = 1$ if $c > d/2$, else $0$.
+ :math:`w(d,c) = 1` if :math:`c > d/2`, else :math:`0`.
**strict**
- $w(d,c) = 1$ iff $c = d$, else $0$.
+ :math:`w(d,c) = 1` iff :math:`c = d`, else :math:`0`.
-The 'linear' function is used by default. Other functions $w(d,c)$ can be supplied as long as $0 \le w(d,c) \le 1$ and $w(d,c)=0$ when $c \le d$.
+The 'linear' function is used by default. Other functions :math:`w(d,c)` can be supplied as long as :math:`0 \le w(d,c) \le 1` and :math:`w(d,c)=0` when :math:`c \le d`.
More details can be found in [2].
Two-section graph
diff --git a/docs/source/overview/index.rst b/docs/source/overview/index.rst
index 2c5e4e82..22d1543e 100644
--- a/docs/source/overview/index.rst
+++ b/docs/source/overview/index.rst
@@ -15,47 +15,47 @@ Overview
COLAB Tutorials
================
The following tutorials may be run in your browser using Google Colab. Additional tutorials are
-available on `GitHub `_.
+available on `GitHub `_.
.. raw:: html