From 9e53c0a6100345f306901cf3b87845a90ada50fd Mon Sep 17 00:00:00 2001 From: Philip Maechling Date: Wed, 3 Nov 2021 13:22:28 -0700 Subject: [PATCH] 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 --- CREDITS.md | 15 ++++ LICENSE => LICENSE.txt | 2 +- README.md | 171 ++++++++++++++++++----------------------- codemeta.json | 46 +++++++++++ 4 files changed, 136 insertions(+), 98 deletions(-) create mode 100644 CREDITS.md rename LICENSE => LICENSE.txt (96%) create mode 100644 codemeta.json diff --git a/CREDITS.md b/CREDITS.md new file mode 100644 index 00000000..4278f38f --- /dev/null +++ b/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! diff --git a/LICENSE b/LICENSE.txt similarity index 96% rename from LICENSE rename to LICENSE.txt index 2fb38d13..0dffb1dd 100644 --- a/LICENSE +++ b/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 diff --git a/README.md b/README.md index d9cfbfd9..51ef37fb 100644 --- a/README.md +++ b/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: +
+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()
+
+ +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. diff --git a/codemeta.json b/codemeta.json new file mode 100644 index 00000000..d61af4d1 --- /dev/null +++ b/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": "wsavran@usc.edu", + "affiliation": { + "@type": "Organization", + "name": "University of Southern California" + } + } + ] +}