pre-release commit for v0.5.0 (#149)

wsavran · web-flow · commit 65a838def961 · 2021-11-09T09:41:11.000-08:00
* add _version.py
* update changelog to markdown for github formatting
* update codemeta.json with version information
* add sphinx to requirements in setup.py
* add instructions to documentation about issuing releases
 added downloads badges to readme
* added note about diff results from catalog filtering example
included figure thumbnail in documents for catalog filtering
* moved files relative to conf.py
* changed PyCSEP -&gt; pyCSEP
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,9 +1,37 @@
-v0.4.1 04/14/2021
+# v0.4.2 (11/03/2021)
+
+## Change-log
+- Removed normalization of rates on CL-Test (#117)
+- Added function to compute bin-wise log-likelihood scores (#118)
+- Properly use region to compute spatial counts and spatial magnitude counts in region class (#122)
+- Fix for simplified 'fast' lat-lon ratio calculation (#125)
+- Add feature to read forecasts with swapped lat/lon values in file (#130)
+- Add 'percentile' argument for plotting Poisson evaluations (#131)
+- Modify comparison plot to simultaneously plot T and W tests (#132)
+- Add feature to trace region outline when plotting spatial data sets (#133)
+- Better handling for magnitude ticks in plotting catalogs (#134)
+- Refactor polygon to models module (#135)
+- Added arguments to modify the fontsize for grid labels and basemap plots (#136)
+- Added function to return the midpoints of the valid testing region (#137)
+- Include regions when serializing catalogs to JSON (#138)
+- Add support for spatial forecasts (#142)
+- Upated CI workflows to reduce time required and fix intermittent OOM issues (#145)
+- Adds function `get_event_counts` to catalog forecasts (#146)
+- Updated README.md (#147)
+
+## Credits
+Jose Bayona (@bayonato89)
+Marcus Hermann (@mherrmann3)
+Pablo Iturrieta (@pabloitu)
+Philip Maechling (@pjmaechling)
+
+
+# v0.4.1 04/14/2021
     - Added 'fast' projection option for plotting spatial datasets (#110)
     - Fixed region border missing when plotted in various projections (#110)
     - Fixed bug where ascii catalog-based forecasts could be incorrectly loaded (#111)
 
-v0.4.0 03/24/2021 
+# v0.4.0 03/24/2021 
     - Fixed issue in plot_poisson_consistency_test where one_sided_lower argument not coloring markers correctly
     - Added several plot configurations based on Cartopy 
       - Plotting spatial datasets with ESRI basemap
@@ -14,7 +42,7 @@ v0.4.0 03/24/2021
     - Updates for INGV readers
     - Fixed bug causing certain events to be placed into incorrrect bins
       
-v0.2 11/11/2020
+# v0.2 11/11/2020
   Added new catalog formats, support for masked forecast bins, and bug fixes, where applicable PR id are shown in parenthesis.
 
     - Fixed bug where filtering by catalog by lists did not remove all desired events (#37)
@@ -29,7 +57,7 @@ v0.2 11/11/2020
     
 
 
-v0.1 10/08/2020
+# v0.1 10/08/2020
     Initial release to PyPI and conda-forge
 
     - Poisson evaluations for gridded forecasts
@@ -39,4 +67,4 @@ v0.1 10/08/2020
     - Forecast input and output
     - Documentation at docs.cseptesting.org
 
-v0.1-dev, 08/16/2018 -- Initial release.
+# v0.1-dev, 08/16/2018 -- Initial release.
diff --git a/MANIFEST.in b/MANIFEST.in
@@ -1,8 +1,11 @@
 include README.md
 include CONTRIBUTING.md
 include CODE_OF_CONDUCT.md
-include LICENSE
-include CHANGELOG.txt
+include LICENSE.txt
+include CHANGELOG.md
+include CREDITS.md
+include codemeta.json
+include CITATION.cff
 include run_tests.sh
 include requirements.txt
 include requirements.yml
diff --git a/README.md b/README.md
@@ -1,9 +1,12 @@
 # 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)
+<p align=center>
+    <a target="_blank" href="https://python.org" title="Python version"><img src="https://gist.githubusercontent.com/wsavran/efce311162c32460336a4f9892218532/raw/1b9c060efd1c6e52eb53f82d4249107417d6a5ec/pycsep_python_badge.svg">
+    <a target="_blank" href="https://pypi.org/project/pycsep"><img src="https://img.shields.io/pypi/dm/pycsep">
+    <a target="_blank" href="https://github.com/SCECcode/pycsep/actions"><img src="https://github.com/SCECCode/pycsep/workflows/Python%20application/badge.svg">
+    <a target="_blank" href="https://github.com/SCECcode/pycsep/actions"><img src="https://github.com/SCECCode/csep2/workflows/Build%20sphinx%20documentation/badge.svg">
+    <a target="_blank" href="https://codecov.io/gh/SCECcode/pycsep"><img src="https://codecov.io/gh/SCECcode/pycsep/branch/master/graph/badge.svg?token=HTMKM29MAU">
+</p>
 
 # Description:
 The pyCSEP Toolkit helps earthquake forecast model developers evaluate their forecasts with the goal of understanding
@@ -21,7 +24,7 @@ pyCSEP should:
 2. [Installation](#installation)
 3. [Usage](#usage)
 4. [Contributing](#contributing)
-5. [Change Log](https://github.com/SCECcode/pycsep/blob/master/CHANGELOG.txt)
+5. [Change Log](https://github.com/SCECcode/pycsep/blob/master/CHANGELOG.md)
 6. [Credits](#credits)
 7. [License](#license)
 
diff --git a/codemeta.json b/codemeta.json
@@ -5,12 +5,12 @@
     "codeRepository": "https://github.com/sceccode/pycsep.git",
     "dateCreated": "2021-10-31",
     "datePublished": "2020-10-20",
-    "dateModified": "2021-04-02",
+    "dateModified": "2021-11-03",
     "downloadUrl": "https://github.com/sceccode/pycsep",
     "issueTracker": "https://github.com/sceccode/pycsep/issues",
-    "name": "PyCSEP",
-    "version": "0.4.0",
-    "description": "The PyCSEP Toolkit helps earthquake forecast model developers evaluate their forecasts with the goal of understanding earthquake predictability.",
+    "name": "pyCSEP",
+    "version": "0.5.0",
+    "description": "The pyCSEP Toolkit helps earthquake forecast model developers evaluate their forecasts with the goal of understanding earthquake predictability.",
     "applicationCategory": "Seismology",
     "developmentStatus": "active",
     "funder": {
@@ -27,9 +27,12 @@
     ],
     "softwareRequirements": [
         "Python 3.7 or later (https://python.org)",
-        "NumPy 1.10 or later (https://numpy.org)",
-        "GEOS 3.3.3 or later (https://trac.osgeo.org/geos/)",
-        "PROJ 4.9.0 or later (https://proj4.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/)"
     ],
     "author": [
         {
diff --git a/csep/__init__.py b/csep/__init__.py
@@ -2,6 +2,7 @@
 import os
 import time
 
+from csep._version import __version__
 
 from csep.core import forecasts
 from csep.core import catalogs
@@ -56,9 +57,12 @@
     'strptime_to_utc_datetime',
     'datetime_to_utc_epoch',
     'epoch_time_to_utc_datetime',
-    'utc_now_epoch'
+    'utc_now_epoch',
+    '__version__'
 ]
 
+
+
 def load_stochastic_event_sets(filename, type='csv', format='native', **kwargs):
     """ General function to load stochastic event sets
 
diff --git a/csep/_version.py b/csep/_version.py
@@ -0,0 +1,2 @@
+__version__ = "0.5.0"
+
diff --git a/docs/Makefile b/docs/Makefile
@@ -15,6 +15,10 @@ help:
 livehtml:
 	sphinx-autobuild -b html $(SOURCEDIR) $(ALLSPHINXOPTS) $(BUILDDIR)/html
 
+clean:
+	rm -rf $(BUILDDIR)/*
+	rm -rf auto_examples/
+
 .PHONY: help Makefile
 
 # Catch-all target: route all unknown targets to Sphinx using the new
diff --git a/docs/_static/CSEP2_Logo_CMYK.png b/docs/_static/CSEP2_Logo_CMYK.png
diff --git a/docs/conf.py b/docs/conf.py
@@ -21,16 +21,16 @@
 
 # -- Project information -----------------------------------------------------
 
-project = 'PyCSEP'
+project = 'pyCSEP'
 author = 'William Savran'
 
 html_show_copyright = False
 html_show_sphinx = False
 
 # The short X.Y version
-version = 'v0.4'
+version = 'v0.5'
 # The full version, including alpha/beta/rc tags
-release = 'v0.4.1'
+release = 'v0.5.0'
 
 
 # -- General configuration ---------------------------------------------------
@@ -109,21 +109,25 @@
 html_theme_options = {}
 html_context = {
     "github_links": [
+        (
+            'Getting help',
+            "https://github.com/SCECCode/pycsep/issues"
+        ),
+        (
+            'Change log',
+            "https://github.com/SCECcode/pycsep/blob/master/CHANGELOG.md"
+        ),
         (
             'Contributing',
-            "https://github.com/SCECcode/pycsep/blob/master/CONTRIBUTING.md",
+            "https://github.com/SCECcode/pycsep/blob/master/CONTRIBUTING.md"
         ),
         (
             'Code of Conduct',
-            "https://github.com/SCECcode/pycsep/blob/master/CODE_OF_CONDUCT.md",
+            "https://github.com/SCECcode/pycsep/blob/master/CODE_OF_CONDUCT.md"
         ),
         (
             'License',
-            "https://github.com/SCECcode/pycsep/blob/master/LICENSE",
-        ),
-        (
-            'Getting help',
-            "https://github.com/SCECCode/pycsep/issues",
+            "https://github.com/SCECcode/pycsep/blob/master/LICENSE"
         ),
         (
             'Source Code',
@@ -135,7 +139,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-# html_static_path = ["_static"]
+html_static_path = ["_static"]
 
 # These paths are either relative to html_static_path
 # or fully qualified paths (eg. https://...)
@@ -213,7 +217,7 @@
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    (master_doc, 'pycsep', 'PyCSEP Documentation',
+    (master_doc, 'pycsep', 'pyCSEP Documentation',
      [author], 1)
 ]
 
@@ -224,7 +228,7 @@
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    (master_doc, 'pycsep', 'PyCSEP Documentation',
+    (master_doc, 'pycsep', 'pyCSEP Documentation',
      author, 'William Savran', 'Python tools for earthquake forecast evaluation.',
      'Miscellaneous'),
 ]
diff --git a/docs/getting_started/installing.rst b/docs/getting_started/installing.rst
@@ -1,4 +1,4 @@
-Installing PyCSEP
+Installing pyCSEP
 =================
 
 We are working on a ``conda-forge`` recipe and PyPI distribution.
diff --git a/docs/index.rst b/docs/index.rst
@@ -39,7 +39,6 @@ pyCSEP: Tools for Earthquake Forecast Developers
     reference/glossary
     reference/publications
     reference/roadmap
-    reference/changelog
     reference/developer_notes
     reference/api_reference
 
diff --git a/docs/reference/changelog.rst b/docs/reference/changelog.rst
diff --git a/docs/reference/developer_notes.rst b/docs/reference/developer_notes.rst
@@ -1,45 +1,45 @@
 Developer Notes
 ===============
 
-Last updated: 10 August 2020
+Last updated: 3 November 2021
 
-Reproducibility Files
----------------------
+Creating a new release of pyCSEP
+--------------------------------
 
-Store information for reproducibility. This should include the following:
-    1. version information (git hash of commit)
-    2. forecast filename
-    3. evaluation catalog (including necessary information to recreate the filtering properties); maybe just md5
-    4. do we need calculation dates?
+These are the steps required to create a new release of pyCSEP. This requires a combination of updates to the repository
+and Github. You will need to build the wheels for distribution on PyPI and upload them to GitHub to issue a release.
+The final step involves uploading the tar-ball of the release to PyPI. CI tools provided by `conda-forge` will automatically
+bump the version on `conda-forge`. Note: permissions are required to push new versions to PyPI.
 
-Evaluation Results
-------------------
+1. Code changes
+***************
+1. Bump the version number in `_version.py <https://github.com/SCECcode/pycsep/tree/master/csep/_version.py>`_
+2. Update `codemeta.json <https://github.com/SCECcode/pycsep/blob/master/codemeta.json>`_
+3. Update `CHANGELOG.md <https://github.com/SCECcode/pycsep/blob/master/CHANGELOG.md>`_. Include links to Github pull requests if possible.
+4. Update `CREDITS.md <https://github.com/SCECcode/pycsep/blob/master/CREDITS.md>`_ if required.
+5. Update the version in `conf.py <https://github.com/SCECcode/pycsep/blob/master/docs/conf.py>`_.
+6. Issue a pull request that contains these changes.
+7. Merge pull request when all changes are merged into `master` and versions are correct.
 
-* Each evaluation should return an evaluation result class that has an associated .plot() method.
-* We should be able to .plot() most everything that makes sense including forecasts and evaluation results.
+2. Creating source distribution
+*******************************
 
-    * How do we .plot() a catalog?
-    * Should we .plot() a region?
-    * For serialization, we can identify the appropriate class as a string in the class state and use that to create the correct object on load.
+Issue these commands from the top-level directory of the project::
 
-Forecast metadata information
------------------------------
+    python setup.py check
 
-1. Forecast should contain metadata information to identify properties of the forecast
+If that executes with no warnings or failures build the source distribution using the command::
 
-    * Start and end date
-    * Spatial region
-    * Magnitude bins
+    python setup.py sdist
 
-Working with GriddedForecasts
------------------------------
+This creates a folder called `dist` that contains a file called `pycsep-X.Y.Z.tar.gz`. This is the distribution
+that will be uploaded to `PyPI`, `conda-forge`, and Github.
 
-* Right now, we can only spatial counts over the entire magnitude range. What if we wanted to have some control over this?
-* Might want to plot above some magnitude threshold or within some incremental threshold.
-* Should be able to have a method that returns a new GriddedForecast with specified parameters such as min/max magnitude.
-
-Region information
-------------------
-* The region information will need to accommodate more complex spaces including 3D areas and those with non-regular grids (e.g.,
-  quadtrees or meshes)
+Upload to PyPI using `twine`. This requires permissions to push to the PyPI account.
 
+3. Create release on Github
+***************************
+1. Create a new `release <https://github.com/SCECcode/pycsep/releases>`_ on GitHub. This can be saved as a draft until it's ready.
+2. Copy new updates information from `CHANGELOG.md <https://github.com/SCECcode/pycsep/blob/master/CHANGELOG.md>`_.
+3. Upload tar-ball created from `setup.py`.
+4. Publish release.
diff --git a/docs/reference/roadmap.rst b/docs/reference/roadmap.rst
@@ -4,10 +4,16 @@
 Development Roadmap
 ###################
 
-1. Include simple examples that people should be able work through by hand
-2. Example scripts and/or programs that expand on the tutorials to show users how to complete more complex end-to-end
-   processing tasks
-3. Expand the :mod:`regions<csep.core.regions>` to accommodate more complex regions, such as a quad-tree or triangulated
-   mesh.
+This page contains expected changes for new releases of `pyCSEP`.
+Last updated 3 November 2021.
+
+v0.6.0
+======
+
+1. Include receiver operating characteristic (ROC) curve
+2. Kagan I1 score
+3. Add function to plot spatial log-likelihood scores
+4. Add documentation section to explain maths of CSEP tests
+
 
 
diff --git a/examples/tutorials/catalog_filtering.py b/examples/tutorials/catalog_filtering.py
@@ -24,6 +24,7 @@
 import csep
 from csep.core import regions
 from csep.utils import time_utils, comcat
+# sphinx_gallery_thumbnail_path = '_static/CSEP2_Logo_CMYK.png'
 
 ####################################################################################################################################
 # Load catalog
@@ -55,7 +56,8 @@
 # We need to define desired start and end times for the catalog using a time-string format. PyCSEP uses integer times for doing
 # time manipulations. Time strings can be converted into integer times using
 # :func:`csep.utils.time_utils.strptime_to_utc_epoch`. The :meth:`csep.core.catalog.AbstractBaseCatalog.filter` also
-# accepts a list of strings to apply multiple filters.
+# accepts a list of strings to apply multiple filters. Note: The number of events may differ if this script is ran
+# at a later date than shown in this example.
 
 # create epoch times from time-string formats
 start_epoch = csep.utils.time_utils.strptime_to_utc_epoch('2019-07-06 03:19:54.040000')
diff --git a/requirements.txt b/requirements.txt
@@ -12,4 +12,4 @@ pytest-cov
 sphinx
 sphinx-gallery
 sphinx-rtd-theme
-pillow
+pillow
diff --git a/setup.py b/setup.py

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-Installing PyCSEP`
	`1`	`+Installing pyCSEP`
`2`	`2`	`=================`
`3`	`3`
`4`	`4`	We are working on a ``conda-forge`` recipe and PyPI distribution.