Pull request #138: Hotfix/joss paper

Merge in HYP/hypernetx from hotfix/joss-paper to master

* commit '3c14988c6b93571fcab8696a324624d75c1a01e7':
  bump: version 2.1.3 → 2.1.4
  Update widget instructions; add screnshot
  Add Discussions section
  Update contributing authors
  HYP-389 Remove testing dependency; update test
  HYP-389 Fix optional dependencies; update documentation
  Pull request #137: Update installation instructions for widget
  HYP-391 Update Contributing guide
  HYP-392 Update post-installation steps documentation

Author: bonicim

.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",

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 <[email protected]>
-
-# 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 [[email protected]](mailto:[email protected])

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.

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.

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,

docs/source/images/notebook_ipykernel.png

@@ -57,7 +57,6 @@ Contents
    Algorithms: Modularity and Clustering <modularity>
    Publications <publications>
    license
-   long_description
 
 
 Indices and tables

docs/source/index.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
 ********************************************
 

docs/source/install.rst

@@ -11,17 +11,91 @@ Hypernetx-Widget
 
 Overview
 --------
-The HyperNetXWidget_ is an addon for HNX, which extends the built in visualization 
-capabilities of HNX to a JavaScript based interactive visualization. The tool has two main interfaces, 
+The HyperNetXWidget is an addon for HNX, which extends the built-in visualization
+capabilities of HNX to a JavaScript based interactive visualization. The tool has two main interfaces,
 the hypergraph visualization and the nodes & edges panel.
-You may `demo the widget here <https://pnnl.github.io/hypernetx-widget/>`_
+You may `demo the widget here <https://pnnl.github.io/hypernetx-widget/>`_.
+
+The HypernetxWidget is open source and
+available on `GitHub <https://github.com/pnnl/hypernetx-widget>`_ It is also `published on PyPi
+<https://pypi.org/project/hnxwidget/>`_
+
+**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
 ------------
-The HypernetxWidget_ is available on `GitHub <https://github.com>`_ and may be
-installed using pip:
 
-    >>> pip install hnxwidget
+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 <https://www.anaconda.com/>`_ so that the
+widget can render on Jupyter notebook. It is highly recommended to use the base environment provided by Anaconda because
+Anaconda's package management system, `conda`, will resolve dependencies when HyperNetX and HyperNetXWidget are
+installed. For more information on `conda` environments, please see `their documentation here.
+<https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#activating-an-environment>`_
+
+**Do not use python's built-in venv module or virtualenv to create a virtual environment; the widget will not render on
+Jupyter notebook.**
+
+Prerequisites
+^^^^^^^^^^^^^
+* conda 23.11.x
+* python 3.11.x
+* jupyter notebook 6.5.4
+* ipywidgets 7.6.5
+
+
+Installation Steps
+^^^^^^^^^^^^^^^^^^
+
+Open a new shell and run the following commands::
+
+    # update conda
+    conda update conda
+
+    # activate the base environment
+    conda activate
+
+    # install hypernetx and hnxwidget
+    pip install hypernetx hnxwidget
+
+    # install jupyter notebook and extensions
+    conda install -y -c anaconda notebook
+    conda install -y -c conda-forge jupyter_contrib_nbextensions
+
+    # install and enable the hnxwidget on jupyter
+    jupyter nbextension install --py --symlink --sys-prefix hnxwidget
+    jupyter nbextension enable --py --sys-prefix hnxwidget
+
+    # install ipykernel and use it to add the base environment to jupyter notebook
+    conda install -y -c anaconda ipykernel
+    python -m ipykernel install --user --name=base
+
+    # start the notebook
+    jupyter-notebook
+
+
+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.
+
+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.
+  <https://medium.com/@nrk25693/how-to-add-your-conda-environment-to-your-jupyter-notebook-in-just-4-steps-abeab8b8d084>`_
+
 
 Using the Tool
 --------------

docs/source/widget.rst

@@ -11,4 +11,4 @@
 from hypernetx.utils import *
 from hypernetx.utils.toys import *
 
-__version__ = "2.1.3"
+__version__ = "2.1.4"