EQcorrscan

A python package to conduct matched-filter earthquake detections.

Installation

Installation has been tested on both OSX and Linux (Ubuntu), and now Windows systems. Currently we only support python 2.7, but plan to extend this coverage in the near future - everything is written to work in python 3.x, we just need to get the testing going.

Installation for all systems should be as simple as:

pip install EQcorrscan

If upgrading from a previous version, rather than running install --upgrade, I recommend the following:

pip install -U --no-deps EQcorrscan

This will not try to upgrade your dependencies, which is not needed. You may wish to update your obspy version to 1.0.0 which was recently released. We have tested this and support it, nevertheless, if you find any issues then let us know.

You will likely need sudo/root permissions to run this command.

If you have any issues installing please let me know. You will need to install openCV separately using (on Linux):

apt-get install python-opencv

Or, for Mac users, this is available on Macports or other similar package managers.

For Windows users, you should follow the instructions here, not that you need to copy the cv2.pyd file.

For those who want to run the GUIs (in very early development) you will need to install tk, on Windows and OSX this is usually pre-installed, on Linux you may need to run:

apt-get install python-tk

Updates

If you want to be kept informed about releases, bug-tracking and enhancements without having to keep looking on github, subscribe to our google group.

Documentation

The full documentation for this package can be found here: Docs. Any errors including typos and just missing bits can either be fixed by you, or flagged in the issues tab here. We host our docs on readthedocs, which uses sphinx to scrape the docstrings in the codes, so it is simple to match the docs to the codes and change the docstrings.

We also have a github-pages site EQcorrscan, which uses jekyll to build the site. Changes or additions to this site can be made on the gh-pages branch.

Functionality

This package contains routines to enable the user to conduct match-filter earthquake detections using obspy bindings when reading and writing seismic data, and the correlation routine in openCV. Neither of these packages are installed by this software, due to a range of licenses being implemented. However, both are open-source and should be installed before using this package. This package was written to implement the Matlab routines used by Chamberlain et al. (2014) for the detection of low-frequency earthquakes.

Also within this package are:

• Clustering routines for seismic data;
• Peak finding algorithm (basic, but appropriate for noisy data);
• Automatic amplitude picker for local magnitude scale;
• Seisan S-file integration for database management and routine earthquake location;
• Obspy.core.event integration, which opens up lots of other functions (Seishub, hypoDDpy etc.);
• Stacking routines including phase-weighted stacking based on Thurber at al. (2014);
• Brightness based template creation based on the work of Frank et al. (2014);
• Singular Value Decomposition derived magnitude calculations based on Rubinstein & Ellsworth (2010).

We are currently hovering around 9,000 lines of code (including doc-strings) - it is probably worth having a look at the docs to check what functions we have. We plan to write a series of tutorials to be included on the EQcorrscan API to highlight key functions, currently our tutorials only show how to do the core matched-filter detection.

Licence

This package is written by Calum Chamberlain and Chet Hopp of Victoria University of Wellington, and is distributed under the LGPL GNU License, Copyright Calum Chamberlain and Chet Hopp 2015, 2016.

Contributing

Please fork this project and work on it there then create a pull request to merge back into develop.

When you make changes please run the tests in the test directory to ensure everything merges with minimum effort. If there is not yet a test to cope with your changes then please write one.

Please document your functions following the other documentation within the functions, these doc-scripts will then be built into the main documentation using Sphinx.

We are trying to implement a better branching model, following that found here. To this end, please fork the development branch if you want to develop things, and flag issues in the master for us to bugfix. If you have a feature you want to develop please create a new branch from the development branch and work on it there, we can then merge it back in to the development branch when it is stable enough.

This branching model (git-flow) is pretty well established, and I would recommend you to install git-flow and read their documentation. It seems pretty intuitive and will keep us all branching in the same way.

References

• CJ Chamberlain, DR Shelly, J Townend, TA Stern (2014) Low‐frequency earthquakes reveal punctuated slow slip on the deep extent of the Alpine Fault, New Zealand, G-cubed,doi:10.1002/2014GC005436
• Thurber, C. H., Zeng, X., Thomas, A. M., & Audet, P. (2014). Phase‐Weighted Stacking Applied to Low‐Frequency Earthquakes, BSSA, doi:10.1785/0120140077.
• Frank, W. B., & Shapiro, N. M. (2014). Automatic detection of low-frequency earthquakes (LFEs) based on a beamformed network response, Geophysical Journal International, 197(2), 1215-1223, doi:10.1093/gji/ggu058.
• Rubinstein, J. L., & Ellsworth, W. L. (2010). Precise estimation of repeating earthquake moment: Example from Parkfield, California, BSSA, doi:10.1785/0120100007 fa66e06971b2dd1e4bf766