|
1 | | -# PyCSEP: Collaboratory for the Study of Earthquake Predictability |
2 | | - |
3 | | - |
4 | | - |
5 | | - |
| 1 | +# pyCSEP: Collaboratory for the Study of Earthquake Predictability |
| 2 | + |
| 3 | + |
6 | 4 |  |
7 | 5 | [](https://cseptesting.org) |
8 | 6 | [](https://codecov.io/gh/SCECcode/pycsep) |
9 | 7 |
|
10 | | -The PyCSEP tools help earthquake forecast model developers evaluate their forecasts with the goal of understanding |
| 8 | +# Description: |
| 9 | +The pyCSEP Toolkit helps earthquake forecast model developers evaluate their forecasts with the goal of understanding |
11 | 10 | earthquake predictability. |
12 | 11 |
|
13 | | -PyCSEP should: |
| 12 | +pyCSEP should: |
14 | 13 | 1. Help modelers become familiar with formats, procedures, and evaluations used in CSEP Testing Centers. |
15 | 14 | 2. Provide vetted software for model developers to use in their research. |
16 | | -3. Provide quantative and visual tools to assess earthquake forecast quality. |
| 15 | +3. Provide quantitative and visual tools to assess earthquake forecast quality. |
17 | 16 | 4. Promote open-science ideas by ensuring transparency and availability of scientific code and results. |
18 | 17 | 5. Curate benchmark models and data sets for modelers to conduct retrospective experiments of their forecasts. |
19 | 18 |
|
20 | | -## Using Conda |
21 | | - |
22 | | -The easiest way to install PyCSEP is using `conda`. It can also be installed using `pip` or built from source. |
23 | | -If you plan on contributing to this package, visit the |
24 | | -[contribution guidelines](https://github.com/SCECcode/pycsep/blob/master/CONTRIBUTING.md) for |
25 | | -installation instructions. We recommend creating a `conda` environment for this installation, but this is not a required step. |
26 | | - |
27 | | - conda create -n pycsep |
28 | | - conda activate pycsep |
29 | | - |
30 | | -Install `pycsep` |
31 | | - |
32 | | - conda install --channel conda-forge pycsep |
33 | | - |
34 | | -## Using Pip |
35 | | - |
36 | | -Before this installation will work, you must **first** install the following system dependencies. The remaining dependencies |
37 | | -should be installed by the installation script. To help manage dependency issues, we recommend using virtual environments |
38 | | -like `virtualenv`. |
39 | | - |
40 | | -Python 3.7 or later (https://python.org) |
41 | | - |
42 | | -NumPy 1.10 or later (https://numpy.org) |
43 | | - Python package for scientific computing and numerical calculations. |
44 | | - |
45 | | -GEOS 3.3.3 or later (https://trac.osgeo.org/geos/) |
46 | | - C++ library for processing geometry. |
47 | | - |
48 | | -PROJ 4.9.0 or later (https://proj4.org/) |
49 | | - Library for cartographic projections. |
50 | | - |
51 | | -Example for Ubuntu: |
52 | | - |
53 | | - sudo apt-get install libproj-dev proj-data proj-bin |
54 | | - sudo apt-get install libgeos-dev |
55 | | - pip install --upgrade pip |
56 | | - pip install numpy |
57 | | - |
58 | | -Example for MacOS: |
59 | | - |
60 | | - brew install proj geos |
61 | | - pip install --upgrade pip |
62 | | - pip install numpy |
63 | | - |
64 | | -### From Source |
65 | | - |
66 | | -Use this approach if you want the most up-to-date code. This creates an editable installation that can be synced with |
67 | | -the latest GitHub commit. |
68 | | - |
69 | | -We recommend using virtual environments when installing python packages from source to avoid any dependency conflicts. We prefer |
70 | | -`conda` as the package manager over `pip`, because `conda` does a good job of handling binary distributions of packages |
71 | | -across multiple platforms. Also, we recommend using the `miniconda` installer, because it is lightweight and only includes |
72 | | -necessary pacakages like `pip` and `zlib`. |
73 | | - |
74 | | -#### Using Conda |
75 | | -If you don't have `conda` on your machine, download and install [Miniconda](https://docs.conda.io/en/latest/miniconda.html). |
76 | | - |
77 | | - git clone https://github.com/SCECcode/pycsep |
78 | | - cd pycsep |
79 | | - conda env create -f requirements.yml |
80 | | - conda activate csep-dev |
81 | | - # Installs in editor mode with all dependencies |
82 | | - pip install -e . |
83 | | - |
84 | | -Note: If you want to go back to your default environment use the command `conda deactivate`. |
85 | | - |
86 | | -#### Using Pip / Virtualenv |
87 | | - |
88 | | -We highly recommend using Conda, because this tools helps to manage binary dependencies on Python packages. If you |
89 | | -must use [Virtualenv](https://packaging.python.org/guides/installing-using-pip-and-virtual-environments/) |
90 | | -follow these instructions: |
91 | | - |
92 | | - git clone https://github.com/SCECcode/pycsep |
93 | | - cd pycsep |
94 | | - python -m virtualenv venv |
95 | | - source venv/bin/activate |
96 | | - # Installs in editor mode with all dependencies |
97 | | - pip install -e .[all] |
98 | | - |
99 | | - Note: If you want to go back to your default environment use the command `deactivate`. |
100 | | - |
101 | | -## Documentation and Changelog |
102 | | - |
103 | | -The documentation can be found at [here](https://cseptesting.org), and the changelog can be found |
104 | | -[here](https://github.com/SCECcode/pycsep/blob/master/CHANGELOG.txt). |
105 | | - |
106 | | -## Releases |
107 | | - |
108 | | -We follow [semver](https://semver.org/) for our versioning strategy. |
| 19 | +# Table of Contents: |
| 20 | +1. [Software Documentation](https://docs.cseptesting.org) |
| 21 | +2. [Installation](#installation) |
| 22 | +3. [Usage](#usage) |
| 23 | +4. [Contributing](#contributing) |
| 24 | +5. [Change Log](https://github.com/SCECcode/pycsep/blob/master/CHANGELOG.txt) |
| 25 | +6. [Credits](#credits) |
| 26 | +7. [License](#license) |
| 27 | + |
| 28 | +# Installation: |
| 29 | +pyCSEP can be installed in several ways. It can be installed using conda or pip package managers or from the |
| 30 | +source code found in the pyCSEP github repo. Researchers interested in contributing to pyCSEP development should |
| 31 | +install pyCSEP from source code. pyCSEP depends on the following software packages. |
| 32 | +These which may be installed automatically, or manually, depending on the installation method used. |
| 33 | +* Python 3.7 or later (https://python.org) |
| 34 | +* NumPy 1.21.3 or later (https://numpy.org) |
| 35 | +* SciPy 1.7.1 or later (https://scipy.org) |
| 36 | +* pandas 1.3.4 or later (https://pandas.pydata.org) |
| 37 | +* cartopy 0.20.0 or later (https://scitools.org.uk/cartopy/docs/latest) |
| 38 | +* GEOS 3.7.2 or later (https://trac.osgeo.org/geos/) |
| 39 | +* PROJ 8.0.0 or later (https://proj.org/) |
| 40 | + |
| 41 | +Please see the [requirements file](https://github.com/SCECcode/pycsep/blob/master/requirements.yml) for a complete list |
| 42 | +of requirements. These are installed automatically when using the `conda` distribution. |
| 43 | + |
| 44 | +Detailed pyCSEP [installation instructions](https://docs.cseptesting.org/getting_started/installing.html) can be found |
| 45 | +in the online pyCSEP documentation. |
| 46 | + |
| 47 | +# Usage: |
| 48 | +Once installed, pyCSEP methods can be invoked from python code by importing package csep. pyCSEP provides objects and |
| 49 | +utilities related to several key concepts: |
| 50 | +* Earthquake Catalogs |
| 51 | +* Earthquake Forecasts |
| 52 | +* Earthquake Forecast Evaluations |
| 53 | +* Regions |
| 54 | + |
| 55 | +An simple example to download and plot an earthquake catalog from the USGS ComCat: |
| 56 | +<pre> |
| 57 | +import csep |
| 58 | +from csep.core import regions |
| 59 | +from csep.utils import time_utils |
| 60 | +start_time = time_utils.strptime_to_utc_datetime('2019-01-01 00:00:00.0') |
| 61 | +end_time = time_utils.utc_now_datetime() |
| 62 | +catalog = csep.query_comcat(start_time, end_time) |
| 63 | +catalog.plot() |
| 64 | +</pre> |
| 65 | + |
| 66 | +Please see [pyCSEP Getting Started](https://docs.cseptesting.org/getting_started/core_concepts) documentation for more examples and tutorials. |
| 67 | + |
| 68 | +# Software Support: |
| 69 | +Software support for pyCSEP is provided by that Southern California Earthquake Center (SCEC) Research Computing Group. |
| 70 | +This group supports several research software distributions including UCVM. Users can report issues and feature requests |
| 71 | +using the pyCSEP github-based issue tracking link below. Developers will also respond to emails sent to the SCEC software contact listed below. |
| 72 | +1. [pyCSEP Issues](https://github.com/SCECcode/pycep/issues) |
| 73 | +2. Email Contact: software [at] scec [dot] usc [dot] edu |
| 74 | + |
| 75 | +# Contributing: |
| 76 | +We welcome contributions to the pyCSEP Toolkit. If you would like to contribute to this package, including software, tests, and documentation, |
| 77 | +please visit the [contribution guidelines](https://github.com/SCECcode/pycsep/blob/master/CONTRIBUTING.md) for guidelines on how to contribute to pyCSEP development. |
| 78 | +pyCSEP contributors agree to abide by the code of conduct found in our [Code of Conduct](CODE_OF_CONDUCT.md) guidelines. |
| 79 | + |
| 80 | +# Credits: |
| 81 | +Development of pyCSEP is a group effort. A list of developers that have contributed to the PyCSEP Toolkit |
| 82 | +are listed in the [credits](CREDITS.md) file in this repository. |
| 83 | + |
| 84 | +# License: |
| 85 | +The pyCSEP software is distributed under the BSD 3-Clause open-source license. Please see the [license](LICENSE.txt) file for more information. |
0 commit comments