diff --git a/.cz.toml b/.cz.toml index 70ea04bb..5b677217 100644 --- a/.cz.toml +++ b/.cz.toml @@ -1,6 +1,6 @@ [tool.commitizen] name = "cz_conventional_commits" -version = "2.1.3" +version = "2.1.4" version_files = [ "setup.py", "docs/source/conf.py", diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index ccc6d8fa..5ed2fed4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,39 +1,73 @@ -# Contributor orientation +# Contributing to HyperNetX -If you have ideas for improving this project, we would love to hear from you! +## Code of Conduct -## Orientation +We want this community to be friendly and respectful to each other. Please read [the full text](CODE_OF_CONDUCT.md) so that you can understand what actions will and will not be tolerated. + +## Requirements + +- Python >=3.8,<3.12 + +## Our Development Process + +### Development workflow + +> **Working on your first pull request?** You can learn how from this *free* series: [How to Contribute to an Open Source Project on GitHub](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project). + +1. Fork the repo and create your branch from the `develop` branch. Here's a guide on [how to fork a repository](https://help.github.com/articles/fork-a-repo/). +1. Create a Python virtual environment. For convenience, our Makefile provides a target called 'venv' that will create a virtual environment for you. Run the following command: `make venv` +1. Activate the virtual environment. If you used the Makefile target in the previous step, activate the virtual environment by the running the following command: `source venv-hnx/bin/activate` +1. Install the library in development mode: `pip install -e .` +1. Install testing dependencies: `pip install -e .['testing'] ` +1. Do the changes you want and ensure all tests pass by running `python -m pytest` before sending a pull request. + +### Commit message convention + +Ensure that commit messages begin with a verb and are in the present tense. Write meaningful commit messages that concisely describes the changes in a commit. +Read this blog post, [How to Write a Git Commit Message](https://cbea.ms/git-commit/) for some guidance. + +### Linting and tests + + We use `pylint` and `black` for linting and formatting the code, and `pytest` for testing. + +We have included a pre-commit config file that can be used to install pre-commit hooks that will lint your code changes every time you create a commit. +To install pre-commit, you must first install the testing dependencies: `pip install -e .['testing']`. Then run: `pre-commit install`. + +Once installed, every time you create a new commit, the linters and formatters will run on the changed code. It is highly recommended to use these `pre-commit` hooks +because these same hooks are run in our CI/CD pipelines on every pull request. Catching pre-commit issues early will prevent CI/CD pipeline issues on your pull request. + +### Sending a pull request + +- Prefer small pull requests focused on one change. +- Verify that and all tests are passing. +- Verify all in-code documentation is correct (it will be used to generate API documentation). -The world of open source is wide; it can be a lot to take in! If this is your first time working with an open source project, then welcome! If you're an experienced contributor, then welcome back! Either way, this online resource might help you [get oriented, or brush up](https://opensource.guide/how-to-contribute/) on the process. ## Report an issue, bug, or feature request -Here are the [steps to creating an issue on github](https://docs.github.com/en/issues/tracking-your-work-with-issues/quickstart). When reporting a bug, +Here are the [steps to creating an issue on GitHub](https://docs.github.com/en/issues/tracking-your-work-with-issues/quickstart). When reporting a bug, -- search for related issues on Github. You might be able to get answer without the hassle of creating an issue +- search for related issues on GitHub. You might be able to get answer without the hassle of creating an issue - describe the current behavior and explain which behavior you expected to see instead and why. At this point you can also tell which alternatives do not work for you. - (if applicable) provide error messages - (if applicable) provide a step by step description of the problem; if possible include code that others can use to reproduce it - You may want to **include screenshots and animated GIFs** which help you demonstrate the steps or point out the part which the suggestion is related to. You can use [this tool](https://www.cockos.com/licecap/) to record GIFs on macOS and Windows, and [this tool](https://github.com/colinkeenan/silentcast) or [this tool](https://github.com/GNOME/byzanz) on Linux. - - provide clear, specific title + - provide a clear, specific title - include details on your setup (operating system, python version, etc.) -- use the most recent version of this library and the source language (e.g. Rust); that fixes a lot of problems +- use the most recent version of this library and the source language (e.g. Python); that fixes a lot of problems - here are [more details on getting the most out of issue reporting!](https://marker.io/blog/how-to-write-bug-report) -## Contribute new code - -Here is a [step-by-step guide to writing new code, and submiting it to the project](https://docs.github.com/en/get-started/quickstart/contributing-to-projects) +## Start a Discussion -The more you know about a software library, the easier it is to get started writing code. The best way to learn about this project is its the documentation! See `README.md` to get started. +If you want a forum to collaborate and discuss topics or questions in more depth, feel free to start a discussion on our +[Github Discussions page](https://github.com/pnnl/HyperNetX/discussions). GitHub Discussions is a collaborative +communication forum for the community. Community members can ask and answer questions, share updates, have open-ended +conversations, and follow along on decisions affecting the community's way of working. ## Where can I go for help? If you're stuck or don't know where to begin, then you're in good company -- we've all been there! We're here to help, and we'd love to hear from you: -- open a issue report on Github -- email us at - -# Code of conduct - -Our shared values as software developers guide us in our day-to-day interactions and decision-making. Our open source projects are no exception. Trust, respect, collaboration and transparency are core values we believe should live and breathe within our projects. Our community welcomes participants from around the world with different experiences, unique perspectives, and great ideas to share. Our [code of conduct](CODE_OF_CONDUCT.md) describes these values, and our standards for contributing. +- open an issue report on [GitHub](https://github.com/pnnl/HyperNetX/issues) +- email us at [hypernetx@pnnl.gov](mailto:hypernetx@pnnl.gov) diff --git a/LONG_DESCRIPTION.rst b/LONG_DESCRIPTION.rst index 4de24045..1c7ed11e 100644 --- a/LONG_DESCRIPTION.rst +++ b/LONG_DESCRIPTION.rst @@ -12,11 +12,11 @@ Hypernets project as part of its High Performance Data Analytics (HPDA) program. PNNL is operated by Battelle Memorial Institute under Contract DE-ACO5-76RL01830. * Principal Developer and Designer: Brenda Praggastis -* Development Team: Madelyn Shapiro, Mark Bonicillo +* Development Team: Audun Myers, Mark Bonicillo * Visualization: Dustin Arendt, Ji Young Yun * Principal Investigator: Cliff Joslyn * Program Manager: Brian Kritzstein -* Principal Contributors (Design, Theory, Code): Sinan Aksoy, Dustin Arendt, Mark Bonicillo, Helen Jenne, Cliff Joslyn, Nicholas Landry, Audun Myers, Christopher Potvin, Brenda Praggastis, Emilie Purvine, Greg Roek, Madelyn Shapiro, Mirah Shi, Francois Theberge, Ji Young Yun +* Principal Contributors (Design, Theory, Code): Sinan Aksoy, Dustin Arendt, Mark Bonicillo, Helen Jenne, Cliff Joslyn, Nicholas Landry, Audun Myers, Christopher Potvin, Brenda Praggastis, Emilie Purvine, Greg Roek, Mirah Shi, Francois Theberge, Ji Young Yun The code in this repository is intended to support researchers modeling data as hypergraphs. We have a growing community of users and contributors. diff --git a/README.md b/README.md index ec4625be..26175364 100644 --- a/README.md +++ b/README.md @@ -16,11 +16,11 @@ Hypernets project as part of its High Performance Data Analytics (HPDA) program. PNNL is operated by Battelle Memorial Institute under Contract DE-ACO5-76RL01830. * Principal Developer and Designer: Brenda Praggastis -* Development Team: Madelyn Shapiro, Mark Bonicillo +* Development Team: Audun Myers, Mark Bonicillo * Visualization: Dustin Arendt, Ji Young Yun * Principal Investigator: Cliff Joslyn * Program Manager: Brian Kritzstein -* Principal Contributors (Design, Theory, Code): Sinan Aksoy, Dustin Arendt, Mark Bonicillo, Helen Jenne, Cliff Joslyn, Nicholas Landry, Audun Myers, Christopher Potvin, Brenda Praggastis, Emilie Purvine, Greg Roek, Madelyn Shapiro, Mirah Shi, Francois Theberge, Ji Young Yun +* Principal Contributors (Design, Theory, Code): Sinan Aksoy, Dustin Arendt, Mark Bonicillo, Helen Jenne, Cliff Joslyn, Nicholas Landry, Audun Myers, Christopher Potvin, Brenda Praggastis, Emilie Purvine, Greg Roek, Mirah Shi, Francois Theberge, Ji Young Yun The code in this repository is intended to support researchers modeling data as hypergraphs. We have a growing community of users and contributors. diff --git a/docs/source/conf.py b/docs/source/conf.py index 4d9094dc..1a379266 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -19,7 +19,7 @@ import os -__version__ = "2.1.3" +__version__ = "2.1.4" # If extensions (or modules to document with autodoc) are in another directory, diff --git a/docs/source/images/notebook_ipykernel.png b/docs/source/images/notebook_ipykernel.png new file mode 100644 index 00000000..fbdc6b95 Binary files /dev/null and b/docs/source/images/notebook_ipykernel.png differ diff --git a/docs/source/index.rst b/docs/source/index.rst index 9b8d9c17..a4f74479 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -57,7 +57,6 @@ Contents Algorithms: Modularity and Clustering Publications license - long_description Indices and tables diff --git a/docs/source/install.rst b/docs/source/install.rst index ca103f5d..4ce55380 100644 --- a/docs/source/install.rst +++ b/docs/source/install.rst @@ -87,8 +87,30 @@ Post-Installation Actions Running Tests ************** +To run all the tests, ensure that you first install the testing dependencies: + + >>> pip install -e .['testing'] + +Then try running all the tests: + >>> python -m pytest + +Dependencies for some Submodules +******************************** + +Two submodules in the library, ``hypernetx.algorithms.hypergraph_modularity`` and ``hypernetx.algorithms.contagion``, +require some additional dependencies. If you want to use those submodules, you will need to install those dependencies. + +For ``hypernetx.algorithms.hypergraph_modularity``, install the following: + + >>> pip install 'igraph>=0.10.4' + +For ``hypernetx.algorithms.contagion``, install the following: + + >>> pip install 'celluloid>=0.2.0' + + Interact with HyperNetX in a REPL ******************************************** diff --git a/docs/source/widget.rst b/docs/source/widget.rst index 8776024d..5805827a 100644 --- a/docs/source/widget.rst +++ b/docs/source/widget.rst @@ -20,11 +20,14 @@ The HypernetxWidget is open source and available on `GitHub `_ It is also `published on PyPi `_ +**The HyperNetX widget is currently in beta with limitations on the Jupyter environment in which it may be used. +It is being actively worked on. Look for improvements and an expanded list of usable environments in a future release.** + Installation ------------ -HyperNetXWidget is currently in beta and will only work on Jupyter Notebook 6.5.x. It is not supported on Jupyter Lab; -support for Jupyter Lab are still in planning. +HyperNetXWidget is currently in beta and will only work on Jupyter Notebook 6.5.x. It is not supported on Jupyter Lab, +but support for Jupyter Lab is in planning. In addition, HyperNetXWidget must be installed using the `Anaconda platform `_ so that the widget can render on Jupyter notebook. It is highly recommended to use the base environment provided by Anaconda because @@ -73,14 +76,25 @@ Open a new shell and run the following commands:: jupyter-notebook -Gotchas -^^^^^^^ +Conda Environment +^^^^^^^^^^^^^^^^^ If the notebook runs into a `ModuleNotFoundError` for the HyperNetX or HyperNetXWidget packages, ensure that you set your kernel to the conda base environment (i.e. `base`). This will ensure that your notebook has the right environment -to run the widget. For more information on setting the environment in Jupyter notebook, see -`How to add your Conda environment to your jupyter notebook in just 4 steps. -`_ +to run the widget. + +On the notebook, click the "New" drop-down button and select "base" as the environment for your notebook. See the +following screenshot as an example: + +.. image:: images/notebook_ipykernel.png + :width: 300px + :align: center + + +| +| For more information on setting the environment in Jupyter notebook, see + `How to add your Conda environment to your jupyter notebook in just 4 steps. + `_ Using the Tool diff --git a/hypernetx/__init__.py b/hypernetx/__init__.py index e06e64ab..ce93dde7 100644 --- a/hypernetx/__init__.py +++ b/hypernetx/__init__.py @@ -11,4 +11,4 @@ from hypernetx.utils import * from hypernetx.utils.toys import * -__version__ = "2.1.3" +__version__ = "2.1.4" diff --git a/hypernetx/algorithms/contagion.py b/hypernetx/algorithms/contagion.py index ec12acf4..74e628e7 100644 --- a/hypernetx/algorithms/contagion.py +++ b/hypernetx/algorithms/contagion.py @@ -68,10 +68,10 @@ def contagion_animation( try: from celluloid import Camera except ModuleNotFoundError as e: - print( - f" {e}. If you need to use {__name__}, please install additional packages by running the following command: pip install .['all']" - ) - raise + raise Exception( + f"If you need to use {__name__}, please install additional packages by running the " + f"following command: pip install .['all']" + ) from e nodeState = defaultdict(lambda: "S") diff --git a/hypernetx/algorithms/hypergraph_modularity.py b/hypernetx/algorithms/hypergraph_modularity.py index a5ea7c99..161661fd 100644 --- a/hypernetx/algorithms/hypergraph_modularity.py +++ b/hypernetx/algorithms/hypergraph_modularity.py @@ -18,12 +18,6 @@ import itertools from scipy.stats import binom -try: - import igraph as ig -except ModuleNotFoundError as e: - print( - f" {e}. If you need to use {__name__}, please install additional packages by running the following command: pip install .['all']" - ) ################################################################################ # we use 2 representations for partitions (0-based part ids): @@ -278,6 +272,15 @@ def two_section(HG): : igraph.Graph The 2-section graph built from HG """ + + try: + import igraph as ig + except ModuleNotFoundError as e: + raise Exception( + f" {e}. If you need to use {__name__}, please install additional packages by running the " + f"following command: pip install .['all']" + ) from e + s = [] for e in HG.edges: E = HG.edges[e] diff --git a/hypernetx/classes/tests/test_hypergraph_by_setsystem.py b/hypernetx/classes/tests/test_hypergraph_by_setsystem.py index 7b4f0e81..6cc7fdcc 100644 --- a/hypernetx/classes/tests/test_hypergraph_by_setsystem.py +++ b/hypernetx/classes/tests/test_hypergraph_by_setsystem.py @@ -1,5 +1,4 @@ import pytest -from pytest_lazyfixture import lazy_fixture as lf from hypernetx import Hypergraph @@ -23,18 +22,18 @@ def test_(hyp: Hypergraph, expected): @pytest.mark.parametrize( - "hyp, expected", + "hypergraph_fixture", [ - (lf("hyp_no_props"), None), - (lf("hyp_df_with_props"), None), - (lf("hyp_dict_with_props"), None), - (lf("hyp_props_on_edges_nodes"), None), + ("hyp_no_props"), + ("hyp_df_with_props"), + ("hyp_dict_with_props"), + ("hyp_props_on_edges_nodes"), ], ) -def test_dual(hyp: Hypergraph, expected): - actual = hyp.dual() +def test_dual(hypergraph_fixture, request): + actual = request.getfixturevalue(hypergraph_fixture).dual() # assertions on the hypergraph assert isinstance(actual, Hypergraph) # assertions on the actual result compared to the expected result that was defined in the parameterize decorator - assert actual != expected + assert actual is not None diff --git a/setup.cfg b/setup.cfg index 5a781cb6..088f2155 100644 --- a/setup.cfg +++ b/setup.cfg @@ -83,7 +83,6 @@ format = testing = pytest>=7.2.2 pytest-cov>=4.1.0 - pytest-lazy-fixture>=0.6.3 pytest-xdist>=3.2.1 pytest-env tox>=4.4.11 diff --git a/setup.py b/setup.py index 51888922..c5c02d7c 100644 --- a/setup.py +++ b/setup.py @@ -1,5 +1,5 @@ from setuptools import setup -__version__ = "2.1.3" +__version__ = "2.1.4" setup(version=__version__) diff --git a/tox.ini b/tox.ini index 29a92bcc..e73113e8 100644 --- a/tox.ini +++ b/tox.ini @@ -6,26 +6,30 @@ [tox] min_version = 4.4.11 -envlist = clean, py{38,39,310,311} +envlist = py{38,39,310,311} isolated_build = True skip_missing_interpreters = true [testenv] -extras = testing +deps = + pytest>=7.2.2 + coverage>=7.2.2 + celluloid>=0.2.0 + igraph>=0.10.4 + nbmake>=1.4.1 + pytest-xdist>=3.2.1 + partition-igraph>=0.0.6 allowlist_externals = env commands = env - coverage run -m pytest -n auto --cov=hypernetx --cov-report term --cov-report html --junit-xml=pytest.xml --cov-fail-under=45 + python --version + coverage run --source=hypernetx -m pytest + coverage report -m [testenv:py38-notebooks] description = run tests on jupyter notebooks -extras = widget allowlist_externals = env commands = - env - pytest --nbmake "tutorials/" -n=auto --nbmake-timeout=20 --nbmake-find-import-errors - -[testenv:clean] -deps = coverage -skip_install = true -commands = coverage erase + env + python --version + pytest --nbmake "tutorials/" --junitxml=pytest.xml -n=auto --nbmake-timeout=20 --nbmake-find-import-errors