Merge branch 'SCECcode:master' into master

Author: bayonato89

.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
@@ -22,15 +20,11 @@ jobs:
           sudo apt-get install libgeos-dev
           sudo apt-get install python3-sphinx
           python -m pip install --upgrade pip
-          pip install numpy==1.18.4
+          pip install numpy
           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/)

CREDITS.md

@@ -0,0 +1,15 @@
+PyCSEP development is a group effort.
+
+Contributors:
+* William Savran, Southern California Earthquake Center
+* Pablo Iturrieta, GFZ Potsdam
+* Khawaja Asim, GFZ Potsdam
+* Thomas Beutin, GFZ Potsdam
+* Jose Bayona, University of Bristol
+* Marcus Hermann, University of Naples 'Frederico II'
+* Edric Pauk, Southern California Earthquake Center
+* Max Werner, University of Bristol
+* Danijel Schorlemmner, GFZ Potsdam
+* Philip Maechling, Southern California Earthquake Center
+
+Thanks to everyone for all your contributions! 

LICENSE LICENSE.txtLICENSE renamed to LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2020, The University of Southern California
+Copyright (c) 2021, The University of Southern California
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

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

README.md

@@ -1,108 +1,85 @@
-# PyCSEP: Collaboratory for the Study of Earthquake Predictability
-
-![](http://hypocenter.usc.edu/research/badges/CSEP2_Logo_CMYK.png)
-
-![Python version](http://hypocenter.usc.edu/research/badges/pycsep-python.svg)
+# pyCSEP: Collaboratory for the Study of Earthquake Predictability
+![](https://i.postimg.cc/Bb60rVQP/CSEP2-Logo-CMYK.png)
+![Python version](https://gist.githubusercontent.com/wsavran/efce311162c32460336a4f9892218532/raw/1b9c060efd1c6e52eb53f82d4249107417d6a5ec/pycsep_python_badge.svg)
 ![Python application](https://github.com/SCECCode/csep2/workflows/Python%20application/badge.svg)
 [![Build sphinx documentation](https://github.com/SCECCode/csep2/workflows/Build%20sphinx%20documentation/badge.svg)](https://cseptesting.org)
 [![codecov](https://codecov.io/gh/SCECcode/pycsep/branch/master/graph/badge.svg?token=HTMKM29MAU)](https://codecov.io/gh/SCECcode/pycsep)
 
-The PyCSEP tools help earthquake forecast model developers evaluate their forecasts with the goal of understanding
+# Description:
+The pyCSEP Toolkit helps earthquake forecast model developers evaluate their forecasts with the goal of understanding
 earthquake predictability.
 
-PyCSEP should:
+pyCSEP should:
 1. Help modelers become familiar with formats, procedures, and evaluations used in CSEP Testing Centers.
 2. Provide vetted software for model developers to use in their research.
-3. Provide quantative and visual tools to assess earthquake forecast quality.
+3. Provide quantitative and visual tools to assess earthquake forecast quality.
 4. Promote open-science ideas by ensuring transparency and availability of scientific code and results.
 5. Curate benchmark models and data sets for modelers to conduct retrospective experiments of their forecasts.
 
-## Using Conda
-
-The easiest way to install PyCSEP is using `conda`. It can also be installed using `pip` or built from source. 
-If you plan on contributing to this package, visit the 
-[contribution guidelines](https://github.com/SCECcode/pycsep/blob/master/CONTRIBUTING.md) for 
-installation instructions. We recommend creating a `conda` environment for this installation, but this is not a required step.
-
-    conda create -n pycsep
-    conda activate pycsep
-    
-Install `pycsep`
-
-    conda install --channel conda-forge pycsep
-    
-## Using Pip
-
-Before this installation will work, you must **first** install the following system dependencies. The remaining dependencies
-should be installed by the installation script. To help manage dependency issues, we recommend using virtual environments 
-like `virtualenv`.
-
-Python 3.7 or later (https://python.org)
-
-NumPy 1.10 or later (https://numpy.org)  
-    Python package for scientific computing and numerical calculations.
-
-GEOS 3.3.3 or later (https://trac.osgeo.org/geos/)  
-    C++ library for processing geometry.
-
-PROJ 4.9.0 or later (https://proj4.org/)  
-    Library for cartographic projections. 
-
-Example for Ubuntu:
-
-    sudo apt-get install libproj-dev proj-data proj-bin  
-    sudo apt-get install libgeos-dev 
-    pip install --upgrade pip
-    pip install numpy
-    
-Example for MacOS:
-
-    brew install proj geos
-    pip install --upgrade pip
-    pip install numpy
-    
-### From Source
-
-Use this approach if you want the most up-to-date code. This creates an editable installation that can be synced with 
-the latest GitHub commit. 
-
-We recommend using virtual environments when installing python packages from source to avoid any dependency conflicts. We prefer 
-`conda` as the package manager over `pip`, because `conda` does a good job of handling binary distributions of packages
-across multiple platforms. Also, we recommend using the `miniconda` installer, because it is lightweight and only includes
-necessary pacakages like `pip` and `zlib`. 
-
-#### Using Conda
-If you don't have `conda` on your machine, download and install [Miniconda](https://docs.conda.io/en/latest/miniconda.html).
-
-    git clone https://github.com/SCECcode/pycsep
-    cd pycsep
-    conda env create -f requirements.yml
-    conda activate csep-dev
-    # Installs in editor mode with all dependencies
-    pip install -e .
-    
-Note: If you want to go back to your default environment use the command `conda deactivate`.
-
-#### Using Pip / Virtualenv
-
-We highly recommend using Conda, because this tools helps to manage binary dependencies on Python packages. If you
-must use [Virtualenv](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/)
-follow these instructions:  
-
-    git clone https://github.com/SCECcode/pycsep
-    cd pycsep
-    python -m virtualenv venv
-    source venv/bin/activate
-    # Installs in editor mode with all dependencies
-    pip install -e .[all]
-    
- Note: If you want to go back to your default environment use the command `deactivate`.   
-
-## Documentation and Changelog
-
-The documentation can be found at [here](https://cseptesting.org), and the changelog can be found 
-[here](https://github.com/SCECcode/pycsep/blob/master/CHANGELOG.txt).
-
-## Releases 
-
-We follow [semver](https://semver.org/) for our versioning strategy. 
+# Table of Contents:
+1. [Software Documentation](https://docs.cseptesting.org)
+2. [Installation](#installation)
+3. [Usage](#usage)
+4. [Contributing](#contributing)
+5. [Change Log](https://github.com/SCECcode/pycsep/blob/master/CHANGELOG.txt)
+6. [Credits](#credits)
+7. [License](#license)
+
+# Installation:
+pyCSEP can be installed in several ways. It can be installed using conda or pip package managers or from the 
+source code found in the pyCSEP github repo. Researchers interested in contributing to pyCSEP development should 
+install pyCSEP from source code. pyCSEP depends on the following software packages. 
+These which may be installed automatically, or manually, depending on the installation method used.
+* Python 3.7 or later (https://python.org)
+* NumPy 1.21.3 or later (https://numpy.org)
+* SciPy 1.7.1 or later (https://scipy.org)
+* pandas 1.3.4 or later (https://pandas.pydata.org)
+* cartopy 0.20.0 or later (https://scitools.org.uk/cartopy/docs/latest)
+* GEOS 3.7.2 or later (https://trac.osgeo.org/geos/)
+* PROJ 8.0.0 or later (https://proj.org/)
+
+Please see the [requirements file](https://github.com/SCECcode/pycsep/blob/master/requirements.yml) for a complete list 
+of requirements. These are installed automatically when using the `conda` distribution.
+
+Detailed pyCSEP [installation instructions](https://docs.cseptesting.org/getting_started/installing.html) can be found 
+in the online pyCSEP documentation.
+
+# Usage: 
+Once installed, pyCSEP methods can be invoked from python code by importing package csep. pyCSEP provides objects and 
+utilities related to several key concepts:
+* Earthquake Catalogs
+* Earthquake Forecasts
+* Earthquake Forecast Evaluations
+* Regions
+
+An simple example to download and plot an earthquake catalog from the USGS ComCat:
+<pre>
+import csep
+from csep.core import regions
+from csep.utils import time_utils
+start_time = time_utils.strptime_to_utc_datetime('2019-01-01 00:00:00.0')
+end_time = time_utils.utc_now_datetime()
+catalog = csep.query_comcat(start_time, end_time)
+catalog.plot()
+</pre>
+
+Please see [pyCSEP Getting Started](https://docs.cseptesting.org/getting_started/core_concepts) documentation for more examples and tutorials.
+
+# Software Support:
+Software support for pyCSEP is provided by that Southern California Earthquake Center (SCEC) Research Computing Group. 
+This group supports several research software distributions including UCVM. Users can report issues and feature requests 
+using the pyCSEP github-based issue tracking link below. Developers will also respond to emails sent to the SCEC software contact listed below.
+1. [pyCSEP Issues](https://github.com/SCECcode/pycep/issues)
+2. Email Contact: software [at] scec [dot] usc [dot] edu
+
+# Contributing:
+We welcome contributions to the pyCSEP Toolkit.  If you would like to contribute to this package, including software, tests, and documentation, 
+please visit the [contribution guidelines](https://github.com/SCECcode/pycsep/blob/master/CONTRIBUTING.md) for guidelines on how to contribute to pyCSEP development.
+pyCSEP contributors agree to abide by the code of conduct found in our [Code of Conduct](CODE_OF_CONDUCT.md) guidelines.
+
+# Credits:
+Development of pyCSEP is a group effort. A list of developers that have contributed to the PyCSEP Toolkit 
+are listed in the [credits](CREDITS.md) file in this repository.
+
+# License:
+The pyCSEP software is distributed under the BSD 3-Clause open-source license. Please see the [license](LICENSE.txt) file for more information.