ci tools to build documentation in pr and test fix for oom issues in build (#145)

* added ci workflow to build documentation on pull request
* added option to increase border pading around catalog plots
* added function to label figures for publication
* changed test_global_binning to use california_relm_region to preserve memory
* fixed bug in workflow yaml file
* added checklist for pycsep pull requests
* bug in docs run script. removed manual triggering.
* updates to CONTRIBUTING.md

Author: wsavran

.github/workflows/build-sphinx-no-deploy.yml

@@ -0,0 +1,32 @@
+name: docs
+on:
+  pull_request:
+    branches: [ master ]
+jobs:
+  build_docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python 3.7
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.7
+      - name: Install dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install libproj-dev proj-data proj-bin
+          sudo apt-get install libgeos-dev
+          sudo apt-get install python3-sphinx
+          python -m pip install --upgrade pip
+          pip install numpy
+          pip install wheel
+          pip install pytest pytest-cov
+          if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
+          pip install pillow
+      - name: Install PyCSEP
+        run: |
+          python setup.py install
+      - name: Build documentation
+        run: |
+          make -C docs clean
+          make -C docs html

.github/workflows/build-sphinx.yml

@@ -6,9 +6,7 @@ on:
 
 jobs:
   build_docs:
-
     runs-on: ubuntu-latest
-
     steps:
       - uses: actions/checkout@v2
       - name: Set up Python 3.7
@@ -26,11 +24,7 @@ jobs:
           pip install wheel
           pip install pytest pytest-cov
           if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
-          pip install sphinx-gallery>=0.7.0
-          pip install sphinx-rtd-theme
           pip install pillow
-          pip uninstall -y shapely
-          pip install shapely --no-binary shapely
       - name: Install PyCSEP
         run: |
           python setup.py install

.github/workflows/python-app.yml

@@ -13,7 +13,6 @@ jobs:
   build:
 
     runs-on: ubuntu-latest
-
     steps:
     - uses: actions/checkout@v2
     - name: Set up Python 3.7

CONTRIBUTING.md

@@ -1,16 +1,16 @@
-# Contributing to PyCSEP
+# Contributing to pyCSEP
 
-This document provides an overview on how to contribute to PyCSEP. It will provide step-by-step instructions and hope to 
+This document provides an overview on how to contribute to pyCSEP. It will provide step-by-step instructions and hope to 
 answer some questions.
 
 
 ## Getting Started
 
 * Make sure you have an active GitHub account
-* Download and install git
-* Read the git documentation
-* Install a development version of PyCSEP
-* If you haven't worked with Git Forks before, make sure to read the documentation linked here:
+* Download and install `git`
+* Read git documentaion if you aren't familiar with `git`
+* Install the **development version** of PyCSEP
+* If you haven't worked with git Forks before, make sure to read the documentation linked here:
 [some helping info](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/working-with-forks).
 
 ## Developer Installation
@@ -24,17 +24,21 @@ We recommend using `conda` to install the development environment.
     conda env create -f requirements.yml
     conda activate csep-dev
     pip install -e .[all]
-    # sync with default repository
+    # add upstream repository
     git remote add upstream https://github.com/SCECCode/pycsep.git
 
-Note: use the commend `conda deactivate` to go back to your regular environment.
+Note: use the command `conda deactivate` to go back to your regular environment when you are done working with pyCSEP.
 
 ## Submitting a Pull Request
 
-Pull requests are great! Please submit them to us! Here's how:
+### Some notes for starting a pull request
+
+Pull requests are how we use your changes to the code! Please submit them to us! Here's how:
 
 1. Make a new branch. For features/additions base your new branch at `master`.
-2. Add a test! Only pull requests for documentation and refactoring do not require a test.
+2. Make sure to add tests! Only pull requests for documentation, refactoring, or plotting features do not require a test.
+3. Also, documentation must accompany new feature requests.
+    - Note: We would really appreciate pull requests that help us improve documentation.
 3. Make sure the tests pass. Run `./run_tests.sh` in the top-level directory of the repo.
 4. Push your changes to your fork and submit a pull request. Make sure to set the branch to `pycsep:master`.
 5. Wait for our review. There may be some suggested changes or improvements. Changes can be made after
@@ -43,9 +47,26 @@ the pull request has been opening by simply adding more commits to your branch.
 Pull requests can be changed after they are opened, so create a pull request as early as possible.
 This allows us to provide feedback during development and to answer any questions.
 
-Please make sure to set the correct branch for your pull request. Also, please do not include large files in your pull request.
-If you feel that you need to add large files, let us know and we can figure something out.
+Also, if you find pyCSEP to be useful, but don't want to contribute to the code we highly encourage updates to the documentation!
 
+Please make sure to set the correct branch for your pull request. Also, please do not include large files in your pull request.
+If you feel that you need to add large files, such as a benchmark forecast, let us know and we can figure something out.
+
+### Tips to get your pull request accepted quickly
+
+1. Any new feature that contains calculations must contain unit-tests to ensure that the calculations are doing what you
+expect. Some exceptions to this are documentation changes and new plotting features. 
+2. Documentation should accompany any new feature additions into the package.
+    * Plotting functions should provide a sphinx-gallery example, which can be found [here](https://github.com/SCECcode/pycsep/blob/master/examples/tutorials/catalog_filtering.py).
+    * More complex features might require additional documentation. We will let you know upon seeing your pull request.
+    * The documentation use sphinx which compiles reST. Some notes on that can be found [here](https://www.sphinx-doc.org/en/master/usage/quickstart.html).
+3. pyCSEP uses pytest as a test runner. Add new tests to the `tests` folder in an existing file or new file starting matching `test_*.py`
+4. New scientific capabilities that are not previously published should be presented to the CSEP science group as part of a 
+science review. This will consist of a presentation that provides a scientific justification for the feature.
+5. Code should follow the [pep8](https://pep8.org/) style-guide.
+6. Functions should use [Google style docstrings](https://www.sphinx-doc.org/en/master/usage/extensions/example_google.html). These 
+get compiled by Sphinx to become part of the documentation.
+ 
 ## Submitting an Issue
 
 Please open an issue if you want to ask a question about PyCSEP.
@@ -54,15 +75,17 @@ Please open an issue if you want to ask a question about PyCSEP.
 * Please apply the correct tag to your issue so others can search
 
 If you want to submit a bug report, please provide the information below:
-* PyCSEP version, Python version, and Platform (Linux, Windows, Mac OSX, etc)
-* How did you install PyCSEP (pip, anaconda, from source...)
+* pyCSEP version, Python version, and Platform (Linux, Windows, Mac OSX, etc)
+* How did you install pyCSEP (pip, anaconda, from source...)
 * Please provide a short, complete, and correct example that demonstrates the issue.
 * If this broke in a recent update, please tell us when it used to work.
 
 ## Additional Resources
 * [Working with Git Forks](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/working-with-forks)
 * [Style Guide](http://google.github.io/styleguide/pyguide.html)
 * [Docs or it doesn’t exist](https://lukeplant.me.uk/blog/posts/docs-or-it-doesnt-exist/)
+* [Quickstart guide for Sphinx](https://www.sphinx-doc.org/en/master/usage/quickstart.html)
+* [Pep8 style guide](https://pep8.org/)
 * Performance Tips:
   * [Python](https://wiki.python.org/moin/PythonSpeed/PerformanceTips)
   * [NumPy and ctypes](https://scipy-cookbook.readthedocs.io/)

PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,26 @@
+# pyCSEP Pull Request Checklist
+
+Please check out the [contributing guidelines](https://github.com/SCECcode/pycsep/blob/master/CONTRIBUTING.md) for some tips 
+on making pull requests to pyCSEP. 
+
+Fixes issue #(*please fill in or delete if not needed*).
+
+## Type of change:
+
+Please delete options that are not relevant.
+
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
+- [ ] Documentation update (this pull request adds no new code)
+- [ ] Unpublished science feature (This may require a science review)
+- [ ] This change requires a documentation update
+
+## Checklist:
+
+- [ ] I have performed a self-review of my own code
+- [ ] I have commented my code, particularly in hard-to-understand areas
+- [ ] I have made corresponding changes to the documentation
+- [ ] My changes generate no new warnings
+- [ ] I have added tests that prove my fix is effective or that my feature works
+- [ ] New and existing unit tests pass locally with my changes

csep/utils/plots.py

@@ -2,6 +2,8 @@
 
 # Third-party imports
 import numpy
+import string
+
 import scipy.stats
 import matplotlib
 from matplotlib import cm
@@ -705,6 +707,7 @@ def plot_catalog(catalog, ax=None, show=False, extent=None, set_global=False, pl
     mag_ticks = plot_args.get('mag_ticks', False)
     labelspacing = plot_args.get('labelspacing', 1)
     region_border = plot_args.get('region_border', True)
+    legend_borderpad = plot_args.get('legend_borderpad', 0.4)
     # cartopy properties
     projection = plot_args.get('projection', ccrs.PlateCarree(central_longitude=0.0))
     basemap = plot_args.get('basemap', None)
@@ -782,7 +785,7 @@ def size_map(markersize, values, scale):
                                                   alpha=0.3)
         ax.legend(handles, numpy.round(mag_ticks, 1),
                   loc=legend_loc, title=legend_title, fontsize=legend_fontsize, title_fontsize=legend_titlesize,
-                  labelspacing=labelspacing, handletextpad=5, framealpha=legend_framealpha)
+                  labelspacing=labelspacing, handletextpad=5, borderpad=legend_borderpad, framealpha=legend_framealpha)
 
     if region_border:
         try:
@@ -1602,4 +1605,18 @@ def plot_calibration_test(evaluation_result, axes=None, plot_args=None, show=Fal
     if show:
         pyplot.show()
 
-    return ax
+    return ax
+
+def add_labels_for_publication(figure, style='bssa', labelsize=16):
+    """ Adds publication labels too the outside of a figure. """
+    all_axes = figure.get_axes()
+    ascii_iter = iter(string.ascii_lowercase)
+    for ax in all_axes:
+        # check for colorbar and ignore for annotations
+        if ax.get_label() == 'Colorbar':
+            continue
+        annot = next(ascii_iter)
+        if style == 'bssa':
+            ax.annotate(f'({annot})', (0.025, 1.025), xycoords='axes fraction', fontsize=labelsize)
+
+    return

requirements.txt

@@ -9,6 +9,7 @@ python-dateutil
 pytest
 vcrpy
 pytest-cov
+sphinx
 sphinx-gallery
 sphinx-rtd-theme
 pillow

requirements.yml

@@ -13,6 +13,7 @@ dependencies:
   - python-dateutil
   - pytest
   - cartopy
+  - sphinx
   - sphinx-gallery
   - sphinx_rtd_theme
   - pillow

tests/test_spatial.py

@@ -5,7 +5,7 @@
 import numpy
 
 from csep.core.regions import CartesianGrid2D, compute_vertex, compute_vertices, _bin_catalog_spatio_magnitude_counts, \
-    _bin_catalog_spatial_counts, _bin_catalog_probability, global_region
+    _bin_catalog_spatial_counts, _bin_catalog_probability, global_region, california_relm_region
 from csep.models import Polygon
 
 
@@ -230,13 +230,17 @@ def test_bin_spatial_magnitudes(self):
         self.assertEqual(test_result[0, 1], 1)
         self.assertEqual(test_result[9, 0], 1)
 
-    def test_global_region_binning(self):
+    def test_binning_using_bounds(self):
+        """ Tests whether point correctly fall within the bin edges.
 
-        gr = global_region()
+        This test is not exhaustive but checks a few points within the region and verifies that the points correctly fall
+        within the bin edges.
+        """
+        gr = california_relm_region()
 
         # test points
-        lons = numpy.array([-178.6, -178.6, -178.02, -177.73, -177.79])
-        lats = numpy.array([-15.88, -51.75, -30.61, -29.98, -30.6])
+        lons = numpy.array([-117.430, -117.505, -117.466, -117.5808, -117.612])
+        lats = numpy.array([35.616, 35.714, 35.652, 35.7776, 35.778])
 
         # directly compute the indexes from the region object
         idxs = gr.get_index_of(lons, lats)