Updated readme (#147)

* added extension to file and updatd to standard format readme.md
* Moved credits to Credits file
* Updated wording about installations
* standardized name as PyCSEP in this file
* Added link to Code of Conduct guidelines
* updated url to carc public filesystem
* updated install instructions
* added codemeta.json file and updated CREDITS.md
* updated list of contributors in CREDITS.md
* small modifications to README.md
* updated links to images
* changed example snippet to include plotting
* minor text changes

Co-authored-by: William Savran <[email protected]>

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

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.

codemeta.json

@@ -0,0 +1,46 @@
+{
+    "@context": "https://doi.org/10.5063/schema/codemeta-2.0",
+    "@type": "SoftwareSourceCode",
+    "license": "https://spdx.org/licenses/BSD-3-Clause",
+    "codeRepository": "https://github.com/sceccode/pycsep.git",
+    "dateCreated": "2021-10-31",
+    "datePublished": "2020-10-20",
+    "dateModified": "2021-04-02",
+    "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.",
+    "applicationCategory": "Seismology",
+    "developmentStatus": "active",
+    "funder": {
+        "@type": "Organization",
+        "name": "Southern California Earthquake Center"
+    },
+    "keywords": [
+        "earthquake",
+        "forecasting",
+        "validation"
+    ],
+    "programmingLanguage": [
+        "Python 3"
+    ],
+    "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/)"
+    ],
+    "author": [
+        {
+            "@type": "Person",
+            "givenName": "William",
+            "familyName": "Savran",
+            "email": "[email protected]",
+            "affiliation": {
+                "@type": "Organization",
+                "name": "University of Southern California"
+            }
+        }
+    ]
+}