1. Introduction to the EQcorrscan package¶
This document is designed to give you an overview of the capabilities and implementation of the EQcorrscan Python package.
1.1. Why EQcorrscan?¶
EQcorrscan is designed to compute detections of earthquakes, or any seismic signal (explosions work really well) using more advanced routines than standard amplitude-ratio methods.
The authors of EQcorrscan foresee this project as an open repository for the development of software for the detection and analysis of repeating and near-repeating earthquakes. This repository will continue to grow and develop and any and all help/criticism will be appreciated.
There are a lot of things that could be added to this project - if you want to get involved a good place to start would be to contribute tests and documentation.
1.2. Installation - Updated for versions > 0.2.7¶
1.2.1. Recommended install method¶
In general we recommend users to install EQcorrscan in a virtual environment, conda will simplify your install greatly (install instructions for anaconda or miniconda are here: conda installation) - we recommend creating a conda environment with the following:
conda config --add channels conda-forge conda create -n eqcorrscan colorama numpy scipy matplotlib obspy bottleneck pyproj # If using bash run: source activate eqcorrscan # If not you should get away with: activate eqcorrscan
To then install EQcorrscan you can simply run:
conda install eqcorrscan
1.2.2. Not-recommended but workable methods¶
There are other ways to install EQcorrscan and it’s dependencies, some details for some of those cases can be found here. We do note that the other methods are more involved, and can be problematic. If you do chose not to use conda then you should definitely test your install (see below).
1.3. Supported environments¶
We support Linux, OSX and Windows environments running Python 2.7 and 3.x.
We do not support Python 2.6.
We will stop support for Python 2.7 in a forthcoming release, for more information see issue #242.
Within core you will find the core routines to generate templates, (template_gen) search for likely templates (bright_lights), compute cross-channel correlations from these templates (match_filter), generate cross-correlation corrected pick-times (lag_calc), and run subspace detection (subspace).
The bright_lights and match_filter submodules have been designed with parallel computing in mind, to the extent that the more cores and machines you have running them (generally) the better. These rely on the python multiprocessing module, and some C extensions using openMP to handle parallelisation at lower-levels.
1.5. Running tests¶
One of the main goals of EQcorrscan is to improve reliability and reproducibility of earthquake detection. To this end, EQcorrscan has a set of tests (you can check how much of our codebase if tested by looked at the badges in the github repository). You can also run these tests yourself locally to ensure that everything runs as you would expect in your environment. Although every effort has been made to ensure these tests run smoothly on all supported environments (using the ci bots), if you do find any issues, please let us know on the github page.
To run the tests you will need to have pytest installed along with a couple of extras (pytest-pep8 and pytest-cov). These can be installed by pip:
pip install pytest pytest-pep8 pytest-cov
To test your installed version of EQcorrscan we provide a test-script. For version<=0.3.2 you should download the script and run it. In later versions this script is included in the package.
This test-script will download the test data and run the tests (you no longer have to clone the git repository). Just run (from anywhere):
Tests will take about half an hour to run (as of version 0.3.2) and will provide a coverage report at the end and notify you of any failures.