Doc updates (#11)

* Documentation and readme updates

* forgot something...

README.md

@@ -2,48 +2,48 @@
 
 # pyRoCS
 
-This software package is designed to support analysis evaluating Resilience of Complex Systems (RoCS). Resilience is the ability of the complex system being analyzed to withstand, operate through, and recover from a disruption. The complex system may be a physical system such as an electric grid, an organization such as a company, or even a subfunction of an organization. Existing mathematical equations for resilience analysis are found within multiple domains including information theory, biological sciences, and complex systems. This package synthesizes and refactors equations from these various domains to make them more generalizable for application across different types of complex systems relevant for resilience analysis. Users will be able to apply these equations to characterize different components of complex systems based on available data.  
-
-The pyRoCS package includes mathematical formulations of equations from three different domains including information theory, biosciences, and complex systems. The information theory equations include formulations of entropy; Kullback-Leibler Divergence (KLD); novelty, transience, and resonance (NTR); and mutual information. The biosciences equations include formulations of Hill diversity, affinity, and functional redundancy. Lastly, the complex systems equations include formulations of global reaching centrality, cyclomatic complexity, and fluctuating complexity. While these equations are applicable within their specific domains, they can also be applied to resilience analysis of any complex system. Accordingly, their formulations and associated documentation have been generalized in this package to apply across domains. Some of the metrics modifications made for pyRoCS package include: exposing more inputs to the user and enabling them to be implemented with different types of data structures than currently available in scipy (information theory equations), converting equations within the literature into a formal python-based software environment (biosciences and complex system equations). Associated literature that describes the origins of all of the pyRoCS equations are included in the documentation. The package also contains example datasets and tutorials to help demonstrate how the functions can be used.
-
-Note: 'XX' indicate details that will be updated as the package is transferred to its final destination.
-
-
-Installation
-=============
-pyRoCS can be installed using `pip`. See more information at XX
-
-Tutorials
-=========
-To get started with pvops we recommended working with the XX
-
-
-Package Layout and Documentation
-==============
-
-The package is delineated into the following directories: XX
-
-More information about these modules is available at XX
-
-Citing
-======
-
-If using this package, please cite XX
-
-**Citation:** 
-
-XX
-
-**BibTex:**
-
-XX
-
-Contributing
-============
-
-XX
-
-Copyright and License
-=======
-
-XX
+pyRoCS is a library of functions used to support resilience analysis of complex systems. The package contains example datasets and tutorial to help demonstrate how the functions can be used. 
+
+## Installation
+pyRoCS can be installed using `pip`
+
+    pip install pyrocs
+
+Alternatively, pyRoCS can be installed through GitHub
+
+    git clone https://github.com/sandialabs/pyrocs.git
+    cd pyrocs
+    pip install .
+
+## Tutorials
+To get started with pyRoCS, we recommend working through the [tutorials](https://sandialabs.github.io/pyrocs/tutorials.html).
+
+
+## Package Layout and Documentation
+```
+docs
+pyrocs/
+├── biosciences/
+│   ├── affinity
+│   ├── functional_redundancy
+│   └── hill_diversity
+├── complex_systems/
+│   ├── causal_complexity
+│   ├── fluctuation_complexity
+│   └── grc
+└── information_theory/
+    ├── entropy
+    ├── kl_divergence
+    └── mutual_info
+test
+tutorials
+```
+
+## Citing
+A peer-reviewed paper is in progress. So stay tuned for the DOI.
+
+## Contributing
+See the [contributing](https://sandialabs.github.io/pyrocs/contributing.html) page for more info
+
+## Copyright and License
+pyRoCS is licensed through National Technology & Engineering Solutions of Sandia, LLC (NTESS) under a Revised BSD-3 clause. See license file for more information.

docs/apidoc.rst

@@ -1,7 +1,24 @@
-.. _api_documentation:
+.. _api-doc:
 
 API Documentation
 ==================
+Currently, the pyRoCS package includes mathematical formulations of equations from three domains: 
+information theory, biosciences, and complex systems. These domains have advanced how we quantify, 
+store, and communicate information (Information theory); explore interactions between species (biosciences); 
+and consider non-linear interactions between system components (complex systems). 
+
+Functions within pyRoCS are organized into modules that reflect the disciplines from which they 
+originate. While they have distinct origins, the functions can also be applied to resilience 
+analysis of any complex system. Accordingly, their formulations and associated documentation 
+have been generalized in this package. Each of the function's documentation includes information 
+about the original publication used to develop the calculation; see :ref:`references<references>` more details. 
+In addition to converting these equations from the literature into formal Python 
+implementations, the calculations were also modified to support usability 
+(e.g., exposing more inputs to the user and diversifying the types of data 
+structures accepted by the calculations). 
+
+See the links below for more details about the functions captured within each of the modules:
+
 
 .. toctree::
    :maxdepth: 1

docs/contributing.rst

@@ -0,0 +1,62 @@
+.. _contributing:
+
+Contributing
+============
+
+Thank you for wanting to contribute to this library! We will try to make this 
+an easy process for you. If you are looking to contribute code, we recommended that you read 
+the :ref:`development<development>` page. 
+Checking that your PR passes the tests before submission will speed up
+the acceptance of your PR.
+
+Issues and bug reporting
+------------------------
+
+To report issues or bugs please create a new issue on 
+the `pyrocs issues page <https://github.com/sandialabs/pyrocs/issues>`_.
+Before submitting your bug report, please perform a cursory search 
+to see if the problem has been already reported. If it has been reported, 
+and the issue is still open, add a comment to the existing issue instead of opening a new issue.
+
+Guidelines for effective bug reporting
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Use a clear descriptive title for the issue.
+
+- Describe the steps to reproduce the problem, 
+  the behavior you observed after following the steps, and the expected behavior.
+
+- If possible, provide a simple example of the bug using pyrocs example data.
+
+- When relevant, provide information on your computing environment
+  (operating system, python version, pyrocs version or commit).
+
+- For runtime errors, provide a function call stack.
+
+Contributing code
+-----------------
+
+Software developers, within the core development team and external collaborators, 
+are expected to follow standard practices to document and test new code. 
+Software developers interested in contributing to the project are encouraged 
+to create a Fork of the project and submit a Pull Request (PR) using GitHub.
+Pull requests will be reviewed by the core development team.
+Create a PR or help with other PRs which are in the library 
+by referencing `pyrocs PR page <https://github.com/sandialabs/pyrocs/pulls>`_. 
+
+Guidelines for preparing and submitting pull-requests
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- Use a clear descriptive title for your pull-requests
+
+- Describe if your submission is a bugfix, documentation update, or a feature
+  enhancement. Provide a concise description of your proposed changes. 
+
+- Provide references to open issues, if applicable, to provide the necessary
+  context to understand your pull request
+
+- Make sure that your pull-request merges cleanly with the `main` branch of
+  pyrocs. When working on a feature, always create your feature branch off of
+  the latest `main` commit
+
+- Ensure that appropriate documentation and tests accompany any added features.

docs/development.rst

@@ -0,0 +1,39 @@
+.. _development:
+
+Development
+=====================
+
+Installation
+------------
+To maintain a local installation, developers should use the following commands::
+    
+    git clone https://github.com/sandialabs/pyrocs.git
+    cd pyrocs
+    pip install -e .
+
+Testing
+-------
+To test locally, run::
+
+    pytest pyrocs
+
+at the root of the repository. Note that this requires the installation
+of pytest.
+
+Documentation
+------------------
+
+Building docs
+^^^^^^^^^^^^^^^
+To build docs locally, navigate to ``pyrocs/docs`` and run::
+
+    make html
+
+After building, the static html files can be found in ``_build/html``.
+
+Docstrings
+^^^^^^^^^^^
+The pyrocs documentation adheres to the Google style for docstrings. Not only does this
+help to keep a consistent style, but it is also necessary for the API documentation
+to be parsed and displayed correctly. Examples can be found in the 
+`sphinx documentation <https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html>`_.

docs/index.rst

@@ -5,49 +5,28 @@
 
 Overview
 ============
-This software package is designed to support analysis evaluating Resilience 
-of Complex Systems (RoCS). Resilience is the ability of the complex system 
-being analyzed to withstand, operate through, and recover from a disruption. 
-The complex system may be a physical system such as an electric grid, 
-an organization such as a company, or even a subfunction of an organization. 
-Existing mathematical equations for resilience analysis are found within 
-multiple domains including information theory, biological sciences, 
-and complex systems. This package synthesizes and refactors equations 
-from these various domains to make them more generalizable for 
-application across different types of complex systems relevant 
-for resilience analysis. Users will be able to apply these 
-equations to characterize different components of complex 
-systems based on available data.  
-
-The pyRoCS package includes mathematical formulations of equations from 
-three different domains including information theory, biosciences, and 
-complex systems. The information theory equations include formulations of 
-entropy; Kullback-Leibler Divergence (KLD); novelty, transience, and 
-resonance (NTR); and mutual information. The biosciences equations include 
-formulations of Hill diversity, affinity, and functional redundancy. 
-Lastly, the complex systems equations include formulations of global 
-reaching centrality, cyclomatic complexity, and fluctuating complexity. 
-While these equations are applicable within their specific domains, 
-they can also be applied to resilience analysis of any complex system. 
-Accordingly, their formulations and associated documentation have 
-been generalized in this package to apply across domains. Some of 
-the metrics modifications made for pyRoCS package include: exposing 
-more inputs to the user and enabling them to be implemented with 
-different types of data structures than currently available in scipy 
-(information theory equations), converting equations within the 
-literature into a formal python-based software environment (biosciences 
-and complex system equations). Associated literature that describes 
-the origins of all of the pyRoCS equations are included in the 
-documentation. The package also contains example datasets and 
-tutorials to help demonstrate how the functions can be used.
+The purpose of pyRoCS is to support characterization, evaluation, and learning to inform 
+improvements in complex systems. Specifically, the focus on resilience draws attention 
+to the ability of a complex system to withstand, operate through, and recover from a 
+disruption. The complex system may be a physical system such as an electric grid, 
+an organization such as a company, or even a subfunction of an organization. Existing 
+mathematical equations for resilience analysis are found within multiple domains including 
+information theory, biological sciences, and complex systems. This package synthesizes and 
+refactors equations from these various domains to generalize their implementations in a 
+Python environment. 
 
 To get started, we recommend exploring the pyrocs :ref:`tutorials<tutorials>`.
 
+The :ref:`API documentation<apidoc>` provides additional details about the functions included in the package.
+
 .. toctree::
     :maxdepth: 1
     :hidden:
 
     Overview <self>
+    installation
     tutorials
+    contributing
+    development
     apidoc
     references

docs/installation.rst

@@ -0,0 +1,22 @@
+.. _installation:
+
+Installation
+===============
+
+We recommend using a virtual environment when installing pyrocs. 
+`Conda<https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html>` is a popular option for
+virtual environment management.
+Regular tests are run for pyrocs on Python versions 3.9, 3.10, and 3.11 so we recommend installing 
+the package alongside one of these Python versions, although pyrocs may work with other versions as well.
+
+The latest release of pyrocs is accessible via PYPI using the following
+command line prompt::
+
+    $ pip install pyrocs
+
+Alternatively, the package can be installed using github::
+
+    $ git clone https://github.com/sandialabs/pyrocs.git
+    $ cd pyrocs
+    $ pip install .
+

docs/references.rst

@@ -1,3 +1,5 @@
+.. _references:
+
 References
 ==========
 

docs/tutorials.rst

@@ -1,8 +1,15 @@
 .. _tutorials:
 
-pyrocs Tutorials
+Tutorials
 ================
 
+The functions within pyRoCS can be applied to either empirical datasets or simulation environments. 
+For example, they can be used to compare a dataset with a subset to characterize how 
+representativeness the former is of the latter (Tutorial #1). The functions can 
+also be used to characterize layout of organizations (Tutorial #2). More details about the 
+implementation of the functions as well as possible implications of the findings are 
+captured in the below tutorials.
+
 .. nbgallery::
     :caption: Tutorials