eqcorrscan documentation · python package. 3.1.1why eqcorrscan? eqcorrscan is designed to compute...

EQcorrscanCorrelation for earthquake

detection in Python

EQcorrscan DocumentationRelease 0.3.1

Calum John Chamberlain

Jun 28, 2018

Contents

1 Citation 3

2 References 5

3 Contents: 73.1 Introduction to the EQcorrscan package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73.2 EQcorrscan installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93.3 What’s new . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123.4 EQcorrscan tutorials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173.5 Core . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383.6 Utils . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

Python Module Index 163

i

EQcorrscan Documentation, Release 0.3.1

A Python package for the detection and analysis of repeating and near-repeating seismicity. EQcorrscan containsan efficient, multi-parallel, matched-filter detection routine (template-matching), as well as routines to implementsubspace detection, and detection based on brightness.

Code is stored on , the development branches are , or the latest stable release can be found .

EQcorrscan uses bindings when reading and writing seismic data, and for handling most of the event metadata,which ensures that detections can be easily migrated between softwares. Matched-filter correlations are calculatedusing . OpenCV is not installed alongside EQcorrscan and must be installed before using this package.

Also within this package are:

• Clustering routines for seismic data;

• Peak finding algorithm (basic);

• Automatic amplitude picker for local magnitude scale;

• 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)

This package is written by the EQcorrscan developers, and is distributed under the LGPL GNU Licence, CopyrightEQcorrscan developers 2017.

Contents 1

https://github.com/calum-chamberlain/EQcorrscan/releases


2 Contents

CHAPTER 1

Citation

If you use this package in your work, please cite the following paper: Chamberlain, C. J., Hopp, C. J., Boese,C. M., Warren-Smith, E., Chambers, D., Chu, S. X., Michailos, K., Townend, J., EQcorrscan: Repeating andnear-repeating earthquake detection and analysis in Python. Seismological Research Letters, 2017

3


4 Chapter 1. Citation

CHAPTER 2

References

• CJ Chamberlain, DR Shelly, J Townend, TA Stern (2014) Lowfrequency earthquakes reveal punctuatedslow 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). PhaseWeighted Stacking Applied to LowFre-quency 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.

5

http://onlinelibrary.wiley.com/doi/10.1002/2014GC005436/full

http://onlinelibrary.wiley.com/doi/10.1002/2014GC005436/full

http://www.bssaonline.org/content/early/2014/08/12/0120140077.abstract

http://www.bssaonline.org/content/early/2014/08/12/0120140077.abstract

http://gji.oxfordjournals.org/content/197/2/1215.short



6 Chapter 2. References

CHAPTER 3

Contents:

3.1 Introduction to the EQcorrscan package

This document is designed to give you an overview of the capabilities and implementation of the EQcorrscanPython package.

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

This package was originally based around a matched-filter detection routine which works by comparing templateswith continuous data. The main benefit of EQcorrscan’s matched-filter routine is the level of parallel processingthat can be achieved. EQcorrscan will run on anything from a 1GB RAM single-board computer to a multi-hundred-GB RAM, thousand CPU high-performance computer. Because the internals of EQcorrscan’s matched-filter routine scale reasonably well, the developers have observed speed-ups of 150x (from 2 months to 10 hours)by migrating from a small cluster to a large one (for a 6.5 year long continuous dataset and 800 templates).

The authors of EQcorrscan foresee this project as an open repository for the development of software for thedetection and analysis of repeating and near-repeating earthquakes. This repository will continue to grow anddevelop 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 the best place to start, andthe most valuable thing for your understanding, and for the health of this package would be to contribute tests anddocumentation.

3.1.2 Installation - Updated for version 0.2.7

Recommended install method

In general we recommend users to install EQcorrscan in a virtual environment, will simplify your install greatly(install instuction for anaconda or miniconda are here: ) - we recommend creating a conda environment with thefollowing:

7


conda config --add channels conda-forgeconda 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

Not-recomended but workable methods

There are a myriad of other ways to install EQcorrscan and it’s dependancies, some details for some of those casescan be found here. We do note that the other methods are more involved, and can be problematic. If you do chosenot to use conda then you should definitely test your install.

3.1.3 Supported environments

We support Linux, OSX and Windows environments running Python 2.7, 3.4 and 3.5. We don’t run our tests onother versions of Python so you might have some issues with other Python 3.x series, if you do, let us know.

We do not support Python 2.6.

3.1.4 Functions

This package is divided into sub-directories of core and utils. The utils directory contains simple functions forintegration with , these are in the sfile_util module and functions therein which are essentially barebones and donot have the full functionality that seisan can handle. utils also contains a simple peak-finding algorithm findpeakswhich looks for peaks within noisy data above a certain threshold and within windows.

Many other functions have been added to this module to handle the analysis of repeating and near-repeatingearthquakes, including stacking routines, clustering algorithms, magnitude calculation both by amplitude pickingand by singular value decomposition. I recommend you take a look in here to see if any of it is useful. There arealso some plotting routines that make handling large datasets a little simpler. Most recently I have added a simplesynthetic seismogram generator, which is currently my main project focus.

Since earlier versions the core modules have moved away from using parameter files, and instead rely on explicitargument calls. The parameter files are still included by not documented here (see inside the par files), and remainuseful when generating batch scripts (see the scripts in the github repo).

Within core you will find the core routines to generate templates, (template_gen) search for likely templates(bright_lights) and compute cross-channel correlations from these templates (match_filter). The bright_lights andmatch_filter submodules have been designed with parallel computing in mind, to the extent that the more coresand machines you have running them the better. These rely on the python multiprocessing module to handleparallelisation at lower-levels. You can also do some ‘brute-force’ parallelisation on a day level when computingdetections over multiple days. I tend to run one day per node of a cluster computer, with each day runningtemplates in parallel.

3.1.5 Running tests

One of the main goals of EQcorrscan is to improve reliability and reproducibility of earthquake detection. Tothis end, EQcorrscan has a moderate test-base (you can check how much of our codebase if tested by looked atthe badges in the repository). You can also run these tests yourself locally to ensure that everything runs as youwould expect in your environment. Although every effort has been made to ensure these tests run smoothly on allsupported environments (using the ci bots), if you do find any issues, please let us know on the page.

8 Chapter 3. Contents:


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

You will also need to have a clone of the github repository:

git clone https://github.com/eqcorrscan/EQcorrscan.git

You can then run the tests from within the repository directory:

python setup.py test

Note that if you needed to prepend CC=gcc (if the default compiler is clang) then you will also need to here forthe setup.py command.

If this fails with an error like:

error: invalid command 'pytest'

If you already have an install of EQcorrscan then you can instead run the tests using the following:

pip install requirements.txtpy.test

Otherwise, if you have the pytest error and no previous install of EQcorrscan you can install from source and runthe tests using:

python setup.py installpy.test

Tests will take about half an hour to run (as of v.0.3.0) and will provide a coverage report at the end and notifyyou of any failures.

3.2 EQcorrscan installation

EQcorrscan is a Python package with C extensions. The C extensions in EQcorrscan have their own dependencieson compiled libraries. We heavily recommend installing EQcorrscan using conda because this will:

• make your life easier;

• separate your EQcorrscan install from your system Python, meaning you can experiment to your hearts-content without breaking your operating system (yay);

• ensure that compiled modules are compiled using the correct C-compiler against the correct libraries

If you do not have either a miniconda or anaconda installation you can follow the instructions.

If you do not already have a conda environment we recommend creating one with the following:

conda create -n eqcorrscan colorama numpy scipy matplotlib obspy bottleneck pyprojsource activate eqcorrscan

To then install EQcorrscan you can simply run:

conda install -c conda-forge eqcorrscan

3.2.1 Installation without conda

Installing EQcorrscan without conda involves two steps:

3.2. EQcorrscan installation 9


1. Installing fftw3 libraries;

2. Installing python dependancies and EQcorrscan.

How you undertake the first step depends on your operating system and system package manager.

Non-Python dependencies–Ubuntu:

Prior to installing the python routines you will need to install the fftw library. On linux use apt (or your defaultpackage manager - note you may need sudo access):

apt-get install libfftw3-dev

Note that you will need to ensure you have the single-precision libraries of fftw3 (files named fftw3f. . . ). OnCentOS you can install the fftw-libs package.

Non-Python dependencies–OSX:

For MacOS/OS-X systems we have tested using homebrew and macports (fink options are available, but wehaven’t tested them).

Homebrew

You will need a recent version of gcc (the homebrew gcc-4.9 port has issues with openMP). We have tested thefollowing and found it to work (note that you may need to prepend sudo depending on your configuration):

brew install gcc6brew install fftw

Then run the following to install EQcorrscan (note the need to select CC=gcc, clang, the default compiler, doesnot support modern openMP pragmas):

CC=gcc pip install eqcorrscan

MacPorts

The following has been tested and found to work (note that you may need to prepend sudo depending on yourconfiguration):

1. Install an up-to-date gcc (gcc is needed for openmp compatibility) - any gcc should work (>4), here we usegcc6 for example:

port install gcc6

2. Install python from macports (tested for python35, but its up to you)

port install python35`# optional: select python35 as default python for terminal:port select --set python python35

3. Install numpy and pip from macports:

port install py35-numpy py35-pip# optional, select pip35 as default pipport select --set pip pip35

4. Install fftw3 from source, use –enable-threads and –enable-float (fftw-3 and fftw-3-single from macportsalso available, but not tested)

(a) - link to fftw 3.3.7, most recent as of 10/01/2018

(b) unzip/untar



(c) Run the following from within the expanded directory:

./configure --enable-threads --enable-float && makemake install./configure --enable-threads && make # Need both double and float precision filesmake install

5. Run: (if you didn’t run the port select –set pip pip35 command you will need to replace pip with pip35)

CC=gcc pip install eqcorrscan

Non-Python dependencies–Windows:

For Windows systems you should follow the instructions on the page and use the pre-compiled dynamic libraries.These should be installed somewhere on your system path, or the install location added to your path. The cor-relation routines use openMP for parallel workflows, however, some aspects of this run into issues with versionof MSVC < 10.0 (due to old C standards being used), as such, by default, the correlation routines are compiledas serial workflows on windows. If you have a need for this threading in windows please get in touch with thedevelopers.

EQcorrscan install via pip:

Once you have installed fftw the EQcorrscan install should be as simple as:

pip install eqcorrscan

Installation from source

pip pulls the package from the package repository and runs the setup.py file. If instead you wish to install fromsource, download the package (either by cloning the git repository, or by downloading the source code) from ,change directory to the EQcorrscan directory and run:

python setup.py install

If this fails because the default compiler is clang you can run:

CC=gcc python setup.py install

Note though that this will compile EQcorrscan using a different compiler than used to build your Python, whichmay have unwanted effects, if you do this you MUST test you install using the instructions here: Running tests.

Using Intel’s MKL

For version 0.3.0 EQcorrscan supports compilation against the Intel Math Kernel Libraries (MKL). This has showncompared to the standard FFTW library. To enable this you must install MKL before compiling EQcorrscan. MKLis available from most package managers (including conda). Once you have MKL installed you can follow theInstallation from source section. Check that near the top of the install that the MKL libraries are found.

3.2.2 Notes

You may have issues with these installs if you don’t have numpy installed: but if you don’t have numpy installedthen you have bigger issues. . .

If you plan to run the bright_lights or generating a synthetic grid of templates you will need to have grid csv files,which the authors have previously used NonLinLoc to generate. This is not provided here and should be sourcedfrom . This will provide the Grid2Time routine which is required to set-up a lag-time grid for your velocity model.

3.2. EQcorrscan installation 11


You should read the NonLinLoc documentation for more information regarding how this process works and theinput files you are required to give.

3.3 What’s new

3.3.1 Version 0.3.1

• Cleaned imports in utils modules

• Removed parallel checking loop in archive_read.

• Add better checks for timing in lag-calc functions (#207)

• Removed gap-threshold of twice the template length in Tribe.client_detect, see issue #224.

• Bug-fix: give multi_find_peaks a cores kwarg to limit thread usage.

• Check for the same value in a row in continuous data when computing correlations and zero resultingcorrelations where the whole window is the same value repeated (#224, #230).

• BUG-FIX: template generation from_client methods for swin=P_all or S_all now download all channelsand return them (as they should). See #235 and #206

• Change from raising an error if data from a station are not long enough, to logging a critical warning andnot using the station.

• Add ability to give multiple swin options as a list. Remains backwards compatible with single swin argu-ments.

• Add option to save_progress for long running Tribe methods. Files are written to temporary files local tothe caller.

• Fix bug where if gaps overlapped the endtime set in pre_processing an error was raised - happened whendownloading data with a deliberate pad at either end.

3.3.2 Version 0.3.0

• Compiled peak-finding routine written to speed-up peak-finding.

• Change default match-filter plotting to not decimate unless it has to.

• BUG-FIX: changed minimum variance for fftw correlation backend.

• Do not try to process when no processing needs to be done in core.match_filter._group_process.

• Length checking in core.match_filter._group_process done in samples rather than time.

• BUG-FIX: Fix bug where data lengths were not correct in match_filter.Tribe.detect when sampling time-stamps were inconsistent between channels, which previously resulted in error.

• BUG-FIX: Fix memory-leak in tribe.construct

• Add plotting options for plotting rate to Party.plot

• Add filtering detections by date as Party.filter

• BUG-FIX: Change method for Party.rethreshold: list.remove was not reliable.

• Add option full_peaks to detect methods to map to find_peaks.

• pre-processing (and match-filter object methods) are now gap-aware and will accept gappy traces and canreturn gappy traces. By default gaps are filled to maintain backwards compatibility. Note that the fftwcorrelation backend requires gaps to be padded with zeros.



• Removed sfile_utils This support for Nordic IO has been upgraded and moved to obspy for obspy version1.1.0. All functions are there and many bugs have been fixed. This also means the removal of nordic-specific functions in EQcorrscan - the following functions have been removed: * template_gen.from_sfile* template_gen.from_contbase * mag_calc.amp_pick_sfile * mag_calc.pick_db All removed functions willerror and tell you to use obspy.io.nordic.core. This now means that you can use obspy’s read_events to readin sfiles.

• Added P_all and S_all options to template generation functions to allow creation of multi-channel templatesstarting at the P and S times respectively.

• Refactored template_gen, all options are available via template_gen(method=. . . ), and depreciation warn-ings are in place.

• Added some docs for converting older templates and detections into Template and Party objects.

3.3.3 Version 0.2.7

• Patch multi_corr.c to work with more versions of MSVC;

• Revert to using single-precision floats for correlations (as in previous, < 0.2.x versions) for memory effi-ciency.

3.3.4 Version 0.2.6

• Added the ability to change the correlation functions used in detection methods through the parameterxcorr_func of match_filter, Template.detect and Tribe.detect, or using the set_xcorr context manager in theutils.correlate module. Supported options are:

– numpy

– fftw

– time-domain

– or passing a function that implements the xcorr interface.

• Added the ability to change the concurrency strategy of xcorr functions using the paramter concurrency ofmatch_filter, Template.detect and Tribe.detect. Supported options are:

– None - for single-threaded execution in a single process

– multithread - for multi-threaded execution

– multiprocess- for multiprocess execution

– concurrent - allows functions to describe their own preferred currency

methods, defaults to multithread

• Change debug printing output, it should be a little quieter;

• Speed-up time-domain using a threaded C-routine - separate from frequency domain C-routines;

• Expose useful parallel options for all correlation routines;

• Expose cores argument for match-filter objects to allow limits to be placed on how much of your machineis used;

• Limit number of workers created during pre-processing to never be more than the number of traces in thestream being processed;

• Implement openMP parallelisation of cross-correlation sum routines - memory consumption reduced byusing shared memory, and by computing the cross-correlation sums rather than individual channel cross-correlations. This also leads to a speed-up. This routine is the default concurrent correlation routine;

• Test examples in rst doc files to ensure they are up-to-date;

3.3. What’s new 13


• Tests that were prone to timeout issues have been migrated to run on circleci to allow quick re-starting offails not due to code errors

3.3.5 Version 0.2.5

• Fix bug with _group_process that resulted in stalled processes.

• Force NumPy version

• Support indexing of Tribe and Party objects by template-name.

• Add tests for lag-calc issue with preparing data

• Change internals of eqcorrscan.core.lag_calc._prepare_data to use a dictionary for delays, and to workcorrectly! Issues arose from not checking for masked data properly and not checking length properly.

• Fix bug in match_filter.match_filter when checking for equal length traces, length count was one sample tooshort.

3.3.6 Version 0.2.4

• Increase test coverage (edge-cases) in template_gen;

• Fix bug in template_gen.extract_from_stack for duplicate channels in

template; * Increase coverage somewhat in bright_lights, remove non-parallel option (previously only used fordebugging in development); * Increase test coverage in lag_calc; * Speed-up tests for brightness; * Increase testcoverage for match_filter including testing io of detections; * Increase subspace test coverage for edge cases; *Speed-up catalog_to_dd_tests; * Lag-calc will pick S-picks on channels ending E, N, 1 and 2, change from onlypicking on E and N before; warning added to docs; * Add full tests for pre-processing; * Run tests in parallel onci, speed-up tests dramatically; * Rename singular-value decomposition functions (with depreciation warnings); *Rename SVD_moments to lower-case and add depreciation warning; * Increase test coverage in utils.mag_calc;* Add Template, Tribe, Family, Party objects and rename DETECTION to Detection;

• Template objects maintain meta-data associated with their creation

to stream-line processing of data (e.g. reduce chance of using the wrong filters). * Template eventshave a detect method which takes unprocessed data and does the correct processing using the Tem-plate meta-data, and computes the matched-filter detections. * Tribe objects are containers for mul-tiple Templates. * Tribe objects have a detect method which groups Templates with similar meta-data (processing information) and runs these templates in parallel through the matched-filter routine.Tribe.detect outputs a Party of Family objects. * The Party object is a container for many Familyobjects. * Family objects are containers for detections from the same Template. * Family and Partyobjects have a lag_calc method which computes the cross-correlation pick-refinements. * The upshotof this is that it is possible to, in one line, generate a Tribe of templates, compute their matched-filterdetections, and generate cross-correlation pick refinements, which output Event objects, which canbe written to a catalog:

Tribe.construct(method, **kwargs).detect(st, **kwargs).lag_calc(**kwargs).write()

• Added 25 tests for these methods.

• Add parameters threshold_type and threshold_input to Detection

class. Add support for legacy Detection objects via NaN and unset values.

• Removed support for obspy < 1.0.0

• Update / correct doc-strings in template-gen functions when describing

processing parameters. * Add warning message when removing channels from continuous data in match_filter; *Add min_snr option for template generation routines, if the signal-to-noise ratio is below a user-defined thresh-old, the channel will not be used. * Stop enforcing two-channel template channel names. * Fix bug in de-



tection_multiplot which didn’t allow streams with fewer traces than template; * Update internals to custom Cfftw-based correlation rather than openCV (Major change);

• OpenCV has been removed as a dependancy;

• eqcorrscan.core.match_filter.normxcorr2 now calls a compiled C routine;

• Parallel workflows handled by openMP rather than Python Multiprocessing for matched-filter operations toallow better memory handling.

– It is worth noting that we tried re-writing using SciPy internals

which led to a significant speed-up, but with high memory costs, we ended up going with thisoption, which was the more difficult option, because it allows effective use on SLURM managedsystems where python multiprocessing results in un-real memory spikes (issue #88).

3.3.7 Version 0.2.0-0.2.3

• See 0.2.4: these versions were not fully released while trying to get anaconda packages to build properly.

3.3.8 Version 0.1.6

• Fix bug introduced in version 0.1.5 for match_filter where looping

through multiple templates did not correctly match image and template data: 0.1.5 fix did not work; * Bug-fix incatalog_to_dd for events without magnitudes; * Amend match-filter to not edit the list of template names in place.Previously, if a template was not used (due to no matching continuous data) then the name of the template wasremoved: this now copies the list of template_names internally and does not change the external list.

3.3.9 Version 0.1.5

• Migrate coverage to codecov;

• Fix bug introduced in version 0.1.5 for match_filter where looping

through multiple templates did not correctly match image and template data.

3.3.10 Version 0.1.4

• Bug-fix in plot_repicked removed where data were not normalized properly;

• Bug-fix in lag_calc where data were missing in the continuous data fixed (this led to incorrect picks, majorbug!);

• Output cross-channel correlation sum in lag-calc output;

• Add id to DETECTION objects, which is consistent with the events within DETECTION objects and catalogoutput, and used in lag_calc to allow linking of detections to catalog events;

• Add lots of logging and error messages to lag-calc to ensure user understands limits;

• Add error to day-proc to ensure user is aware of risks of padding;

• Change utils.pre_processing.process to accept different length of data enforcement, not just full day (allowfor overlap in processing, which might be useful for reducing day start and end effects);

• Bug-fix in mag_calc.amp_pick_event, broke loop if data were missing;

• Lots of docs adjustment to sort order of doc-strings and hyper-links;

• Allow multiple uses of the same channel in templates (e.g. you can now use a template with two windowsfrom the same channel, such as a P and an S);

• Add evaluation mode filter to utils.catalog_utils.filter_picks;

3.3. What’s new 15


• Update subspace plot to work when detector is not partitioned;

• Make tests run a little faster;

• Add pep8 testing for all code.

3.3.11 Version 0.1.3

• Now testing on OSX (python 2.7 and 3.5) - also added linux python 3.4;

• Add lag-calculation and tests for it;

• Change how lag-calc does the trace splitting to reduce memory usage;

• Added pick-filtering utility to clean up tutorials;

• Change template generation function names for clarity (wrappers for depreciated names);

• Add more useful error messages when picks are not associated with waveforms;

• Add example plots for more plotting functions;

• Add subspace detector including docs and tutorial.

• Add delayed option to all template_gen functions, set to True by default which retains old behaviour.

3.3.12 Version 0.1.2

• Add handling for empty location information in sfiles;

• Added project setup script which creates a useful directory structure and copies a default match-filter scriptto the directory;

• Add archive reader helper for default script, and parameter classes and definitions for default script;

• Re-write history to make repository smaller, removed trash files that had been added carelessly;

• Now tested on appveyor, so able to be run on Windows;

• Added ability to read hypoDD/tomoDD phase files to obspy events;

• Added simple despiking algorithm - not ideal for correlation as spikes are interpolated around when found:eqcorrscan.utils.despike;

• Option to output catalog object from match_filter - this will become the default once we introduce meta-data to templates - currently the picks for events are the template trace start-times, which will be before thephase-pick by the lag defined in the template creation - also added event into detection class, so you canaccess the event info from the detections, or create a catalog from a list of detections;

• Add option to extract detections at run-time in match_filter.match_filter;

• Edited multi_event_singlechan to take a catalog with multiple picks, but requires you to specify the stationand channel to plot;

• Add normalize option to stacking routines;

• Add tests for stacking - PWS test needs more checks;

• Add many examples to doc-strings, not complete though;

• Change docs to have one page per function.

• Python 3.5 testing underway, all tests pass, but only testing about 65% of codebase.

• Add io functions to match_filter to simplify detection handling including writing detections to catalog andto text file.

• Stricter match_filter testing to enforce exactly the same result with a variety of systems.

• Add hack to template_gen tutorial to fix differences in sorting between python 3.x and python 2.



• Added advanced network triggering routine from Konstantinos, allows different parameters for individualstations - note only uses recursive sta-lta triggering at the moment. Useful for template generations alongsidepickers.

• Added magnitude of completeness and b-value calculators to utils.mag_calc

3.3.13 Version 0.1.1

• Cope with events not always having time_errors in them in eventtoSfile;

• Convert Quakeml depths from m to km;

• Multiple little fixes to make Sfile conversion play well with GeoNet QuakeML files;

• Add function to convert from obspy.core.inventory.station.Station to string format for Seisan STA-TION0.HYP file;

• Merged feature branch - hypoDD into develop, this provides mappings for the hypoDD location program,including generation of dt.cc files;

• Added tests for functions in catalog_to_dd;

• Implemented unittest tests;

• Changed name of EQcorrscan_plotting to plotting;

• Added depreciation warnings;

• Changed internal structure of pre-processing to aid long-term upkeep;

• Added warnings in docs for template_gen relating to template generation from set length files;

• Updated template_creation tutorial to use day-long data;

• Renamed Sfile_util to sfile_util, and functions there-in: will warn about name changes;

• Updated template plotting to include pick labels;

• Updated template_creation tutorial to download S-picks as well as P-picks;

• Update sfile_util to cope with many possible unfilled objects;

• Added sac_util to convert from sac headers to useful event information - note, does not convert all things,just origin and pick times;

• Added from_sac function to template_gen.

3.4 EQcorrscan tutorials

Welcome to EQcorrscan - this package is designed to compute earthquake detections using a paralleled matched-filter network cross-correlation routine, and analyse the results.

Before continuing with this tutorial please check that you have installed all the pre-requisite modules, as not allwill be installed by the setup.py file. The list of these is in the Introduction section of this documentation.

As you will see, this package is divided into two main sub-modules, the core and utils sub-modules. The coresub-module contains the main, high-level functions:

bright_lights A brightness based template detection routine;

template_gen A series of routines to generate templates for match-filter detection from continuousor cut data, with pick-times either defined manually, or defined in event files;

match_filter The main matched-filter routines, this is split into several smaller functions to allowpython-based parallel-processing;

subspace Subspace detection routine based on .

3.4. EQcorrscan tutorials 17


lag_calc Routines for calculating optimal lag-times for events detected by the match-filter routine,these lags can then be used to define new picks for high accuracy re-locations.

Some other high-level functions are included in the utils sub-module and are documented here with tutorials:

mag_calc Simple local magnitude calculation and high-precision relative moment calculation usingsingular-value decomposition.

clustering Routines for clustering earthquakes based on a range of metircs using agglomorative clus-tering methods.

The utils sub-module contains useful, but small functions. These functions are rarely cpu intensive, but performvital operations, such as finding peaks in noisy data (findpeaks), converting a database to hypoDD formattedfiles and computing cross-correlations between detections for (a double difference relocation software) (cata-log_to_dd), calculating magnitudes (mag_calc), clustering detections (clustering), stacking detections (stacking),making pretty plots (plotting), and processing seismic data in the same way repeatedly using ’s functionality(pre_processing).

What follows is an expanding set of tutorials that should take you through some of the key functionality of theEQcorrscan package.

3.4.1 Template creation

Note: These tutorials are for the functional workflow - for details on creating Template and Tribe objects see thematched filter docs page.

Simple example

Within template_gen there are lots of methods for generating templates depending on the type of pick data andwaveform data you are using. Have a look at those to check their simple examples.

Example of how to generate a useful template from data available via FDSN (see for a list of possible clients):

>>> from obspy.clients.fdsn import Client>>> from obspy.core.event import Catalog>>> from eqcorrscan.core.template_gen import from_client>>> client = Client('NCEDC')>>> catalog = client.get_events(eventid='72572665', includearrivals=True)>>> templates = from_client(catalog=catalog, client_id='NCEDC',... lowcut=2.0, highcut=9.0, samp_rate=20.0,... filt_order=4, length=3.0, prepick=0.15,... swin='all', process_len=200)

This will download data for a single event (given by eventid) from the NCEDC database, then use that informationto download relevant waveform data. These data will then be filtered and cut according the parameters set.

It is often wise to set these parameters once as variables at the start of your scripts to ensure that the sameparameters are used for both template creation and matched-filtering.

The method from_client can cope with multiple events (hence the use of a Catalog object), so you can downloada lot of events from your chosen client and generate templates for them all.

Useful considerations

With these data-mining techniques, memory consumption is often an issue, as well as speed. To reduce memoryconsumption and increase efficiency it is often worth using a subset of picks. The advanced example below showsone way to do this. In practice, five picks (and therefore traces in a template) is often sufficient for matched-filterdetections. However, you should test this on your own data.

Some other things that you might want to consider when generating templates include:



• Template-length, you probably only want to include the real earthquake signal in your template, so reallylong templates are probably not the best idea.

• On the same note, don’t include much (if any) data before the P-phase, unless you have good reason to -assuming your noise is random, including noise will reduce the correlations.

• Consider your frequency band - look for peak power in the chosen waveform relative to the noise.

• Coda waves often describe scatterers - scattered waves are very interesting, but may reduce the generality ofyour templates. If this is what you want, include coda, if you want a more general template, I would suggestnot including coda. For examples of this you could try generating a lot of templates from a sequence andcomputing the SVD of the templates to see where the most coherent energy is (in the first basis vector), orjust computing the stack of the waveforms.

Storing templates

Templates are returned as obspy Stream objects. You will likely want to store these templates on disk. This isusually best done by saving them as miniseed files. Miniseed uses an efficient compression algorithm and allowsmultiplexing, which is useful for template storage. However we do not constrain you to this.

>>> templates[0].write('template.ms', format="MSEED")

Advanced example

In this example we will download some data and picks from the New Zealand GeoNet database and make use ofthe functions in EQcorrscan to quickly and simply generate templates for use in matched-filter detection. In theexample we are looking at an earthquake sequence on the east coast of New Zealand’s North Island that occurredon the 4th of January 2016. We will take a set of four template events from the sequence that have been picked byGeoNet, of a range of magnitudes. You can decide if these were good templates or not. You could easily extendthis by choosing more template events (the mainshock in the sequence is a M 5 and you can get the informationby clicking ).

You do not need to use data from an online server, many pick formats can be parsed, either by obspy, or (for seisanpick files) through the Sfile_utils module in EQcorrscan.

This template script is written to be general, so you should be able to give command line arguments to the script togenerate templates from other FDSN databases. Note that some data-centers do not support full FDSN quakemlfiles, and working out which do is quite painful.

"""Simple tutorial detailing how to generate a series of templates from catalog\data available online."""

from obspy.clients.fdsn import Clientfrom obspy import read_eventsfrom obspy.core.event import Catalog

from eqcorrscan.utils.catalog_utils import filter_picksfrom eqcorrscan.core import template_gen

def mktemplates(network_code='GEONET',publicIDs=['2016p008122', '2016p008353', '2016p008155',

'2016p008194'], plot=True):"""Functional wrapper to make templates"""# We want to download some QuakeML files from the New Zealand GeoNet# network, GeoNet currently doesn't support FDSN event queries, so we# have to work around to download quakeml from their quakeml.geonet site.

(continues on next page)



(continued from previous page)

client = Client(network_code)# We want to download a few events from an earthquake sequence, these are# identified by publiID numbers, given as arguments

catalog = Catalog()for publicID in publicIDs:

if network_code == 'GEONET':data_stream = client._download(

'http://quakeml.geonet.org.nz/quakeml/1.2/' + publicID)data_stream.seek(0, 0)catalog += read_events(data_stream, format="quakeml")data_stream.close()

else:catalog += client.get_events(

eventid=publicID, includearrivals=True)

# Lets plot the catalog to see what we haveif plot:

catalog.plot(projection='local', resolution='h')

# We don't need all the picks, lets take the information from the# five most used stations - note that this is done to reduce computational# costs.catalog = filter_picks(catalog, top_n_picks=5)# We only want the P picks in this example, but you can use others or all# picks if you want.for event in catalog:

for pick in event.picks:if pick.phase_hint == 'S':

event.picks.remove(pick)

# Now we can generate the templatestemplates = template_gen.template_gen(

method='from_client', catalog=catalog, client_id=network_code,lowcut=2.0, highcut=9.0, samp_rate=20.0, filt_order=4, length=3.0,prepick=0.15, swin='all', process_len=3600, debug=0, plot=plot)

# We now have a series of templates! Using Obspy's Stream.write() method we# can save these to disk for later use. We will do that now for use in the# following tutorials.for i, template in enumerate(templates):

template.write('tutorial_template_' + str(i) + '.ms', format='MSEED')# Note that this will warn you about data types. As we don't care# at the moment, whatever obspy chooses is fine.

return

if __name__ == '__main__':"""Wrapper for template creation"""import sysimport warningsif not len(sys.argv) > 1:

warnings.warn('Needs a network ID followed by a list of event IDs, ' +'will run the test case instead')

mktemplates()else:

net_code = sys.argv[1]idlist = list(sys.argv)[2:]print(idlist)mktemplates(net_code, idlist)

Try this example for another, Northern California Data Center earthquake:



python template_creation.py NCEDC 72572665

This will (unfortunately for you) generate a warning about un-labelled picks, as many data-centers do not providephase-hints with their picks. We care about which phase is which when we have to run our cross-correlationre-picker (yet to be completed), which means that we, by convention, assign P-picks to the vertical channel andS-picks to both horizontal channels.

This will also show template waveforms for both the automatic and the manual picks - you can change thisby removing either automatic or manual picks y setting the evaluation_mode flag in eqcorrscan.utils.catalog_utils.filter_picks().

Note: To run this script and for all map plotting you will need to install matplotlib-toolkits basemap package.Install instructions and a link to the download are . We recommend that you install the package using your systempackage manager if it is available.

Important considerations

In this tutorial we enforce downloading of day-long data for the template generation. This is to ensure that the datawe make the template from, and the data we use for detection are processed in exactly the same way. If we wereto only download a short segment of data around the event and process this we would find that the resamplingprocess would result in minor differences between the templates and the continuous data. This has the effect that,for self-detections, the cross-correlation values are less than 1.

This is an important effect and something that you should consider when generating your own templates. YouMUST process your templates in the exact same way (using the same routines, same filters, same resampling, andsame data length) as your continuous data. It can have a very significant impact to your results.

The functions provided in template_gen are there to aid you, but if you look at the source code, all they are doingis:

• Detrending;

• Resampling;

• Filtering;

• and cutting.

If you want to do these things another way you are more then welcome to!

Converting from templates to Template and Tribe objects

This section should guide you through generating eqcorrscan.core.match_filter.Template andeqcorrscan.core.match_filter.Tribe objects from the simple templates created above. This shouldprovide you with a means to migrate from older scripts to the more modern, object-oriented workflows in matchedfilter.

To generate a eqcorrscan.core.match_filter.Template from a cut, processed waveform generatedby the template_gen functions you must fill all the attributes of the eqcorrscan.core.match_filter.Template object. You must use the parameters you used when generating the template waveform. Note thatyou do not need to include an event to make a complete eqcorrscan.core.match_filter.Templateobject, but it will be benficial for further location of detected events.

In the following example we take a cut-waveform and convert it to a eqcorrscan.core.match_filter.Template object using the parameters we used to generate the waveform:

>>> from eqcorrscan.core.match_filter import Template>>> template = Template(... name='test_template', st=templates[0], lowcut=2.0, highcut=9.0,... samp_rate=20.0, filt_order=4, prepick=0.15, process_length=200)

You can then make a eqcorrscan.core.match_filter.Tribe from a list of eqcorrscan.core.match_filter.Template objects as follows:



>>> from eqcorrscan.core.match_filter import Tribe>>> tribe = Tribe(templates=[template])

3.4.2 Matched-filter detection

This tutorial will cover using both the match-filter objects, and using the internal functions within match-filter. Thematch-filter objects are designed to simplify meta-data handling allowing for shorter code with fewer mistakes andtherefore more consistent results.

Match-filter objects

The match-filter module contains five objects:

• Tribe

• Template

• Party

• Family

• Detection

The Tribe object is a container for multiple Template objects. Templates contain the waveforms of the templatealongside the metadata used to generate the template. Both Templates and Tribes can be written to disk as tararchives containing the waveform data in miniseed format, event catalogues associated with the Templates (ifprovided) in quakeml format and meta-data in a csv file. This archives can be read back in or transferred betweenmachines.

The Detection, Family and Party objects are heirachical, a single Detection object describes a single event detec-tion, and contains information regarding how the detection was made, what time it was made at alongside otheruseful information, it does not store the Template object used for the detection, but does store a reference to thename of the Template. Family objects are containers for multiple Detections made using a single Template (namechosen to match the literature). These objects do contain the Template used for the detections, and as such can beused to re-create the list of detections is necessary. Party objects are containers for multiple Family objects. Allobjects in the detection heirachy have read and write methods - we recommend writing to tar archives (default) forParty and Family objects, as this will store all metadata used in detection, which should allow for straightforwardreproduction of results.

Template creation

Templates have a construct method which accesses the functions in template_gen. Template.construct only hasaccess to methods that work on individual events, and not catalogs; for that use the Tribe.construct method. Forexample, we can use the from_sac method to make a Template from a series of SAC files associated with a singleevent:

>>> import glob>>> from eqcorrscan.core.match_filter import Template>>> sac_files = glob.glob('eqcorrscan/tests/test_data/SAC/2014p611252/*')>>> # sac_files is now a list of all the SAC files for event id:2014p611252>>> template = Template().construct(... method='from_sac', name='test', lowcut=2.0, highcut=8.0,... samp_rate=20.0, filt_order=4, prepick=0.1, swin='all',... length=2.0, sac_files=sac_files)



Tribe creation

As eluded to above, Template.construct only works for individual events, to make a lot of templates we have to usethe Tribe.construct method. The syntax is similar, but we don’t specify names - templates are named according totheir start-time, but you can rename them later if you wish:

>>> from eqcorrscan.core.match_filter import Tribe>>> from obspy.clients.fdsn import Client

>>> client = Client('NCEDC')>>> catalog = client.get_events(eventid='72572665', includearrivals=True)>>> # To speed the example we have a catalog of one event, but you can have>>> # more, we are also only using the first five picks, again to speed the>>> # example.>>> catalog[0].picks = catalog[0].picks[0:5]>>> tribe = Tribe().construct(... method='from_client', catalog=catalog, client_id='NCEDC', lowcut=2.0,... highcut=8.0, samp_rate=20.0, filt_order=4, length=6.0, prepick=0.1,... swin='all', process_len=3600, all_horiz=True)

Matched-filter detection using a Tribe

Both Tribe and Template objects have detect methods. These methods call the main match_filter function. Theycan be given an un-processed stream and will complete the appropriate processing using the same processingvalues stored in the Template objects. Because Tribe objects can contain Templates with a range of processingvalues, this work is completed in groups for groups of Templates with the same processing values. The Tribeobject also has a client_detect method which will download the appropriate data. Both detect and client_detectmethods return Party objects.

For example, we can use the Tribe we created above to detect through a day of data by running the following:

>>> from obspy import UTCDateTime

>>> party, stream = tribe.client_detect(... client=client, starttime=UTCDateTime(2016, 1, 2),... endtime=UTCDateTime(2016, 1, 3), threshold=8, threshold_type='MAD',... trig_int=6, plotvar=False, return_stream=True)

Generating a Party from a Detection csv

If you are moving from detections written out as a csv file from an older version of EQcorrscan, but want to useParty objects now, then this section is for you!

First, you need to generate a Tribe from the templates you used to make the detections. Instructions for this are inthe Template creation tutorial section.

Once you have a Tribe, you can generate a Party using the following:

>>> detections = read_detections(detection_file)>>> party = Party()>>> for template in tribe:... template_detections = [d for d in detections... if d.template_name == template.name]... family = Family(template=template, detections=template_detections)... party += family



Lag-calc using a Party

Because parties contain Detection and Template information they can be used to generate re-picked cataloguesusing lag-calc:

>>> stream = stream.merge().sort(['station'])>>> repicked_catalog = party.lag_calc(stream, pre_processed=False,... shift_len=0.2, min_cc=0.4)5 Trace(s) in Stream:...

By using the above examples you can go from a standard catalog available from data centers, to a matched-filterdetected and cross-correlation repicked catalog in a handful of lines.

Simple example - match-filter.match-filter

This example does not work out of the box, you will have to have your own templates and data, and set things upfor this. However, in principle matched-filtering can be as simple as:

from eqcorrscan.core import match_filterfrom eqcorrscan.utils import pre_processingfrom obspy import read

# Read in and process the daylong datast = read('continuous_data')# Use the same filtering and sampling parameters as your template!st = pre_processing.dayproc(st, lowcut=2, highcut=10, filt_order=4,

samp_rate=50,starttime=st[0].stats.starttime.date)

# Read in the templatestemplates = []template_names = ['template_1', 'template_2']for template_file in template_names:

templates.append(read(template_file))detections = match_filter.match_filter(

template_names=template_names, template_list=templates, st=st,threshold=8, threshold_type='MAD', trig_int=6, plotvar=False, cores=4)

This will create a list of detections, which are of class detection. You can write out the detections to a csv (colonseparated) using the detection.write method, set append=True to write all the detections to one file. Bewarethough, if this is set and the file already exists, it will just add on to the old file.

for detection in detections:detection.write('my_first_detections.csv', append=True)

Memory limitations and what to do about it

You may (if you are running large numbers of templates, long data durations, or using a machine with smallmemory) run in to errors to do with memory consumption. The most obvious symptom of this is your computerfreezing because it has allocated all of its RAM, or declaring that it cannot allocate memory. Because EQcorrscancomputes correlations in parallel for multiple templates for the same data period, it will generate a large numberof correlation vectors. At start-up, EQcorrscan will try to assign the memory it needs (although it then requires alittle more later to do the summation across channels), so you might find that it fills your memory very early - thisis just to increase efficiency and ensure that the memory is available when needed.

To get around memory limitations you can:

• Reduce the number of templates you run in parallel at once - for example you can make groups of a numberof templates and run that group in parallel, before running the next group in parallel. This is not much lessefficient, unless you have a machine with more CPU cores than your group-size.



• Reduce the length of data you are correlating at any one time. The default is to use day-long files, but thereis nothing stopping you using shorter waveform durations.

• Reduce the number of channels in templates to only those that you need. Note, EQcorrscan will gener-ate vectors of zeros for templates that are missing a channel that is present in other templates, again forprocessing efficiency, if not memory efficiency.

• Reduce your sampling rate. Obviously this needs to be at-least twice as large as your upper frequency filter,but much above this is wasted data.

The three threshold parameters

The match-filter routine has three key threshold parameters:

• threshold_type can either be MAD, abs or av_chan_corr. MAD stands for Median Absolute Deviation andis the most commonly used detection statistic in matched-filter studies. abs is the absolute cross-channelcorrelation sum, note that if you have different numbers of channels in your templates then this thresholdmetric probably isn’t for you. av_chan_corr sets a threshold in the cross-channel correlation sum based onav_chan_corr x number of channels.

• threshold is the value used for the above metric.

• trig_int is the minimum interval in seconds for a detection using the same template. If there are multipledetections within this window for a single template then EQcorrscan will only give the best one (that exceedsthe threshold the most).

Advanced example - match-filter-match-filter

In this section we will outline using the templates generated in the first tutorial to scan for similar earthquakeswithin a day of data. This small example does not truly exploit the parallel operations within this package however,so you would be encouraged to think about where parallel operations occur (hint, the code can run one templateper CPU), and why there are –instance and–splits flags in the other scripts in the github repository (hint, if youhave heaps of memory and CPUs you can do some brute force day parallelisation!).

The main processing flow is outlined in the figure below, note the main speedups in this process are achieved byrunning multiple templates at once, however this increases memory usage. If memory is a problem there are flags(mem_issue) in the match_filter.py source that can be turned on - the codes will then write temporary files, whichis slower, but can allow for more data crunching at once, your trade-off, your call.



"""Simple tutorial to demonstrate some of the basic capabilities of the EQcorrscanmatched-filter detection routine. This builds on the template generationtutorial and uses those templates. If you haven't run that tutorial scriptthen you will need to before you can run this script."""

import glob

from multiprocessing import cpu_countfrom obspy.clients.fdsn import Clientfrom obspy import UTCDateTime, Stream, read

from eqcorrscan.utils import pre_processingfrom eqcorrscan.utils import plottingfrom eqcorrscan.core import match_filter

def run_tutorial(plot=False, process_len=3600):





"""Main function to run the tutorial dataset."""# First we want to load our templatestemplate_names = glob.glob('tutorial_template_*.ms')

if len(template_names) == 0:raise IOError('Template files not found, have you run the template ' +

'creation tutorial?')

templates = [read(template_name) for template_name in template_names]

# Work out what stations we have and get the data for themstations = []for template in templates:

for tr in template:stations.append((tr.stats.station, tr.stats.channel))

# Get a unique list of stationsstations = list(set(stations))

# We will loop through the data chunks at a time, these chunks can be any# size, in general we have used 1 day as our standard, but this can be# as short as five minutes (for MAD thresholds) or shorter for other# threshold metrics. However the chunk size should be the same as your# template process_len.

# You should test different parameters!!!start_time = UTCDateTime(2016, 1, 4)end_time = UTCDateTime(2016, 1, 5)chunks = []chunk_start = start_timewhile chunk_start < end_time:

chunk_end = chunk_start + process_lenif chunk_end > end_time:

chunk_end = end_timechunks.append((chunk_start, chunk_end))chunk_start += process_len

unique_detections = []

# Set up a client to access the GeoNet databaseclient = Client("GEONET")

# Note that these chunks do not rely on each other, and could be paralleled# on multiple nodes of a distributed cluster, see the SLURM tutorial for# an example of this.for t1, t2 in chunks:

# Generate the bulk information to query the GeoNet databasebulk_info = []for station in stations:

bulk_info.append(('NZ', station[0], '*',station[1][0] + 'H' + station[1][-1], t1, t2))

# Note this will take a little while.print('Downloading seismic data, this may take a while')st = client.get_waveforms_bulk(bulk_info)# Merge the stream, it will be downloaded in chunksst.merge(fill_value='interpolate')

# Set how many cores we want to parallel across, we will set this# to four as this is the number of templates, if your machine has# fewer than four cores/CPUs the multiprocessing will wait until there# is a free core.





# Setting this to be higher than the number of templates will have no# increase in speed as only detections for each template are computed# in parallel. It may also slow your processing by using more memory# than needed, to the extent that swap may be filled.if cpu_count() < len(templates):

ncores = cpu_count()else:

ncores = len(templates)

# Pre-process the data to set frequency band and sampling rate# Note that this is, and MUST BE the same as the parameters used for# the template creation.print('Processing the seismic data')st = pre_processing.shortproc(

st, lowcut=2.0, highcut=9.0, filt_order=4, samp_rate=20.0,debug=2, num_cores=ncores, starttime=t1, endtime=t2)

# Convert from list to streamst = Stream(st)

# Now we can conduct the matched-filter detectiondetections = match_filter.match_filter(

template_names=template_names, template_list=templates,st=st, threshold=8.0, threshold_type='MAD', trig_int=6.0,plotvar=plot, plotdir='.', cores=ncores, debug=1,plot_format='png')

# Now lets try and work out how many unique events we have just to# compare with the GeoNet catalog of 20 events on this day in this# sequencefor master in detections:

keep = Truefor slave in detections:

if not master == slave and abs(master.detect_time -slave.detect_time) <= 1.0:

# If the events are within 1s of each other then test which# was the 'best' match, strongest detectionif not master.detect_val > slave.detect_val:

keep = Falseprint('Removed detection at %s with cccsum %s'

% (master.detect_time, master.detect_val))print('Keeping detection at %s with cccsum %s'

% (slave.detect_time, slave.detect_val))break

if keep:unique_detections.append(master)print('Detection at :' + str(master.detect_time) +

' for template ' + master.template_name +' with a cross-correlation sum of: ' +str(master.detect_val))

# We can plot these tooif plot:

stplot = st.copy()template = templates[template_names.index(

master.template_name)]lags = sorted([tr.stats.starttime for tr in template])maxlag = lags[-1] - lags[0]stplot.trim(starttime=master.detect_time - 10,

endtime=master.detect_time + maxlag + 10)plotting.detection_multiplot(

stplot, template, [master.detect_time.datetime])print('We made a total of ' + str(len(unique_detections)) + ' detections')





return unique_detections

if __name__ == '__main__':run_tutorial()

SLURM example

When the authors of EQcorrscan work on large projects, we use grid computers with the SLURM (Simple LinuxUtility for Resource Management) job scheduler installed. To facilitate ease of setup, what follows is an exampleof how we run this.

#!/bin/bash#SBATCH -J MatchTest#SBATCH -A ###########SBATCH --time=12:00:00#SBATCH --mem=7G#SBATCH --nodes=1#SBATCH --output=matchout_%a.txt#SBATCH --error=matcherr_%a.txt#SBATCH --cpus-per-task=16#SBATCH --array=0-49

# Load the required modules here.module load OpenCV/2.4.9-intel-2015amodule load ObsPy/0.10.3rc1-intel-2015a-Python-2.7.9module load joblib/0.8.4-intel-2015a-Python-2.7.9

# Run your python script using srunsrun python2.7 LFEsearch.py --splits 50 --instance $SLURM_ARRAY_TASK_ID

Where we use a script (LFEsearch.py) that accepts splits and instance flags, this section of the script is as follows:

Split=Falseinstance=Falseif len(sys.argv) == 2:

flag=str(sys.argv[1])if flag == '--debug':

Test=TruePrep=False

elif flag == '--debug-prep':Test=FalsePrep=True

else:raise ValueError("I don't recognise the argument, I only know --debug and -

→˓-debug-prep")elif len(sys.argv) == 5:

# Arguments to allow the code to be run in multiple instancesSplit=TrueTest=FalsePrep=Falseargs=sys.argv[1:len(sys.argv)]for i in xrange(len(args)):

if args[i] == '--instance':instance=int(args[i+1])print 'I will run this for instance '+str(instance)

elif args[i] == '--splits':splits=int(args[i+1])print 'I will divide the days into '+str(splits)+' chunks'





elif not len(sys.argv) == 1:raise ValueError("I only take one argument, no arguments, or two flags with

→˓arguments")else:

Test=FalsePrep=FalseSplit=False

The full script is not included in EQcorrscan, but is available on request.

3.4.3 Subspace Detection

EQcorrscan’s subspace detection methods are closely modelled on the method described by , Subspace Detectors:Theory. We offer options to multiplex data or leave as single-channels (multiplexing is significantly faster).

Subspace detection is implemented in an object-oriented style, whereby individual detectors are constructed fromdata, then used to detect within continuous data. At the core of the subspace routine is a Cython-based, static-typed routine to calculate the detection statistics. We do this to make use of numpy’s vectorized calculations,while taking advantage of the speed-ups afforded by compiling the sliding window loop.

WARNING

Subspace in EQcorrscan is in beta, you must check your results match what you expect - if you find errors pleasereport them. Although our test-cases run correctly, changes in data quality may affect the routines in ways wehave not accounted for.

Important

How you generate you detector is likely to be the most important thing, careful selection and alignment is key,and because of this we haven’t provided a total cookie-cutter system for doing this. You have freedom to choseyour parameters, how to process, how you align, what traces to keep, whether you multiplex or not, etc. This alsomeans you have a lot of freedom to get it wrong. You will have to do significant testing with your own dataset towork out what works and what doesn’t. Anything that you find that doesn’t work well in EQcorrscans system, itwould be great to hear about so that we can make it better.

The following examples demonstrate some of the options, but not all of them. The advanced example is theexample used to test and develop subspace and took a fair amount of effort over a number of weeks.

Simple example

To begin with you will need to create a Detector:

>>> from eqcorrscan.core import subspace>>> detector = subspace.Detector()

This will create an empty detector object. These objects have various attributes, including the data to be usedas a detector (detector.data), alongside the full input and output basis vector matrices (detector.u and detector.vrespectively) and the vector of singular-values (detector.sigma). Meta-data are also included, including whetherthe detector is multiplexed or not (detector.multiplex), the filters applied (detector.lowcut, detector.highcut, detec-tion.filt_order, detector.sampling_rate), the dimension of the subspace (detector.dimension), and the name of thedetector, which you can use for book-keeping (detector.name).

To populate the empty detector you need a design set of streams that have been aligned (see clustering submodulefor alignment methods).



>>> from obspy import read>>> import glob>>> wavefiles = glob.glob('eqcorrscan/tests/test_data/similar_events/*')>>> streams = [read(w) for w in wavefiles[0:3]]>>> # Channels must all be the same length>>> for st in streams:... for tr in st:... tr.data = tr.data[int(41.5 * tr.stats.sampling_rate):... int(44 * tr.stats.sampling_rate)]>>> detector.construct(streams=streams, lowcut=2, highcut=9, filt_order=4,... sampling_rate=20, multiplex=True, name='Test_1',... align=True, shift_len=0.5, reject=0.2)Detector: Test_1

This will populate all the attributes of your detector object, and fill the detector.data with the full input basis vectormatrix.

You will want to reduce the dimensions of your subspace detector, such that you are just describing the signal,preferably with a lot of generality. Details for selecting dimensionality should be found in . To do this in EQ-corrscan simply use the partition method:

>>> detector.partition(2)Detector: Test_1

This will populate detector.data with the first four, left-most input basis vectors. You can test to see how much ofyour original design set is described by this detector by using the energy_capture method:

>>> percent_capture = detector.energy_capture()

This will return a percentage capture, you can run this for multiple dimensions to test what dimension best suitsyour application. Again, details for this selection can be found in .

Finally, to use your detector to detect within continuous data you should use the detect method. This requires astream with the same stations and channels used in the detector, and a threshold from 0-1, where 0 is no signal,and 1 is totally described by your detector. You can extract streams for the detections at the same time as thedetections by setting the extract_detections flag to True.

>>> stream = read(wavefiles[0])>>> for tr in stream:... tr.data = tr.data[int(41.5 * tr.stats.sampling_rate):... int(44 * tr.stats.sampling_rate)]>>> detections = detector.detect(st=stream, threshold=0.5, trig_int=3)Detection took ...

Advanced Example

This example computes detections for a short data-period during an earthquake sequence in the Wairarapa regionof New Zealand’s North Island. This example only shows one subspace detector, but could be extended, usingthe various clustering routines in EQcorrscan, to create many subspace detectors. These could be run using thesubspace_detect function, which runs similar detectors in parallel through the given data.

"""Advanced subspace tutorial to show some of the capabilities of the method.

This example uses waveforms from a known earthquake sequence (in the Wairaraparegion north of Wellington, New Zealand). The catalogue locations etc canbe downloaded from this link:

http://quakesearch.geonet.org.nz/services/1.0.0/csv?bbox=175.37956,-40.97912,175.→˓53097,-40.84628&startdate=2015-7-18T2:00:00&enddate=2016-7-18T3:00:00





"""

from obspy.clients.fdsn import Clientfrom obspy import UTCDateTime

from eqcorrscan.utils.catalog_utils import filter_picksfrom eqcorrscan.utils.clustering import space_clusterfrom eqcorrscan.core import subspace

def run_tutorial(plot=False, multiplex=True, return_streams=False):"""Run the tutorial.

:return: detections"""client = Client("GEONET")cat = client.get_events(

minlatitude=-40.98, maxlatitude=-40.85, minlongitude=175.4,maxlongitude=175.5, starttime=UTCDateTime(2016, 5, 1),endtime=UTCDateTime(2016, 5, 20))

print("Downloaded a catalog of %i events" % len(cat))# This gives us a catalog of events - it takes a while to download all# the information, so give it a bit!# We will generate a five station, multi-channel detector.cat = filter_picks(catalog=cat, top_n_picks=5)stachans = list(set(

[(pick.waveform_id.station_code, pick.waveform_id.channel_code)for event in cat for pick in event.picks]))

# In this tutorial we will only work on one cluster, defined spatially.# You can work on multiple clusters, or try to whole set.clusters = space_cluster(catalog=cat, d_thresh=2, show=False)# We will work on the largest clustercluster = sorted(clusters, key=lambda c: len(c))[-1]# This cluster contains 32 events, we will now download and trim the# waveforms. Note that each chanel must start at the same time and be the# same length for multiplexing. If not multiplexing EQcorrscan will# maintain the individual differences in time between channels and delay# the detection statistics by that amount before stacking and detection.client = Client('GEONET')design_set = []bulk_info = []for event in cluster:

t1 = event.origins[0].timet2 = t1 + 25.1 # Have to download extra data, otherwise GeoNet will# trim wherever suits.t1 -= 0.1for station, channel in stachans:

bulk_info.append(('NZ', station, '*', channel[0:2] + '?', t1, t2))print("Downloading data for %i events" % len(cluster))st = client.get_waveforms_bulk(bulk=bulk_info)for event in cluster:

t1 = event.origins[0].timet2 = t1 + 25design_set.append(st.copy().trim(t1, t2))

# Construction of the detector will process the traces, then align them,# before multiplexing.detector = subspace.Detector()detector.construct(

streams=design_set, lowcut=2.0, highcut=9.0, filt_order=4,





sampling_rate=20, multiplex=multiplex, name='Wairarapa1', align=True,reject=0.2, shift_len=6, plot=plot).partition(9)

print("Constructed Detector")if plot:

detector.plot()# We also want the continuous stream to detect in.t1 = UTCDateTime(2016, 5, 11, 19)t2 = UTCDateTime(2016, 5, 11, 20)# We are going to look in a single hour just to minimize cost, but you can# run for much longer.bulk_info = [('NZ', stachan[0], '*',

stachan[1][0] + '?' + stachan[1][-1],t1, t2) for stachan in detector.stachans]

print("Downloading continuous data")st = client.get_waveforms_bulk(bulk_info)st.merge().detrend('simple').trim(starttime=t1, endtime=t2)# We set a very low threshold because the detector is not that great, we# haven't aligned it particularly well - however, at this threshold we make# two real detections.print("Computing detections")detections, det_streams = detector.detect(

st=st, threshold=0.3, trig_int=2, extract_detections=True)if return_streams:

return detections, det_streamselse:

return detections

if __name__ == '__main__':run_tutorial()

3.4.4 Lag-time and pick correction

The following is a work-in-progress tutorial for lag-calc functionality.

An important note

Picks generated by lag-calc are relative to the start of the template waveform, for example, if you generated yourtemplates with a pre_pick of 0.2, you should expect picks to occur 0.2 seconds before the actual phase arrival. Theresult of this is that origin-times will be shifted by the same amount.

If you have applied different pre_picks to different channels when generating template (currently not supportedby any EQcorrscan functions), then picks generated here will not give the correct location.

Advanced Example: Parkfield 2004

"""Tutorial to illustrate the lag_calc usage."""

from obspy.clients.fdsn import Clientfrom obspy.core.event import Catalogfrom obspy import UTCDateTime

from eqcorrscan.core import template_gen, match_filter, lag_calcfrom eqcorrscan.utils import pre_processing, catalog_utils

def run_tutorial(min_magnitude=2, shift_len=0.2, num_cores=4, min_cc=0.5):





"""Functional, tested example script for running the lag-calc tutorial."""client = Client('NCEDC')t1 = UTCDateTime(2004, 9, 28)t2 = t1 + 86400print('Downloading catalog')catalog = client.get_events(

starttime=t1, endtime=t2, minmagnitude=min_magnitude,minlatitude=35.7, maxlatitude=36.1, minlongitude=-120.6,maxlongitude=-120.2, includearrivals=True)

# We don't need all the picks, lets take the information from the# five most used stations - note that this is done to reduce computational# costs.catalog = catalog_utils.filter_picks(catalog, channels=['EHZ'],

top_n_picks=5)# There is a duplicate pick in event 3 in the catalog - this has the effect# of reducing our detections - check it yourself.for pick in catalog[3].picks:

if pick.waveform_id.station_code == 'PHOB' and \pick.onset == 'emergent':

catalog[3].picks.remove(pick)print('Generating templates')templates = template_gen.from_client(

catalog=catalog, client_id='NCEDC', lowcut=2.0, highcut=9.0,samp_rate=50.0, filt_order=4, length=3.0, prepick=0.15,swin='all', process_len=3600)

# In this section we generate a series of chunks of data.start_time = UTCDateTime(2004, 9, 28, 17)end_time = UTCDateTime(2004, 9, 28, 20)process_len = 3600chunks = []chunk_start = start_timewhile chunk_start < end_time:

chunk_end = chunk_start + process_lenif chunk_end > end_time:

chunk_end = end_timechunks.append((chunk_start, chunk_end))chunk_start += process_len

all_detections = []picked_catalog = Catalog()template_names = [str(template[0].stats.starttime)

for template in templates]for t1, t2 in chunks:

print('Downloading and processing for start-time: %s' % t1)# Download and process the databulk_info = [(tr.stats.network, tr.stats.station, '*',

tr.stats.channel, t1, t2) for tr in templates[0]]# Just downloading a chunk of datast = client.get_waveforms_bulk(bulk_info)st.merge(fill_value='interpolate')st = pre_processing.shortproc(

st, lowcut=2.0, highcut=9.0, filt_order=4, samp_rate=50.0,debug=0, num_cores=num_cores)

detections = match_filter.match_filter(template_names=template_names, template_list=templates, st=st,threshold=8.0, threshold_type='MAD', trig_int=6.0, plotvar=False,plotdir='.', cores=num_cores)

# Extract unique detections from set.unique_detections = []for master in detections:

keep = True





for slave in detections:if not master == slave and\

abs(master.detect_time - slave.detect_time) <= 1.0:# If the events are within 1s of each other then test which# was the 'best' match, strongest detectionif not master.detect_val > slave.detect_val:

keep = Falsebreak

if keep:unique_detections.append(master)

all_detections += unique_detections

picked_catalog += lag_calc.lag_calc(detections=unique_detections, detect_data=st,template_names=template_names, templates=templates,shift_len=shift_len, min_cc=min_cc, interpolate=False, plot=False,parallel=True, debug=3)

# Return all of this so that we can use this function for testing.return all_detections, picked_catalog, templates, template_names

if __name__ == '__main__':from multiprocessing import cpu_countrun_tutorial(min_magnitude=4, num_cores=cpu_count())

3.4.5 Magnitude calculation

EQcorrscan contains both an automatic amplitude picker and a singular-value decomposition derived magnitudecalculation, which is very accurate but requires high levels of event similarity.

Amplitude picker for local magnitudes

Currently this is only implemented for seisan s-files, however we have no plans to extend this to other formats(although it would be simple as seisan files are read in as obspy events not).

This example requires data downloaded from the eqcorrscan github repository.

>>> from eqcorrscan.utils.mag_calc import amp_pick_event>>> from obspy import read, read_events>>> from obspy.io.nordic.core import readwavename>>> import os>>> testing_path = 'eqcorrscan/tests/test_data'>>> sfile = os.path.join(testing_path, 'REA', 'TEST_',... '01-0411-15L.S201309')>>> datapath = os.path.join(testing_path, 'WAV', 'TEST_')>>> event = read_events(sfile)[0]>>> st = read(os.path.join(datapath, readwavename(sfile)[0]))>>> respdir = testing_path>>> event = amp_pick_event(... event=event, st=st, respdir=respdir, chans=['Z'],... var_wintype=True, winlen=0.9, pre_pick=0.2, pre_filt=True,... lowcut=1.0, highcut=20.0, corners=4)Working on ...

Relative moment by singular-value decomposition

This method closely follows the method outlined by .

This example requires data downloaded from the eqcorrscan github repository.



>>> from eqcorrscan.utils.mag_calc import svd_moments>>> from obspy import read>>> import glob>>> from eqcorrscan.utils.clustering import svd>>> import numpy as np>>> # Do the set-up>>> testing_path = 'eqcorrscan/tests/test_data/similar_events'>>> stream_files = glob.glob(os.path.join(testing_path, '*'))>>> stream_list = [read(stream_file) for stream_file in stream_files]>>> event_list = []>>> for i, stream in enumerate(stream_list):... st_list = []... for tr in stream:... # Only use the vertical channels of sites with known high similarity.... # You do not need to use this step for your data.... if (tr.stats.station, tr.stats.channel) not in\... [('WHAT2', 'SH1'), ('WV04', 'SHZ'), ('GCSZ', 'EHZ')]:... stream.remove(tr)... continue... tr.detrend('simple')... tr.filter('bandpass', freqmin=5.0, freqmax=15.0)... tr.trim(tr.stats.starttime + 40, tr.stats.endtime - 45)... st_list.append(i)... event_list.append(st_list)<obspy.core.stream.Stream object at ...>>>> event_list = np.asarray(event_list).T.tolist()>>> SVectors, SValues, Uvectors, stachans = svd(stream_list=stream_list)>>> M, events_out = svd_moments(u=Uvectors, s=SValues, v=SVectors,... stachans=stachans, event_list=event_list)Created Kernel matrix: ...

3.4.6 Clustering and stacking

Prior to template generation, it may be beneficial to cluster earthquake waveforms. Clusters of earthquakes withsimilar properties can then be stacked to create higher signal-to-noise templates that describe the dataset well (andrequire fewer templates to reduce computational cost). Clusters could also be reduced to their singular-vectorsand employed in a subspace detection routine (coming soon to eqcorrscan).

The following outlines a few examples of clustering and stacking.

Cluster in space

Download a catalog of global earthquakes and cluster in space, set the distance threshold to 1,000km

>>> from eqcorrscan.utils.clustering import space_cluster>>> from obspy.clients.fdsn import Client>>> from obspy import UTCDateTime

>>> client = Client("IRIS")>>> starttime = UTCDateTime("2002-01-01")>>> endtime = UTCDateTime("2002-02-01")>>> cat = client.get_events(starttime=starttime, endtime=endtime,... minmagnitude=6, catalog="ISC")>>> groups = space_cluster(catalog=cat, d_thresh=1000, show=False)

Download a local catalog of earthquakes and cluster much finer (distance threshold of 2km).

>>> client = Client("NCEDC")>>> cat = client.get_events(starttime=starttime, endtime=endtime,





... minmagnitude=2)>>> groups = space_cluster(catalog=cat, d_thresh=2, show=False)

Setting show to true will plot the dendrogram for grouping with individual groups plotted in different colours. Theclustering is performed using scipy’s . Specifically clustering is performed using the linkage method, which is anagglomorative clustering routine. EQcorrscan uses the average method with the euclidean distance metric.

Cluster in time and space

EQcorrscan’s space-time clustering routine first computes groups in space, using the space_cluster method, thensplits the returned groups based on their inter-event time.

The following example extends the example of the global catalog with a 1,000km distance threshold and a one-daytemporal limit.

>>> from eqcorrscan.utils.clustering import space_time_cluster>>> client = Client("IRIS")>>> cat = client.get_events(starttime=starttime, endtime=endtime,... minmagnitude=6, catalog="ISC")>>> groups = space_time_cluster(catalog=cat, t_thresh=86400, d_thresh=1000)

Cluster according to cross-correlation values

Waveforms from events are often best grouped based on their similarity. EQcorrscan has a method to computeclustering based on average cross-correlations. This again uses scipy’s , however in this case clusters are computedusing the single method. Distances are computed from the average of the multi-chanel cross-correlation values.

The following example uses data stored in the EQcorrscan github repository, in the tests directory.

>>> from obspy import read>>> import glob>>> import os>>> from eqcorrscan.utils.clustering import cluster>>> # You will need to edit this line to the location of your eqcorrscan repo.>>> testing_path = 'eqcorrscan/tests/test_data/similar_events'>>> stream_files = glob.glob(os.path.join(testing_path, '*'))>>> stream_list = [(read(stream_file), i)... for i, stream_file in enumerate(stream_files)]>>> for stream in stream_list:... for tr in stream[0]:... if tr.stats.station not in ['WHAT2', 'WV04', 'GCSZ']:... stream[0].remove(tr)... continue... tr = tr.detrend('simple')... tr = tr.filter('bandpass', freqmin=5.0, freqmax=15.0)... tr = tr.trim(tr.stats.starttime + 40, tr.stats.endtime - 45)<obspy.core.stream.Stream object at ...>>>> groups = cluster(template_list=stream_list, show=False,... corr_thresh=0.3, cores=2)Computing the distance matrix using 2 coresComputing linkageClusteringFound 9 groupsExtracting and grouping



Stack waveforms (linear)

Following from clustering, similar waveforms can be stacked. EQcorrscan includes two stacking algorithms, asimple linear stacking method, and a phase-weighted stacking method.

The following examples use the test data in the eqcorrscan github repository.

>>> from eqcorrscan.utils.stacking import linstack

>>> # groups[0] should contain 3 streams, which we can now stack>>> # Groups are returned as lists of tuples, of the stream and event index>>> group_streams = [st_tuple[0] for st_tuple in groups[0]]>>> stack = linstack(streams=group_streams)

Stack waveforms (phase-weighted)

The phase-weighted stack method closely follows the method outlined by . In this method the linear stack isweighted by the stack of the instantaneous phase. In this manor coherent signals are amplified.

>>> from eqcorrscan.utils.stacking import PWS_stack

>>> # groups[0] should contain 3 streams, which we can now stack>>> # Groups are returned as lists of tuples, of the stream and event index>>> stack = PWS_stack(streams=group_streams)Computing instantaneous phaseComputing the phase stack

3.5 Core

Core routines of the EQcorrscan project. These routines concern the large-scale matched-filter detection of near-repeating earthquakes. For this to take place a series of templates must be generated: these templates can becreated using the functions in template_gen, or you can generate them externally. Templates in EQcorrscanare simply cut waveforms. Because EQcorrscan relies on Obspy, these waveforms can be any type readable byObspy. For simplicity, portability and data compression reasons, EQcorrscan currently stores templates on-disk asmultiplexed miniseed files, where each file is a single template.

3.5.1 Brightness

bright_lights contains a series of functions to detect events using the brightness-based beamforming method ofFrank et. al (2014). This has been tested significantly, but has failed to detect events unambiguously in the centralSouthern Alps. As such development of these functions has ceased.

3.5.2 Template generation

template_gen contains routines for cutting waveforms around picks for use as templates in match_filter. Includedin this are wrappers to directly read in Seisan formattaed pick files and waveforms associated with the picks, andgenerate templates from these. There are also wrappers for quakeML events and catalogs, and seishub databases.

3.5.3 Matched-Filter

match_filter contains the core routines for earthquake detection by cross-correlation. This is optimized for large-scale, multi-paralleled detection, with large numbers of templates. Because we are unsure of your architecture wehave not written functions for the top level of possible parallel computing, which would be to compute detectionsfor multiple days in parallel in a High-Performance Computing, cluster environment. If you want to know more


http://docs.obspy.org/

submodules/core.bright_lights.html


submodules/core.template_gen.html

submodules/core.match_filter.html



about doing this please contact the authors. We use a cluster running SLURM for job scheduling and handlemultiple days using the batch job submission capability which distributes daily detections across multiple nodes.This allows us to detect earthquakes through > 6 years of multi-channel data using > 600 templates in less than 36hours.

Of note: EQcorrscan does not enforce a length of data to process, it is up to the user to exercise caution whenthresholding cross-correlation sums. As the figure below shows, if using the median absolute deviation (MAD)thresholding metric the user should be aware that this changes with time, and those variations can be significantwhen using short windows of data.

Fig. 1: Plot of a few hours of cross-correlation sum (black) for a five channel template associated with the Parkfield2004 earthquake with various windowed thresholds, set to 8 x Median Absolute Deviation. x-axis is time in hours,y-axis is cross-correlation sum.

3.5.4 Lag-Calc

lag_calc contains functions for generating pick-corrections from cross-correlations with a defined template. Origi-nally this was designed for events detected by match_filter, however you can use any well correlated events. Basedon the method of Shelly and Hardebeck (2010).

3.5. Core 39

submodules/core.lag_calc.html


http://onlinelibrary.wiley.com/doi/10.1029/2010GL043672/full


3.5.5 Subspace

subspace contains a subspace detector for either single-channel cases, or network cases. This is modelled on thatdescribed by Harris. This method allows for slightly more variation in detected waveforms than the traditionalmatched-filter method. In this method, templates are constructed either by using the empirical subspace method, orby computing the basis vectors by singular-value decomposition. Both methods are provided as part of EQcorrscanin the clustering module.

3.5.6 API-docs

bright_lights

Code to determine the brightness function of seismic data according to a three-dimensional travel-time grid. Thistravel-time grid can be generated using the grid2time function of the NonLinLoc package by Anthony Lomaxwhich can be found here: NonLinLoc. NonLinLoc is not distributed within this package but it is a very usefulstand-alone library for seismic event location.

This code is based on the method of Frank & Shapiro 2014.

copyright EQcorrscan developers.

license GNU Lesser General Public License, Version 3 (https://www.gnu.org/copyleft/lesser.html)

Classes & Functions

brightness Calculate the brightness function for a single day.coherence Determine the average network coherence of a given

template or detection.

eqcorrscan.core.bright_lights.brightness

eqcorrscan.core.bright_lights.brightness(stations, nodes, lags, stream, thresh-old, thresh_type, template_length,template_saveloc, coherence_thresh,coherence_stations=[’all’], coher-ence_clip=False, gap=2.0, clip_level=100,instance=0, pre_pick=0.2, plotvar=False,plotsave=True, cores=1, debug=0,mem_issue=False)

Calculate the brightness function for a single day.

Written to calculate the brightness function for a single day of data, using moveouts from a 3D travel-timegrid.

Note: Data in stream must be all of the same length and have the same sampling rates, see eqcorrscan.utils.pre_processing.dayproc()

Parameters

• stations (list) – List of station names from in the form where stations[i] refers tonodes[i][:] and lags[i][:]

• nodes (list) – List of node points where nodes[i] refers to stations[i] andnodes[:][:][0] is latitude in degrees, nodes[:][:][1] is longitude in degrees, nodes[:][:][2]is depth in km.


submodules/core.subspace.html

https://e-reports-ext.llnl.gov/pdf/335299.pdf

submodules/utils.clustering.html

http://alomax.free.fr/nlloc/


https://www.gnu.org/copyleft/lesser.html


• lags (numpy.ndarray) – Array of arrays where lags[i][:] refers to stations[i].lags[i][j] should be the delay to the nodes[i][j] for stations[i] in seconds.

• stream (obspy.core.stream.Stream) – Data through which to look for detec-tions.

• threshold (float) – Threshold value for detection of template within the bright-ness function.

• thresh_type (str) – Either MAD or abs where MAD is the Median Absolute De-viation and abs is an absolute brightness.

• template_length (float) – Length of template to extract in seconds

• template_saveloc (str) – Path of where to save the templates.

• coherence_thresh (tuple) – Threshold for removing incoherent peaks in thenetwork response, those below this will not be used as templates. Must be in the formof (a,b) where the coherence is given by: 𝑎 − 𝑘𝑐ℎ𝑎𝑛/𝑏 where kchan is the number ofchannels used to compute the coherence.

• coherence_stations (list) – List of stations to use in the coherence threshold-ing - defaults to all which uses all the stations.

• coherence_clip (tuple) – Start and end in seconds of data to window around,defaults to False, which uses all the data given.

• gap (float) – Minimum inter-event time in seconds for detections.

• clip_level (float) – Multiplier applied to the mean deviation of the energy as anupper limit, used to remove spikes (earthquakes, lightning, electrical spikes) from theenergy stack.

• instance (int) – Optional, used for tracking when using a distributed computingsystem.

• pre_pick (float) – Seconds before the detection time to include in template

• plotvar (bool) – Turn plotting on or off

• plotsave (bool) – Save or show plots, if False will try and show the plots on screen- as this is designed for bulk use this is set to True to save any plots rather than showthem if you create them - changes the backend of matplotlib, so if is set to False youwill see NO PLOTS!

• cores (int) – Number of cores to use, defaults to 1.

• debug (int) – Debug level from 0-5, higher is more output.

• mem_issue (bool) – Set to True to write temporary variables to disk rather than storein memory, slow.

Returns list of templates as obspy.core.stream.Stream objects

Return type list

eqcorrscan.core.bright_lights.coherence

eqcorrscan.core.bright_lights.coherence(stream_in, stations=[’all’], clip=False)Determine the average network coherence of a given template or detection.

You will want your stream to contain only signal as noise will reduce the coherence (assuming it is incoher-ent random noise).

Parameters

• stream_in (obspy.core.stream.Stream) – The stream of seismic data youwant to calculate the coherence for.

3.5. Core 41

https://docs.scipy.org/doc/numpy/reference/generated/numpy.ndarray.html#numpy.ndarray

https://docs.obspy.org/packages/autogen/obspy.core.stream.Stream.html#obspy.core.stream.Stream

https://docs.python.org/2.7/library/functions.html#float

https://docs.python.org/2.7/library/functions.html#str





https://docs.python.org/2.7/library/functions.html#int


https://docs.python.org/2.7/library/functions.html#bool








• stations (list) – List of stations to use for coherence, default is all

• clip (tuple) – Default is to use all the data given (False) - tuple of start and end inseconds from start of trace

Returns tuple of coherence and number of channels used.

Return type tuple

Private Functions

Note that these functions are not designed for public use and may change at any point.

_rms Calculate RMS of array._rm_similarlags Remove nodes that have a very similar network move-

out to another node._resample_grid Resample the lagtime grid to a given volume._read_tt Read in .csv files of slowness generated from

Grid2Time._cum_net_resp Compute the cumulative network response by reading

saved energy .npy files._node_loop Internal function to allow for brightness to be paral-

leled._find_detections Find detections within the cumulative network re-

sponse.

eqcorrscan.core.bright_lights._rms

eqcorrscan.core.bright_lights._rms(array)Calculate RMS of array.

Parameters array (numpy.ndarray) – Array to calculate the RMS for.

Returns RMS of array

Return type float

eqcorrscan.core.bright_lights._rm_similarlags

eqcorrscan.core.bright_lights._rm_similarlags(stations, nodes, lags, threshold)Remove nodes that have a very similar network moveout to another node.

This function will, for each node, calculate the difference in lagtime at each station at every node, then sumthese for each node to get a cumulative difference in network moveout. This will result in an array of arrayswith zeros on the diagonal.

Parameters


• nodes (list) – List of node points where nodes[i] referes to stations[i] andnodes[:][:][0] is latitude in degrees, nodes[:][:][1] is longitude in degrees, nodes[:][:][2]is depth in km.


• threshold (float) – Threshold for removal in seconds

Returns Stations







Return type list

Returns List of lists of tuples of node locations

Return type list

Returns Array of lags.

Return type numpy.ndarray

Note: Output:

station[1] refers to nodes[1] and lags[1] nodes[1][1] refers to station[1] and lags[1][1] nodes[n][n] is a tupleof latitude, longitude and depth.

eqcorrscan.core.bright_lights._resample_grid

eqcorrscan.core.bright_lights._resample_grid(stations, nodes, lags, mindepth,maxdepth, corners)

Resample the lagtime grid to a given volume.

For use if the grid from Grid2Time is too large or you want to run a faster, downsampled scan.

Parameters


• nodes (list) – List of node points where nodes[i] referes to stations[i] andnodes[:][:][0] is latitude in degrees, nodes[:][:][1] is longitude in degrees, nodes[:][:][2]is depth in km.


• mindepth (float) – Upper limit of volume

• maxdepth (float) – Lower limit of volume

• corners (matplotlib.path.Path) – matplotlib Path of the corners for the 2Dpolygon to cut to in lat and lon.

Returns Stations

Return type list


Return type list



Note: Output:


eqcorrscan.core.bright_lights._read_tt

eqcorrscan.core.bright_lights._read_tt(path, stations, phase, phaseout=’S’,ps_ratio=1.68, lags_switch=True)

Read in .csv files of slowness generated from Grid2Time.

3.5. Core 43





https://matplotlib.org/api/path_api.html#matplotlib.path.Path



Converts these data to a useful format here.

It should be noted that this can read either P or S travel-time grids, not both at the moment.

Parameters

• path (str) – The path to the .csv Grid2Time outputs

• stations (list) – List of station names to read slowness files for.

• phase (str) – Input phase type.

• phaseout (str) – What phase to return the lagtimes in.

• ps_ratio (float) – p to s ratio for conversion

• lags_switch (bool) – Return lags or raw travel-times, if set to true will return lags.

Returns Stations

Return type list


Return type list



Note: Output:


Note: This function currently needs comma separated grid files in NonLinLoc format. Only certainversions of NonLinLoc write these csv files, however it should be possible to read the binary files directly.If you find you need this capability let us know and we can try and implement it.

eqcorrscan.core.bright_lights._cum_net_resp

eqcorrscan.core.bright_lights._cum_net_resp(node_lis, instance=0)Compute the cumulative network response by reading saved energy .npy files.

Parameters

• node_lis (numpy.ndarray) – List of nodes (ints) to read from

• instance (int) – Instance flag for parallel workflows, defaults to 0.

Returns cumulative network response


Returns node indices for each sample of the cumulative network response.

Return type list

eqcorrscan.core.bright_lights._node_loop

eqcorrscan.core.bright_lights._node_loop(stations, lags, stream, clip_level, i=0,mem_issue=False, instance=0, plot=False)

Internal function to allow for brightness to be paralleled.

Parameters












• stations (list) – List of stations to use.

• lags (numpy.ndarray) – List of lags where lags[i[:]] are the lags for stations[i].

• stream (obspy.core.stream.Stream) – Data stream to find the brightness for.

• clip_level (float) – Upper limit for energy as a multiplier to the mean energy.

• i (int) – Index of loop for parallelisation.

• mem_issue (bool) – If True will write to disk rather than storing data in RAM.

• instance (int) – instance for bulk parallelisation, only used if mem_issue=true.

• plot (bool) – Turn plotting on or off, defaults to False.

Returns index

Return type int

Returns network response


eqcorrscan.core.bright_lights._find_detections

eqcorrscan.core.bright_lights._find_detections(cum_net_resp, nodes, threshold,thresh_type, samp_rate, realsta-tions, length)

Find detections within the cumulative network response.

Parameters

• cum_net_resp (numpy.ndarray) – Array of cumulative network response fornodes

• nodes (list) – Nodes associated with the source of energy in the cum_net_resp

• threshold (float) – Threshold value

• thresh_type (str) – Either MAD (Median Absolute Deviation) or abs (absolute)or RMS (Root Mean Squared)

• samp_rate (float) – Sampling rate in Hz

• realstations (list) – List of stations used to make the cumulative network re-sponse, will be reported in the eqcorrscan.core.match_filter.Detection

• length (float) – Maximum length of peak to look for in seconds

Returns Detections as eqcorrscan.core.match_filter.Detection objects.

Return type list

lag_calc

Functions to generate pick-corrections for events detected by correlation.



Classes & Functions

3.5. Core 45

















lag_calc Main lag-calculation function for detections of spe-cific events.

eqcorrscan.core.lag_calc.lag_calc

eqcorrscan.core.lag_calc.lag_calc(detections, detect_data, template_names, templates,shift_len=0.2, min_cc=0.4, horizontal_chans=[’E’, ’N’,’1’, ’2’], vertical_chans=[’Z’], cores=1, interpo-late=False, plot=False, parallel=True, debug=0)

Main lag-calculation function for detections of specific events.

Overseer function to take a list of detection objects, cut the data for them to lengths of the same length of thetemplate + shift_len on either side. This will output a obspy.core.event.Catalog of picked events.Pick times are based on the lag-times found at the maximum correlation, providing that correlation is abovethe min_cc.

Parameters

• detections (list) – List of eqcorrscan.core.match_filter.Detection objects.

• detect_data (obspy.core.stream.Stream) – All the data needed to cutfrom - can be a gappy Stream.

• template_names (list) – List of the template names, used to help identify familiesof events. Must be in the same order as templates.

• templates (list) –

List of the templates, templates must be a list of obspy.core.stream.Stream objects.

• shift_len (float) – Shift length allowed for the pick in seconds, will beplus/minus this amount - default=0.2

• min_cc (float) – Minimum cross-correlation value to be considered a pick, de-fault=0.4.

• horizontal_chans (list) – List of channel endings for horizontal-channels, onwhich S-picks will be made.

• vertical_chans (list) – List of channel endings for vertical-channels, on whichP-picks will be made.

• cores (int) – Number of cores to use in parallel processing, defaults to one.

• interpolate (bool) – Interpolate the correlation function to achieve sub-sampleprecision.

• plot (bool) – To generate a plot for every detection or not, defaults to False

• parallel (bool) – Turn parallel processing on or off.

• debug (int) – Debug output level, 0-5 with 5 being the most output.

Returns Catalog of events with picks. No origin information is included. These events can thenbe written out via obspy.core.event.Catalog.write(), or to Nordic Sfiles usingeqcorrscan.utils.sfile_util.eventtosfile() and located externally.

Return type obspy.core.event.Catalog

Note: Picks output in catalog are generated relative to the template start-time. For example, if you gener-ated your template with a pre_pick time of 0.2 seconds, you should expect picks generated by lag_calc to


https://docs.obspy.org/packages/autogen/obspy.core.event.Catalog.html#obspy.core.event.Catalog













occur 0.2 seconds before the true phase-pick. This is because we do not currently store template meta-dataalongside the templates.

Warning: Because of the above note, origin times will be consistently shifted by the static pre_pickapplied to the templates.

Warning: This routine requires only one template per channel (e.g. you should not use templates witha P and S template on a single channel). If this does occur an error will be raised.

Note: S-picks will be made on horizontal channels, and P picks made on vertical channels - the default isthat horizontal channels end in one of: ‘E’, ‘N’, ‘1’ or ‘2’, and that vertical channels end in ‘Z’. The optionsvertical_chans and horizontal_chans can be changed to suit your dataset.

Note: Individual channel cross-correlations are stored as a obspy.core.event.Comment for eachpick, and the summed cross-correlation value resulting from these is stored as a obspy.core.event.Comment in the main obspy.core.event.Event object.

Note: The order of events is preserved (e.g. detections[n] == output[n]), providing picks have been madefor that event. If no picks have been made for an event, it will not be included in the output. However, aseach detection has an ID associated with it, these can be mapped to the output resource_id for each Eventin the output Catalog. e.g.

detections[n].id == output[m].resource_id

if the output[m] is for the same event as detections[n].

Private Functions


_channel_loop Inner loop for correlating and assigning picks._day_loop Function to loop through multiple detections for one

template._prepare_data Prepare data for lag_calc - reduce memory here._xcorr_interp Intrpolate around the maximum correlation value for

sub-sample precision.

eqcorrscan.core.lag_calc._channel_loop

eqcorrscan.core.lag_calc._channel_loop(detection, template, min_cc, detection_id,interpolate, i, pre_lag_ccsum=None, de-tect_chans=0, horizontal_chans=[’E’, ’N’, ’1’,’2’], vertical_chans=[’Z’], debug=0)

Inner loop for correlating and assigning picks.

Utility function to take a stream of data for the detected event and write maximum correlation to absolutetime as picks in an obspy.core.event.Event object. Only outputs picks for picks above min_cc.

3.5. Core 47


Parameters

• detection (obspy.core.stream.Stream) – Stream of data for the slave eventdetected using template.

• template (obspy.core.stream.Stream) – Stream of data as the template forthe detection.

• min_cc (float) – Minimum cross-correlation value to allow a pick to be made.

• detection_id (str) – Detection ID to associate the event with.


• i (int) – Used to track which process has occurred when running in parallel.

• pre_lag_ccsum (float) – Cross-correlation sum before lag-calc, will check thatthe cross-correlation sum is increased by lag-calc (using all channels, ignoring min_cc)

• detect_chans (int) – Number of channels originally used in detections, mustmatch the number used here to allow for cccsum checking.



• debug (int) – Debug output level 0-5.

Returns Event object containing network, station, channel and pick information.

Return type obspy.core.event.Event

eqcorrscan.core.lag_calc._day_loop

eqcorrscan.core.lag_calc._day_loop(detection_streams, template, min_cc, detections, hori-zontal_chans, vertical_chans, interpolate, cores, par-allel, debug=0)

Function to loop through multiple detections for one template.

Designed to run for the same day of data for I/O simplicity, but as you are passing stream objects it couldrun for all the detections ever, as long as you have the RAM!

Parameters

• detection_streams (list) – List of all the detections for this template that youwant to compute the optimum pick for. Individual things in list should be of obspy.core.stream.Stream type.

• template (obspy.core.stream.Stream) – The original template used to de-tect the detections passed

• min_cc (float) – Minimum cross-correlation value to be allowed for a pick.

• detections (list) – List of detections to associate events with an input detection.




• debug (int) – debug output level 0-5.


















Returns Catalog object containing Event objects for each detection created by this template.


eqcorrscan.core.lag_calc._prepare_data

eqcorrscan.core.lag_calc._prepare_data(detect_data, detections, template, delays,shift_len, plot)

Prepare data for lag_calc - reduce memory here.

Parameters

• detect_data (obspy.core.stream.Stream) – Stream to extract detectionstreams from.

• detections (list) – List of eqcorrscan.core.match_filter.Detection to get data for.

• template (tuple) – tuple of (template_name, template)

• delays (list) – Dictionary of delay times in seconds keyed by sta.channel.

• shift_len (float) – Shift length in seconds allowed for picking.

• plot (bool) – Whether to plot the data extracted or not, used for debugging.

Returns List of detect_streams to be worked on

Return type list

eqcorrscan.core.lag_calc._xcorr_interp

eqcorrscan.core.lag_calc._xcorr_interp(ccc, dt)Intrpolate around the maximum correlation value for sub-sample precision.

Parameters

• ccc (numpy.ndarray) – Cross-correlation array

• dt (float) – sample interval

Returns Position of interpolated maximum in seconds from start of ccc

Return type float

match_filter

See notes and warnings on correlations here: correlation_warnings Functions for network matched-filter detectionof seismic data.

Designed to cross-correlate templates generated by template_gen function with data and output the detections.



3.5. Core 49








utils.correlate.html#notes-on-accuracy



Classes

match_filter.Detection

class eqcorrscan.core.match_filter.Detection(template_name, detect_time, no_chans,detect_val, threshold, typeofdet,threshold_type, threshold_input,chans=None, event=None, id=None)

Bases: object

Single detection from detection routines in eqcorrscan. Information required for a full detection based oncross-channel correlation sums.

Parameters

• template_name (str) – The name of the template for which this detection wasmade.

• detect_time (obspy.core.utcdatetime.UTCDateTime) – Time of detec-tion as an obspy UTCDateTime object

• no_chans (int) – The number of channels for which the cross-channel correlationsum was calculated over.

• detect_val (float) – The raw value of the cross-channel correlation sum for thisdetection.

• threshold (float) – The value of the threshold used for this detection, will be theraw threshold value related to the cccsum.

• typeofdet (str) – Type of detection, STA, corr, bright

• threshold_type (str) – Type of threshold used for detection

• threshold_input (float) – Threshold set for detection, relates to threshold ac-cording to the threshold_type.

• chans (list) – List of stations for the detection

• event (obspy.core.event.event.Event) – Obspy Event object for this de-tection, note that this is lost when writing to a Detection objects to csv files usingeqcorrscan.core.match_filter.Detection.write()

• id (str) – Identification for detection (should be unique).

Methods

copy() Returns a copy of the detection.write(fname[, append]) Write detection to csv formatted file.

__init__(template_name, detect_time, no_chans, detect_val, threshold, typeofdet, threshold_type,threshold_input, chans=None, event=None, id=None)

Main class of Detection.

copy()Returns a copy of the detection.

Returns Copy of detection

write(fname, append=True)Write detection to csv formatted file.

Will append if append==True and file exists

Parameters


https://docs.python.org/2.7/library/functions.html#object


https://docs.obspy.org/packages/autogen/obspy.core.utcdatetime.UTCDateTime.html#obspy.core.utcdatetime.UTCDateTime







https://docs.obspy.org/packages/autogen/obspy.core.event.event.Event.html#obspy.core.event.event.Event



• fname (str) – Full path to file to open and write to.

• append (bool) – Set to true to append to an existing file, if True and file doesn’texist, will create new file and warn. If False will overwrite old files.

match_filter.Family

class eqcorrscan.core.match_filter.Family(template, detections=None, catalog=None)Bases: object

Container for Detection objects from a single template.

Parameters

• template (eqcorrscan.core.match_filter.Template) – The templateused to detect the family

• detections (list) – list of Detection objects

• catalog (obspy.core.event.Catalog) – Catalog of detections, with informa-tion for the individual detections.

Methods

append(other) Add another family or detection to the family.copy() Returns a copy of the family.lag_calc(stream, pre_processed[, shift_len,. . . ])

Compute picks based on cross-correlation align-ment.

plot([plot_grouped]) Plot the cumulative number of detections in time.sort() Sort by detection time.write(filename[, format]) Write Family out, select output format.

__init__(template, detections=None, catalog=None)Instantiation of Family object.

append(other)Add another family or detection to the family.

Example

Append a family to a family

>>> family_a = Family(template=Template(name='a'))>>> family_b = Family(template=Template(name='a'))>>> family_a.append(family_b)Family of 0 detections from template a

Append a detection to the family

>>> family_a = Family(template=Template(name='a'))>>> detection = Detection(... template_name='a', detect_time=UTCDateTime(), no_chans=5,... detect_val=2.5, threshold=1.23, typeofdet='corr',... threshold_type='MAD', threshold_input=8.0)>>> family_a.append(detection)Family of 1 detections from template a

copy()Returns a copy of the family.

3.5. Core 51






Returns Copy of family

Example

>>> family = Family(... template=Template(name='a'), detections=[... Detection(template_name='a', detect_time=UTCDateTime(0),... no_chans=8, detect_val=4.2, threshold=1.2,... typeofdet='corr', threshold_type='MAD',... threshold_input=8.0),... Detection(template_name='a', detect_time=UTCDateTime(0) + 10,... no_chans=8, detect_val=4.5, threshold=1.2,... typeofdet='corr', threshold_type='MAD',... threshold_input=8.0)])>>> family == family.copy()True

lag_calc(stream, pre_processed, shift_len=0.2, min_cc=0.4, horizontal_chans=[’E’, ’N’, ’1’,’2’], vertical_chans=[’Z’], cores=1, interpolate=False, plot=False, parallel=True, de-bug=0)

Compute picks based on cross-correlation alignment.

Parameters

• stream (obspy.core.stream.Stream) – All the data needed to cut from - canbe a gappy Stream.

• pre_processed (bool) – Whether the stream has been pre-processed or not tomatch the templates. See note below.




• vertical_chans (list) – List of channel endings for vertical-channels, onwhich P-picks will be made.






Returns Catalog of events with picks. No origin information is included. These eventscan then be written out via obspy.core.event.Catalog.write(), or to NordicSfiles using eqcorrscan.utils.sfile_util.eventtosfile() and locatedexternally.


Note: Note on pre-processing: You can provide a pre-processed stream, which may be beneficial fordetections over large time periods (the stream can have gaps, which reduces memory usage). However,in this case the processing steps are not checked, so you must ensure that all the template in the Partyhave the same sampling rate and filtering as the stream. If pre-processing has not be done then the data













will be processed according to the parameters in the templates, in this case templates will be groupedby processing parameters and run with similarly processed data. In this case, all templates do not haveto have the same processing parameters.

Note: Picks are corrected for the template pre-pick time.

plot(plot_grouped=False)Plot the cumulative number of detections in time.

Example

>>> family = Family(... template=Template(name='a'), detections=[... Detection(template_name='a', detect_time=UTCDateTime(0) + 200,... no_chans=8, detect_val=4.2, threshold=1.2,... typeofdet='corr', threshold_type='MAD',... threshold_input=8.0),... Detection(template_name='a', detect_time=UTCDateTime(0),... no_chans=8, detect_val=4.5, threshold=1.2,... typeofdet='corr', threshold_type='MAD',... threshold_input=8.0),... Detection(template_name='a', detect_time=UTCDateTime(0) + 10,... no_chans=8, detect_val=4.5, threshold=1.2,... typeofdet='corr', threshold_type='MAD',... threshold_input=8.0)])>>> family.plot(plot_grouped=True)

1970/01/01 00:00:00

1970/01/01 00:02:00

Date

0.0

0.5

1.0

1.5

2.0

2.5

3.0

Cum

ula

tive d

ete

ctio

ns

All templates

sort()Sort by detection time.

3.5. Core 53


Example

>>> family = Family(... template=Template(name='a'), detections=[... Detection(template_name='a', detect_time=UTCDateTime(0) + 200,... no_chans=8, detect_val=4.2, threshold=1.2,... typeofdet='corr', threshold_type='MAD',... threshold_input=8.0),... Detection(template_name='a', detect_time=UTCDateTime(0),... no_chans=8, detect_val=4.5, threshold=1.2,... typeofdet='corr', threshold_type='MAD',... threshold_input=8.0),... Detection(template_name='a', detect_time=UTCDateTime(0) + 10,... no_chans=8, detect_val=4.5, threshold=1.2,... typeofdet='corr', threshold_type='MAD',... threshold_input=8.0)])>>> family[0].detect_timeUTCDateTime(1970, 1, 1, 0, 3, 20)>>> family.sort()[0].detect_timeUTCDateTime(1970, 1, 1, 0, 0)

write(filename, format=’tar’)Write Family out, select output format.

Parameters

• format (str) – One of either ‘tar’, ‘csv’, or any obspy supported catalog output.

• filename (str) – Path to write file to.

Note: csv format will write out detection objects, all other outputs will write the catalog. Thesecannot be rebuilt into a Family object. The only format that can be read back into Family objects isthe ‘tar’ type.

Note: csv format will append detections to filename, all others will overwrite any existing files.

Example

>>> family = Family(... template=Template(name='a', st=read()), detections=[... Detection(template_name='a', detect_time=UTCDateTime(0) + 200,... no_chans=8, detect_val=4.2, threshold=1.2,... typeofdet='corr', threshold_type='MAD',... threshold_input=8.0),... Detection(template_name='a', detect_time=UTCDateTime(0),... no_chans=8, detect_val=4.5, threshold=1.2,... typeofdet='corr', threshold_type='MAD',... threshold_input=8.0),... Detection(template_name='a', detect_time=UTCDateTime(0) + 10,... no_chans=8, detect_val=4.5, threshold=1.2,... typeofdet='corr', threshold_type='MAD',... threshold_input=8.0)])>>> family.write('test_family')





match_filter.Party

class eqcorrscan.core.match_filter.Party(families=None)Bases: object

Container for multiple Family objects.

Methods

copy() Returns a copy of the Party.filter([dates, min_dets]) Return a new Party filtered according to condi-

tions.plot([plot_grouped, dates, min_dets, rate]) Plot the cumulative detections in time.decluster(trig_int[, timing, metric]) De-cluster a Party of detections by enforcing a de-

tection separation.get_catalog() Get an obspy catalog object from the party.lag_calc(stream, pre_processed[, shift_len,. . . ])

Compute picks based on cross-correlation align-ment.

min_chans(min_chans) Remove detections with fewer channels used thanmin_chans

read([filename]) Read a Party from a file.rethreshold(new_threshold[,new_threshold_type])

Remove detections from the Party that are below anew threshold.

sort() Sort the families by template name.write(filename[, format, debug]) Write Family out, select output format.

__init__(families=None)Instantiate the Party object.

copy()Returns a copy of the Party.

Returns Copy of party

Example

>>> party = Party(families=[Family(template=Template(name='a'))])>>> party_b = party.copy()>>> party == party_bTrue

filter(dates=None, min_dets=1)Return a new Party filtered according to conditions.

Return a new Party with only detections within a date range and only families with a minimum numberof detections.

Parameters

• dates (list of obspy.core.UTCDateTime objects) – A start and enddate for the new Party

• min_dets (int) – Minimum number of detections per family

3.5. Core 55




Example

>>> from obspy import UTCDateTime>>> Party().read().filter(dates=[UTCDateTime(2016, 1, 1),... UTCDateTime(2017, 1, 1)],... min_dets=30)

plot(plot_grouped=False, dates=None, min_dets=1, rate=False, **kwargs)Plot the cumulative detections in time.

Parameters

• plot_grouped (bool) – Whether to plot all families together(plot_grouped=True), or each as a separate line.

• dates (list) – list of obspy.core.UTCDateTime objects bounding the plot. Thefirst should be the start date, the last the end date.

• min_dets (int) – Plot only families with this number of detections or more.

• rate (bool) – Whether or not to plot the daily rate of detection as opposed to cu-mulative number. Only works with plot_grouped=True.

• **kwargs – Any other arguments accepted by eqcorrscan.utils.plotting.cumulative_detections()

Examples

Plot cumulative detections for all templates individually:

>>> Party().read().plot()

Plot cumulative detections for all templates grouped together:

>>> Party().read().plot(plot_grouped=True)

Plot the rate of detection for all templates grouped together:

>>> Party().read().plot(plot_grouped=True, rate=True)

Plot cumulative detections for all templates with more than five detections between June 1st, 2012 andJuly 31st, 2012:

>>> from obspy import UTCDateTime>>> Party().read().plot(dates=[UTCDateTime(2012, 6, 1),... UTCDateTime(2012, 7, 31)],... min_dets=5)

decluster(trig_int, timing=’detect’, metric=’avg_cor’)De-cluster a Party of detections by enforcing a detection separation.

De-clustering occurs between events detected by different (or the same) templates. If multiple detec-tions occur within trig_int then the preferred detection will be determined by the metric argument.This can be either the average single-station correlation coefficient which is calculated as Detec-tion.detect_val / Detection.no_chans, or the raw cross channel correlation sum which is simply Detec-tion.detect_val.

Parameters

• trig_int (float) – Minimum detection separation in seconds.







• metric (str) – What metric to sort peaks by. Either ‘avg_cor’ which takes thesingle station average correlation or ‘cor_sum’ which takes the total correlation sumacross all channels.

• timing (str) – Either ‘detect’ or ‘origin’ to decluster based on either the detectiontime or the origin time.

Warning: Works in place on object, if you need to keep the original safe then run this on a copyof the object!

Example

>>> party = Party().read()>>> len(party)4>>> declustered = party.decluster(20)>>> len(party)3

get_catalog()Get an obspy catalog object from the party.

Returns obspy.core.event.Catalog

Example

>>> party = Party().read()>>> cat = party.get_catalog()>>> print(len(cat))4

lag_calc(stream, pre_processed, shift_len=0.2, min_cc=0.4, horizontal_chans=[’E’, ’N’, ’1’,’2’], vertical_chans=[’Z’], cores=1, interpolate=False, plot=False, parallel=True,overlap=’calculate’, debug=0)

Compute picks based on cross-correlation alignment.

Parameters

• stream (obspy.core.stream.Stream) – All the data needed to cut from - canbe a gappy Stream.

• pre_processed (bool) – Whether the stream has been pre-processed or not tomatch the templates. See note below.




• vertical_chans (list) – List of channel endings for vertical-channels, onwhich P-picks will be made.



3.5. Core 57













• overlap (float) – Either None, “calculate” or a float of number of seconds tooverlap detection streams by. This is to counter the effects of the delay-and-stack incalcualting cross-correlation sums. Setting overlap = “calculate” will work out theappropriate overlap based on the maximum lags within templates.


Returns Catalog of events with picks. No origin information is included. These eventscan then be written out via obspy.core.event.Catalog.write(), or to NordicSfiles using eqcorrscan.utils.sfile_util.eventtosfile() and locatedexternally.


Note: Note on pre-processing: You can provide a pre-processed stream, which may be beneficial fordetections over large time periods (the stream can have gaps, which reduces memory usage). However,in this case the processing steps are not checked, so you must ensure that all the template in the Partyhave the same sampling rate and filtering as the stream. If pre-processing has not be done then the datawill be processed according to the parameters in the templates, in this case templates will be groupedby processing parameters and run with similarly processed data. In this case, all templates do not haveto have the same processing parameters.

Note: Picks are corrected for the template pre-pick time.

min_chans(min_chans)Remove detections with fewer channels used than min_chans

Parameters min_chans (int) – Minimum number of channels to allow a detection.

Returns Party

Note: Works in place on Party.

Example

>>> party = Party().read()>>> print(len(party))4>>> party = party.min_chans(5)>>> print(len(party))1

read(filename=None)Read a Party from a file.

Parameters filename (str) – File to read from

Example

>>> Party().read()Party of 4 Families.










rethreshold(new_threshold, new_threshold_type=’MAD’)Remove detections from the Party that are below a new threshold.

Note: threshold can only be set higher.

Warning: Works in place on Party.

Parameters

• new_threshold (float) – New threshold level

• new_threshold_type (str) – Either ‘MAD’, ‘absolute’ or ‘av_chan_corr’

Examples

Using the MAD threshold on detections made using the MAD threshold:

>>> party = Party().read()>>> len(party)4>>> party = party.rethreshold(10.0)>>> len(party)4>>> # Note that all detections are self detections

Using the absolute thresholding method on the same Party:

>>> party = Party().read().rethreshold(6.0, 'absolute')>>> len(party)1

Using the av_chan_corr method on the same Party:

>>> party = Party().read().rethreshold(0.9, 'av_chan_corr')>>> len(party)4

sort()Sort the families by template name.

Example

>>> party = Party(families=[Family(template=Template(name='b')),... Family(template=Template(name='a'))])>>> party[0]Family of 0 detections from template b>>> party.sort()[0]Family of 0 detections from template a

write(filename, format=’tar’, debug=0)Write Family out, select output format.

Parameters

• format (str) – One of either ‘tar’, ‘csv’, or any obspy supported catalog output.See note below on formats

• filename (str) – Path to write file to.

3.5. Core 59






• debug (int) – Whether to output progress or not.

Note: csv format will write out detection objects, all other outputs will write the catalog. Thesecannot be rebuilt into a Family object. The only format that can be read back into Family objects isthe ‘tar’ type.

Note: We recommend writing to the ‘tar’ format, which will write out all the template information(wavefiles as miniseed and metadata) alongside the detections and store these in a tar archive. This isreadable by other programs and maintains all information required for further study.

Example

>>> party = Party().read()>>> party.write('test_tar_write', format='tar', debug=1)Writing family 0Writing family 1Writing family 2Writing family 3Party of 4 Families.>>> party.write('test_csv_write.csv', format='csv')Party of 4 Families.>>> party.write('test_quakeml.xml', format='quakeml')Party of 4 Families.

match_filter.Template

See notes and warnings on correlations here: correlation_warnings

class eqcorrscan.core.match_filter.Template(name=None, st=None, lowcut=None,highcut=None, samp_rate=None,filt_order=None, process_length=None,prepick=None, event=None)

Bases: object

Template object holder.

Contains waveform data and metadata parameters used to generate the template.

Methods

construct(method, name, lowcut, highcut, . . . ) Construct a template using a given method.copy() Returns a copy of the template.detect(stream, threshold, threshold_type, . . . ) Detect using a single template within a continuous

stream.read(filename) Read template from tar format with metadata.same_processing(other) Check is the templates are processed the same.write(filename[, format]) Write template.

__init__(name=None, st=None, lowcut=None, highcut=None, samp_rate=None,filt_order=None, process_length=None, prepick=None, event=None)

Initialize self. See help(type(self)) for accurate signature.

construct(method, name, lowcut, highcut, samp_rate, filt_order, prepick, **kwargs)






Construct a template using a given method.

Parameters

• method (str) – Method to make the template, see eqcorrscan.core.template_gen for possible methods.

• name (str) – Name for the template

• lowcut (float) – Low cut (Hz), if set to None will not apply a lowcut

• highcut (float) – High cut (Hz), if set to None will not apply a highcut.

• samp_rate (float) – New sampling rate in Hz.

• filt_order (int) – Filter level (number of corners).

• prepick (float) – Pre-pick time in seconds

Note: methods from_meta_file, from_seishub, from_client and multi_template_gen are not accommo-dated in this function and must be called from Tribe.construct as these generate multiple templates.

Note: Calls functions from eqcorrscan.core.template_gen, see these functions for details on whatfurther arguments are required.

Example

>>> sac_files = glob.glob(... 'eqcorrscan/tests/test_data/SAC/2014p611252/*')>>> template = Template().construct(... method='from_sac', name='test', lowcut=2.0, highcut=8.0,... samp_rate=20.0, filt_order=4, prepick=0.1, swin='all',... length=2.0, sac_files=sac_files)>>> print(template)Template test:12 channels;lowcut: 2.0 Hz;highcut: 8.0 Hz;sampling rate 20.0 Hz;filter order: 4;process length: 300.0 s

This will raise an error if the method is unsupported:

>>> template = Template().construct(... method='from_meta_file', name='test', lowcut=2.0, highcut=8.0,... samp_rate=20.0, filt_order=4, prepick=0.1, swin='all',... length=2.0)Traceback (most recent call last):NotImplementedError: Method is not supported, use Tribe.construct→˓instead.

copy()Returns a copy of the template.

Returns Copy of template

3.5. Core 61









Example

>>> template_a = Template(... name='a', st=read(), lowcut=2.0, highcut=8.0, samp_rate=100,... filt_order=4, process_length=3600, prepick=0.5)>>> template_b = template_a.copy()>>> template_a == template_bTrue

detect(stream, threshold, threshold_type, trig_int, plotvar, pre_processed=False, day-long=False, parallel_process=True, xcorr_func=None, concurrency=None, cores=None,ignore_length=False, overlap=’calculate’, debug=0, full_peaks=False)

Detect using a single template within a continuous stream.

Parameters

• stream (obspy.core.stream.Stream) – Continuous data to detect within using theTemplate.

• threshold (float) – Threshold level, if using threshold_type=’MAD’ then thiswill be the multiple of the median absolute deviation.

• threshold_type (str) – The type of threshold to be used, can be MAD, absoluteor av_chan_corr. See Note on thresholding below.

• trig_int (float) – Minimum gap between detections in seconds. If multiple de-tections occur within trig_int of one-another, the one with the highest cross-correlationsum will be selected.

• plotvar (bool) – Turn plotting on or off, see warning about plotting below

• pre_processed (bool) – Set to True if stream has already undergone processing,in this case eqcorrscan will only check that the sampling rate is correct. Defaults toFalse, which will use the eqcorrscan.utils.pre_processing routines toresample and filter the continuous data.

• daylong (bool) – Set to True to use the eqcorrscan.utils.pre_processing.dayproc() routine, which preforms additional checksand is more efficient for day-long data over other methods.

• parallel_process (bool) –

• xcorr_func (str or callable) – A str of a registered xcorr function ora callable for implementing a custom xcorr function. For more details seeeqcorrscan.utils.correlate.register_array_xcorr().

• concurrency (str) – The type of concurrency to apply to the xcorr func-tion. Options are ‘multithread’, ‘multiprocess’, ‘concurrent’. For more details seeeqcorrscan.utils.correlate.get_stream_xcorr().

• cores (int) – Number of workers for processing and detection.

• ignore_length (bool) – If using daylong=True, then dayproc will try check thatthe data are there for at least 80% of the day, if you don’t want this check (which willraise an error if too much data are missing) then set ignore_length=True. This is notrecommended!

• overlap (float) – Either None, “calculate” or a float of number of seconds tooverlap detection streams by. This is to counter the effects of the delay-and-stack incalcualting cross-correlation sums. Setting overlap = “calculate” will work out theappropriate overlap based on the maximum lags within templates.

• debug (int) – Debug level from 0-5 where five is more output, for debug levels 4and 5, detections will not be computed in parallel.

• full_peaks – See eqcorrscan.utils.findpeaks.find_peaks2_short
















Returns Family of detections.

Warning: Plotting within the match-filter routine uses the Agg backend with interactive plottingturned off. This is because the function is designed to work in bulk. If you wish to turn interactiveplotting on you must import matplotlib in your script first, when you then import match_filter youwill get the warning that this call to matplotlib has no effect, which will mean that match_filter hasnot changed the plotting behaviour.

Note: Data overlap:

Internally this routine shifts and trims the data according to the offsets in the template (e.g. if trace 2starts 2 seconds after trace 1 in the template then the continuous data will be shifted by 2 seconds toalign peak correlations prior to summing). Because of this, detections at the start and end of continuousdata streams may be missed. The maximum time-period that might be missing detections is themaximum offset in the template.

To work around this, if you are conducting matched-filter detections through long-duration continu-ous data, we suggest using some overlap (a few seconds, on the order of the maximum offset in thetemplates) in the continous data. You will then need to post-process the detections (which should bedone anyway to remove duplicates).

Note: Thresholding:

MAD threshold is calculated as the:

𝑡ℎ𝑟𝑒𝑠ℎ𝑜𝑙𝑑×(𝑚𝑒𝑑𝑖𝑎𝑛(𝑎𝑏𝑠(𝑐𝑐𝑐𝑠𝑢𝑚)))

where 𝑐𝑐𝑐𝑠𝑢𝑚 is the cross-correlation sum for a given template.

absolute threshold is a true absolute threshold based on the cccsum value.

av_chan_corr is based on the mean values of single-channel cross-correlations assuming all data arepresent as required for the template, e.g:

𝑎𝑣_𝑐ℎ𝑎𝑛_𝑐𝑜𝑟𝑟_𝑡ℎ𝑟𝑒𝑠ℎ = 𝑡ℎ𝑟𝑒𝑠ℎ𝑜𝑙𝑑× (𝑐𝑐𝑐𝑠𝑢𝑚/𝑙𝑒𝑛(𝑡𝑒𝑚𝑝𝑙𝑎𝑡𝑒))

where 𝑡𝑒𝑚𝑝𝑙𝑎𝑡𝑒 is a single template from the input and the length is the number of channels withinthis template.

Note: See tutorials for example.

read(filename)Read template from tar format with metadata.

Parameters filename (str) – Filename to read template from.

Example

>>> template_a = Template(... name='a', st=read(), lowcut=2.0, highcut=8.0, samp_rate=100,... filt_order=4, process_length=3600, prepick=0.5)>>> template_a.write(... 'test_template_read')Template a:


3.5. Core 63




3 channels;lowcut: 2.0 Hz;highcut: 8.0 Hz;sampling rate 100 Hz;filter order: 4;process length: 3600 s

>>> template_b = Template().read('test_template_read.tgz')>>> template_a == template_bTrue

same_processing(other)Check is the templates are processed the same.

Example

>>> template_a = Template(... name='a', st=read(), lowcut=2.0, highcut=8.0, samp_rate=100,... filt_order=4, process_length=3600, prepick=0.5)>>> template_b = template_a.copy()>>> template_a.same_processing(template_b)True>>> template_b.lowcut = 5.0>>> template_a.same_processing(template_b)False

write(filename, format=’tar’)Write template.

Parameters

• filename (str) – Filename to write to, if it already exists it will be opened andappended to, otherwise it will be created.

• format (str) – Format to write to, either ‘tar’ (to retain metadata), or any obspysupported waveform format to just extract the waveform.

Example

>>> template_a = Template(... name='a', st=read(), lowcut=2.0, highcut=8.0, samp_rate=100,... filt_order=4, process_length=3600, prepick=0.5)>>> template_a.write('test_template')Template a:3 channels;lowcut: 2.0 Hz;highcut: 8.0 Hz;sampling rate 100 Hz;filter order: 4;process length: 3600 s

>>> template_a.write('test_waveform.ms',... format='MSEED')Template a:3 channels;lowcut: 2.0 Hz;highcut: 8.0 Hz;sampling rate 100 Hz;filter order: 4;process length: 3600 s





match_filter.Tribe

See notes and warnings on correlations here: correlation_warnings

class eqcorrscan.core.match_filter.Tribe(templates=None)Bases: object

Holder for multiple templates.

Methods

client_detect(client, starttime, endtime, . . . ) Detect using a Tribe of templates within a contin-uous stream.

cluster(method, **kwargs) Cluster the tribe.construct(method, lowcut, highcut, . . . [, . . . ]) Generate a Tribe of Templates.copy() Copy the Tribe.detect(stream, threshold, threshold_type, . . . ) Detect using a Tribe of templates within a contin-

uous stream.read(filename) Read a tribe of templates from a tar formatted file.remove(template) Remove a template from the tribe.sort() Sort the tribe, sorts by template name.write(filename[, compress]) Write the tribe to a file using tar archive format-

ting.

__init__(templates=None)Initialize self. See help(type(self)) for accurate signature.

client_detect(client, starttime, endtime, threshold, threshold_type, trig_int, plotvar,min_gap=None, daylong=False, parallel_process=True, xcorr_func=None,concurrency=None, cores=None, ignore_length=False, group_size=None, de-bug=0, return_stream=False, full_peaks=False, save_progress=False)

Detect using a Tribe of templates within a continuous stream.

Parameters

• client (obspy.clients.*.Client) – Any obspy client with a dataselect service.

• starttime (obspy.core.UTCDateTime) – Start-time for detections.

• endtime (obspy.core.UTCDateTime) – End-time for detections





• min_gap (float) – Minimum gap allowed in data - use to remove traces withknown issues



3.5. Core 65











• xcorr_func (str or callable) – A str of a registered xcorr function ora callable for implementing a custom xcorr function. For more information see:eqcorrscan.utils.correlate.register_array_xcorr()

• concurrency (str) – The type of concurrency to apply to the xcorr func-tion. Options are ‘multithread’, ‘multiprocess’, ‘concurrent’. For more details seeeqcorrscan.utils.correlate.get_stream_xcorr()

• cores (int) – Number of workers for processing and detection.


• group_size (int) – Maximum number of templates to run at once, use to reducememory consumption, if unset will use all templates.

• full_peaks (bool) – See eqcorrscan.utils.findpeaks.find_peaks2_short

• save_progress (bool) – Whether to save the resulting party at every data step ornot. Useful for long-running processes.


• return_stream (bool) – Whether to also output the stream downloaded, usefulif you plan to use the stream for something else, e.g. lag_calc.

Returns eqcorrscan.core.match_filter.Party of Families of detections.

Warning: Picks included in the output Party.get_catalog() will not be corrected for pre-picks inthe template.

Note: Ensures that data overlap between loops, which will lead to no missed detections at data start-stop points (see note for eqcorrscan.core.match_filter.Tribe.detect() method).This will result in end-time not being strictly honoured, so detections may occur after the end-timeset. This is because data must be run in the correct process-length.


Note: Thresholding:



















cluster(method, **kwargs)Cluster the tribe.

Cluster templates within a tribe: returns multiple tribes each of which could be stacked.

Parameters method (str) – Method of stacking, see eqcorrscan.utils.clustering

Returns List of tribes.

Example

construct(method, lowcut, highcut, samp_rate, filt_order, prepick, save_progress=False,**kwargs)

Generate a Tribe of Templates.

See eqcorrscan.core.template_gen for available methods.

Parameters

• method – Method of Tribe generation.

• kwargs – Arguments for the given method.

• lowcut (float) – Low cut (Hz), if set to None will not apply a lowcut






Note: Methods: from_contbase, from_sfile and from_sac are not supported by Tribe.construct andmust use Template.construct.

Note: The Method multi_template_gen is not supported because the processing parameters for thestream are not known. Use from_meta_file instead.

Note: Templates will be named according to their start-time.

copy()Copy the Tribe.

Example

>>> tribe_a = Tribe(templates=[Template(name='a')])>>> tribe_b = tribe_a.copy()>>> tribe_a == tribe_bTrue

3.5. Core 67









detect(stream, threshold, threshold_type, trig_int, plotvar, daylong=False, paral-lel_process=True, xcorr_func=None, concurrency=None, cores=None, ig-nore_length=False, group_size=None, overlap=’calculate’, debug=0, full_peaks=False,save_progress=False)

Detect using a Tribe of templates within a continuous stream.

Parameters

• stream (obspy.core.stream.Stream) – Continuous data to detect within using theTemplate.









• cores (int) – Number of workers for procesisng and detection.



• overlap (float) – Either None, “calculate” or a float of number of seconds tooverlap detection streams by. This is to counter the effects of the delay-and-stack incalculating cross-correlation sums. Setting overlap = “calculate” will work out theappropriate overlap based on the maximum lags within templates.


• full_peaks (bool) – See eqcorrscan.utils.findpeak.find_peaks2_short


Returns eqcorrscan.core.match_filter.Party of Families of detections.

Note: stream must not be pre-processed.


















Warning: Picks included in the output Party.get_catalog() will not be corrected for pre-picks inthe template.


Note: Data overlap:

Internally this routine shifts and trims the data according to the offsets in the template (e.g. if trace 2starts 2 seconds after trace 1 in the template then the continuous data will be shifted by 2 seconds toalign peak correlations prior to summing). Because of this, detections at the start and end of continuousdata streams may be missed. The maximum time-period that might be missing detections is themaximum offset in the template.

To work around this, if you are conducting matched-filter detections through long-duration continu-ous data, we suggest using some overlap (a few seconds, on the order of the maximum offset in thetemplates) in the continuous data. You will then need to post-process the detections (which should bedone anyway to remove duplicates). See below note for how overlap argument affects data internallyif stream is longer than the processing length.

Note: If stream is long then processing length, this routine will ensure that data overlap betweenloops, which will lead to no missed detections at data start-stop points (see above note). This willresult in end-time not being strictly honoured, so detections may occur after the end-time set. This isbecause data must be run in the correct process-length.

Note: Thresholding:








read(filename)Read a tribe of templates from a tar formatted file.

Parameters filename (str) – File to read templates from.

3.5. Core 69



Example

>>> tribe = Tribe(templates=[Template(name='c', st=read())])>>> tribe.write('test_tribe')Tribe of 1 templates>>> tribe_back = Tribe().read('test_tribe.tgz')>>> tribe_back == tribeTrue

remove(template)Remove a template from the tribe.

Parameters template (eqcorrscan.core.match_filter.Template) – Tem-plate to remove from tribe

Example

>>> tribe = Tribe(templates=[Template(name='c'), Template(name='b'),... Template(name='a')])>>> tribe.remove(tribe.templates[0])Tribe of 2 templates

sort()Sort the tribe, sorts by template name.

Example

>>> tribe = Tribe(templates=[Template(name='c'), Template(name='b'),... Template(name='a')])>>> tribe.sort()Tribe of 3 templates>>> tribe[0]Template a:0 channels;lowcut: None Hz;highcut: None Hz;sampling rate None Hz;filter order: None;process length: None s

write(filename, compress=True)Write the tribe to a file using tar archive formatting.

Parameters

• filename (str) – Filename to write to, if it exists it will be appended to.

• compress (bool) – Whether to compress the tar archive or not, if False then willjust be files in a folder.

Example

>>> tribe = Tribe(templates=[Template(name='c', st=read())])>>> tribe.write('test_tribe')Tribe of 1 templates





Functions

extract_from_stream Extract waveforms for a list of detections from astream.

get_catalog Generate an obspy.core.event.Catalogfrom list of Detection’s.

match_filter Main matched-filter detection function.normxcorr2 Thin wrapper to eqcorrscan.utils.correlate functions.read_detections Read detections from a file to a list of Detection ob-

jects.read_tribe Read a Tribe of templates from a tar archive.read_party Read detections and metadata from a tar archive.read_template Read a Template object from a tar archive.write_catalog Write events contained within detections to a catalog

file.

eqcorrscan.core.match_filter.extract_from_stream

eqcorrscan.core.match_filter.extract_from_stream(stream, detections, pad=5.0,length=30.0)

Extract waveforms for a list of detections from a stream.

Parameters

• stream (obspy.core.stream.Stream) – Stream containing the detections.

• detections (list) – list of eqcorrscan.core.match_filter.detection

• pad (float) – Pre-detection extract time in seconds.

• length (float) – Total extracted length in seconds.

Returns list of obspy.core.stream.Stream, one for each detection.

Type list

eqcorrscan.core.match_filter.get_catalog

eqcorrscan.core.match_filter.get_catalog(detections)Generate an obspy.core.event.Catalog from list of Detection’s.

Parameters detections (list) – list of eqcorrscan.core.match_filter.Detection

Returns Catalog of detected events.


Warning: Will only work if the detections have an event associated with them. This will not bethe case if detections have been written to csv format using eqcorrscan.core.match_filter.Detection.write() and read back in.

3.5. Core 71









eqcorrscan.core.match_filter.match_filter

eqcorrscan.core.match_filter.match_filter(template_names, template_list, st, thresh-old, threshold_type, trig_int, plotvar,plotdir=’.’, xcorr_func=None, concur-rency=None, cores=None, debug=0,plot_format=’png’, output_cat=False, out-put_event=True, extract_detections=False,arg_check=True, full_peaks=False)

Main matched-filter detection function.

Over-arching code to run the correlations of given templates with a day of seismic data and output thedetections based on a given threshold. For a functional example see the tutorials.

Parameters

• template_names (list) – List of template names in the same order as template_list

• template_list (list) – A list of templates of which each template is a obspy.core.stream.Stream of obspy traces containing seismic data and header informa-tion.

• st (obspy.core.stream.Stream) – A Stream object containing all the dataavailable and required for the correlations with templates given. For efficiency thisshould contain no excess traces which are not in one or more of the templates. This willnow remove excess traces internally, but will copy the stream and work on the copy,leaving your input stream untouched.

• threshold (float) – A threshold value set based on the threshold_type


• trig_int (float) – Minimum gap between detections in seconds.

• plotvar (bool) – Turn plotting on or off

• plotdir (str) – Path to plotting folder, plots will be output here, defaults to runlocation.



• cores (int) – Number of cores to use

• debug (int) – Debug output level, the bigger the number, the more the output.

• plot_format (str) – Specify format of output plots if saved

• output_cat (bool) – Specifies if matched_filter will output an obspy.Catalog classcontaining events for each detection. Default is False, in which case matched_filter willoutput a list of detection classes, as normal.

• output_event (bool) – Whether to include events in the Detection objects, defaultsto True, but for large cases you may want to turn this off as Event objects can be quitememory intensive.

• extract_detections (bool) – Specifies whether or not to return a list of streams,one stream per detection.

• arg_check (bool) – Check arguments, defaults to True, but if running in bulk, andyou are certain of your arguments, then set to False.




















• full_peaks (bool) – See eqcorrscan.core.findpeaks.find_peaks2_short.

Note: Returns:

If neither output_cat or extract_detections are set to True, then only the list of eqcorrscan.core.match_filter.Detection’s will be output:

return eqcorrscan.core.match_filter.Detection detections for each detectionmade.

rtype list

If output_cat is set to True, then the obspy.core.event.Catalog will also be output:

return Catalog containing events for each detection, see above.

rtype obspy.core.event.Catalog

If extract_detections is set to True then the list of obspy.core.stream.Stream’s will also be output.

return list of obspy.core.stream.Stream’s for each detection, see above.

rtype list

Warning: Plotting within the match-filter routine uses the Agg backend with interactive plotting turnedoff. This is because the function is designed to work in bulk. If you wish to turn interactive plottingon you must import matplotlib in your script first, when you them import match_filter you will get thewarning that this call to matplotlib has no effect, which will mean that match_filter has not changed theplotting behaviour.

Note: Data overlap:

Internally this routine shifts and trims the data according to the offsets in the template (e.g. if trace 2 starts2 seconds after trace 1 in the template then the continuous data will be shifted by 2 seconds to align peakcorrelations prior to summing). Because of this, detections at the start and end of continuous data streamsmay be missed. The maximum time-period that might be missing detections is the maximum offset in thetemplate.

To work around this, if you are conducting matched-filter detections through long-duration continuous data,we suggest using some overlap (a few seconds, on the order of the maximum offset in the templates) in thecontinous data. You will then need to post-process the detections (which should be done anyway to removeduplicates).

Note: Thresholding:





av_chan_corr is based on the mean values of single-channel cross-correlations assuming all data are presentas required for the template, e.g:

𝑎𝑣_𝑐ℎ𝑎𝑛_𝑐𝑜𝑟𝑟_𝑡ℎ𝑟𝑒𝑠ℎ = 𝑡ℎ𝑟𝑒𝑠ℎ𝑜𝑙𝑑× (𝑐𝑐𝑐𝑠𝑢𝑚 / 𝑙𝑒𝑛(𝑡𝑒𝑚𝑝𝑙𝑎𝑡𝑒))

where 𝑡𝑒𝑚𝑝𝑙𝑎𝑡𝑒 is a single template from the input and the length is the number of channels within thistemplate.

3.5. Core 73







Note: The output_cat flag will create an obspy.core.event.Catalog containing one event foreach eqcorrscan.core.match_filter.Detection’s generated by match_filter. Each event willcontain a number of comments dealing with correlation values and channels used for the detection. Eachchannel used for the detection will have a corresponding obspy.core.event.Pick which will containtime and waveform information. HOWEVER, the user should note that, at present, the pick times do notaccount for the prepick times inherent in each template. For example, if a template trace starts 0.1 secondsbefore the actual arrival of that phase, then the pick time generated by match_filter for that phase will be 0.1seconds early.

Note: xcorr_func can be used as follows:

>>> import obspy>>> import numpy as np>>> from eqcorrscan.core.match_filter import match_filter>>> from eqcorrscan.utils.correlate import time_multi_normxcorr>>> # define a custom xcorr function>>> def custom_normxcorr(templates, stream, pads, *args, **kwargs):... # Just to keep example short call other xcorr function... # in practice you would define your own function here... print('calling custom xcorr function')... return time_multi_normxcorr(templates, stream, pads)>>> # generate some toy templates and stream>>> random = np.random.RandomState(42)>>> template = obspy.read()>>> stream = obspy.read()>>> for num, tr in enumerate(stream): # iter st and embed templates... data = tr.data... tr.data = random.randn(6000) * 5... tr.data[100: 100 + len(data)] = data>>> # call match_filter ane ensure the custom function is used>>> detections = match_filter(... template_names=['1'], template_list=[template], st=stream,... threshold=.5, threshold_type='absolute', trig_int=1,... plotvar=False,... xcorr_func=custom_normxcorr)calling custom xcorr function...

eqcorrscan.core.match_filter.normxcorr2

eqcorrscan.core.match_filter.normxcorr2(template, image)Thin wrapper to eqcorrscan.utils.correlate functions.

Parameters

• template (numpy.ndarray) – Template array

• image (numpy.ndarray) – Image to scan the template through. The order of thesematters, if you put the template after the image you will get a reversed correlation matrix

Returns New numpy.ndarray of the correlation values for the correlation of the image withthe template.









eqcorrscan.core.match_filter.read_detections

eqcorrscan.core.match_filter.read_detections(fname)Read detections from a file to a list of Detection objects.

Parameters fname (str) – File to read from, must be a file written to by Detection.write.

Returns list of eqcorrscan.core.match_filter.Detection

Return type list

Note: eqcorrscan.core.match_filter.Detection’s returned do not contain Detection.event

eqcorrscan.core.match_filter.read_tribe

eqcorrscan.core.match_filter.read_tribe(fname)Read a Tribe of templates from a tar archive.

Parameters fname – Filename to read from

Returns eqcorrscan.core.match_filter.Tribe

eqcorrscan.core.match_filter.read_party

eqcorrscan.core.match_filter.read_party(fname=None)Read detections and metadata from a tar archive.

Parameters fname (str) – Filename to read from, if this contains a single Family, then willreturn a party of length = 1

Returns eqcorrscan.core.match_filter.Party

eqcorrscan.core.match_filter.read_template

eqcorrscan.core.match_filter.read_template(fname)Read a Template object from a tar archive.

Parameters fname (str) – Filename to read from

Returns eqcorrscan.core.match_filter.Template

eqcorrscan.core.match_filter.write_catalog

eqcorrscan.core.match_filter.write_catalog(detections, fname, format=’QUAKEML’)Write events contained within detections to a catalog file.

Parameters

• detections (list) – list of eqcorrscan.core.match_filter.Detection

• fname (str) – Name of the file to write to

• format (str) – File format to use, see obspy.core.event.Catalog.write for supportedformats.

Private Functions

3.5. Core 75







_group_process Process data into chunks based on template process-ing length.

_group_detect Pre-process and compute detections for a group oftemplates.

_write_family Write a family to a csv file._read_family Internal function to read csv family files._total_microsec Calculate difference between two datetime stamps in

microseconds._test_event_similarity Check the similarity of the components of obspy

events, discounting resource IDs, which are not main-tained in nordic files.

eqcorrscan.core.match_filter._group_process

eqcorrscan.core.match_filter._group_process(template_group, parallel, debug, cores,stream, daylong, ignore_length, over-lap)

Process data into chunks based on template processing length.

Templates in template_group must all have the same processing parameters.

Parameters

• template_group (list) – List of Templates.

• parallel (bool) – Whether to use parallel processing or not

• debug (int) – Debug level from 0-5

• cores (int) – Number of cores to use, can be False to use all available.

• stream (obspy.core.stream.Stream) – Stream to process, will be left intact.

• daylong (bool) – Whether to enforce day-length files or not.


• overlap (float) – Number of seconds to overlap chunks by.

Returns list of processed streams.

eqcorrscan.core.match_filter._group_detect

eqcorrscan.core.match_filter._group_detect(templates, stream, threshold,threshold_type, trig_int, plotvar,group_size=None, pre_processed=False,daylong=False, parallel_process=True,xcorr_func=None, concurrency=None,cores=None, ignore_length=False,overlap=’calculate’, debug=0,full_peaks=False)

Pre-process and compute detections for a group of templates.

Will process the stream object, so if running in a loop, you will want to copy the stream before passing it tothis function.

Parameters

• templates (list) – List of eqcorrscan.core.match_filter.Template










• stream (obspy.core.stream.Stream) – Continuous data to detect within using the Tem-plate.

• threshold (float) – Threshold level, if using threshold_type=’MAD’ then this willbe the multiple of the median absolute deviation.



• plotvar (bool) – Turn plotting on or off, see warning about plotting below.


• pre_processed (bool) – Set to True if stream has already undergone processing, inthis case eqcorrscan will only check that the sampling rate is correct. Defaults to False,which will use the eqcorrscan.utils.pre_processing routines to resampleand filter the continuous data.



• xcorr_func (str or callable) – A str of a registered xcorr function ora callable for implementing a custom xcorr function. For more details see:eqcorrscan.utils.correlate.register_array_xcorr()


• cores (int) – Number of workers for processing and correlation.


• overlap (float) – Either None, “calculate” or a float of number of seconds to over-lap detection streams by. This is to counter the effects of the delay-and-stack in calculat-ing cross-correlation sums. Setting overlap = “calculate” will work out the appropriateoverlap based on the maximum lags within templates.

• debug (int) – Debug level from 0-5 where five is more output, for debug levels 4 and5, detections will not be computed in parallel.

• full_peaks (bool) – See eqcorrscan.utils.findpeaks.find_peaks2_short

Returns eqcorrscan.core.match_filter.Party of families of detections.

eqcorrscan.core.match_filter._write_family

eqcorrscan.core.match_filter._write_family(family, filename)Write a family to a csv file.

Parameters

• family (eqcorrscan.core.match_filter.Family) – Family to write tofile

• filename (str) – File to write to.

3.5. Core 77


















eqcorrscan.core.match_filter._read_family

eqcorrscan.core.match_filter._read_family(fname, all_cat)Internal function to read csv family files.

Parameters fname (str) – Filename

Returns list of Detection

eqcorrscan.core.match_filter._total_microsec

eqcorrscan.core.match_filter._total_microsec(t1, t2)Calculate difference between two datetime stamps in microseconds.

Returns int

Example

>>> print(_total_microsec(UTCDateTime(2013, 1, 1).datetime,... UTCDateTime(2014, 1, 1).datetime))-31536000000000

eqcorrscan.core.match_filter._test_event_similarity

eqcorrscan.core.match_filter._test_event_similarity(event_1, event_2, ver-bose=False)

Check the similarity of the components of obspy events, discounting resource IDs, which are not maintainedin nordic files.

Parameters

• event_1 (obspy.core.event.Event) – First event

• event_2 (obspy.core.event.Event) – Comparison event

• verbose (bool) – If true and fails will output why it fails.

Returns bool

subspace

This module contains functions relevant to executing subspace detection for earthquake catalogs.

We recommend that you read Harris’ detailed report on subspace detection theory which can be found here:https://e-reports-ext.llnl.gov/pdf/335299.pdf






https://e-reports-ext.llnl.gov/pdf/335299.pdf



Classes

eqcorrscan.core.subspace.Detector

class eqcorrscan.core.subspace.Detector(name=None, sampling_rate=None, multi-plex=None, stachans=None, lowcut=None,highcut=None, filt_order=None, data=None,u=None, sigma=None, v=None, dimen-sion=None)

Bases: object

Class to serve as the base for subspace detections.

Parameters

• name (str) – Name of subspace detector, used for book-keeping

• sampling_rate (float) – Sampling rate in Hz of original waveforms

• multiplex (bool) – Is this detector multiplexed.

• stachans (list) – List of tuples of (station, channel) used in detector. If multi-plexed, these must be in the order that multiplexing was done.

• lowcut (float) – Lowcut filter in Hz

• highcut (float) – Highcut filter in Hz

• filt_order (int) – Number of corners for filtering

• data (numpy.ndarray) – The actual detector

• u (numpy.ndarray) – Full rank U matrix of left (input) singular vectors.

• sigma (numpy.ndarray) – Full rank vector of singular values.

• v (numpy.ndarray) – Full rank right (output) singular vectors.

• dimension (int) – Dimension of data.

Warning: Changing between scipy.linalg.svd solvers (obvious changes between scipy version 0.18.xand 0.19.0) result in sign changes in svd results. You should only run a detector created using the samescipy version as you currently run.

Methods

construct(streams, lowcut, highcut, . . . [, . . . ]) Construct a subspace detector from a list ofstreams, full rank.

detect(st, threshold, trig_int[, moveout, . . . ]) Detect within continuous data using the subspacemethod.

energy_capture([stachans, size, show]) Calculate the average percentage energy capturefor this subspace.

partition(dimension) Partition subspace into desired dimension.plot([stachans, size, show]) Plot the output basis vectors for the detector at the

given dimension.read(filename) Read detector from a file, must be HDF5 format.write(filename) Write detector to a file - uses HDF5 file format.

3.5. Core 79














__init__(name=None, sampling_rate=None, multiplex=None, stachans=None, lowcut=None,highcut=None, filt_order=None, data=None, u=None, sigma=None, v=None, dimen-sion=None)

Initialize self. See help(type(self)) for accurate signature.

construct(streams, lowcut, highcut, filt_order, sampling_rate, multiplex, name, align,shift_len=0, reject=0.3, no_missed=True, plot=False)

Construct a subspace detector from a list of streams, full rank.

Subspace detector will be full-rank, further functions can be used to select the desired dimensions.

Parameters

• streams (list) – List of obspy.core.stream.Stream to be used to gener-ate the subspace detector. These should be pre-clustered and aligned.

• lowcut (float) – Lowcut in Hz, can be None to not apply filter

• highcut (float) – Highcut in Hz, can be None to not apply filter

• filt_order (int) – Number of corners for filter.

• sampling_rate (float) – Desired sampling rate in Hz

• multiplex (bool) – Whether to multiplex the data or not. Data are multiplexedaccording to the method of Harris, see the multi function for details.

• name (str) – Name of the detector, used for book-keeping.

• align (bool) – Whether to align the data or not - needs to be done at some point

• shift_len (float) – Maximum shift allowed for alignment in seconds.

• reject (float) – Minimum correlation to include traces - only used if align=True.

• no_missed (bool) – Reject streams with missed traces, defaults to True. A missingtrace from lots of events will reduce the quality of the subspace detector if multiplexed.Only used when multi is set to True.

• plot (bool) – Whether to plot the alignment stage or not.

Note: The detector will be normalized such that the data, before computing the singular-value de-composition, will have unit energy. e.g. We divide the amplitudes of the data by the L1 norm of thedata.

Warning: EQcorrscan’s alignment will attempt to align over the whole data window given. Forlong (more than 2s) chunks of data this can give poor results and you might be better off usingthe eqcorrscan.utils.stacking.align_traces() function externally, focusing on asmaller window of data. To do this you would align the data prior to running construct.

detect(st, threshold, trig_int, moveout=0, min_trig=0, process=True, extract_detections=False,debug=0)

Detect within continuous data using the subspace method.

Parameters

• st (obspy.core.stream.Stream) – Un-processed stream to detect within us-ing the subspace detector.

• threshold (float) – Threshold value for detections between 0-1

• trig_int (float) – Minimum trigger interval in seconds.

• moveout (float) – Maximum allowable moveout window for non-multiplexed,network detection. See note.



















• min_trig (int) – Minimum number of stations exceeding threshold for non-multiplexed, network detection. See note.

• process (bool) – Whether or not to process the stream according to the parametersdefined by the detector. Default is True, which will process the data.

• extract_detections (bool) – Whether to extract waveforms for each detectionor not, if True will return detections and streams.

• debug (int) – Debug output level from 0-5.

Returns list of eqcorrscan.core.match_filter.Detection

Return type list

Warning: Subspace is currently in beta, see note in the subspace tutorial for information.

Note: If running in bulk with detectors that all have the same parameters then you can pre-processthe data and set process to False. This will speed up this detect function dramatically.

Warning: If the detector and stream are multiplexed then they must contain the same channelsand multiplexed in the same order. This is handled internally when process=True, but if running inbulk you must take care.

Note: Non-multiplexed, network detection. When the detector is not multiplexed, but there aremultiple channels within the detector, we do not stack the single-channel detection statistics becausewe do not have a one-size-fits-all solution for computing delays for a subspace detector (if you want toimplement one, then please contribute it!). Therefore, these parameters provide a means for declaringa network coincidence trigger using single-channel detection statistics, in a similar fashion to thecommonly used network-coincidence trigger with energy detection statistics.

energy_capture(stachans=’all’, size=(10, 7), show=False)Calculate the average percentage energy capture for this subspace.

Returns Percentage energy capture

Return type float

partition(dimension)Partition subspace into desired dimension.

Parameters dimension (int) – Maximum dimension to use.

plot(stachans=’all’, size=(10, 7), show=True)Plot the output basis vectors for the detector at the given dimension.

Corresponds to the first n horizontal vectors of the V matrix.

Parameters

• stachans (list) – list of tuples of station, channel pairs to plot.

• stachans – List of tuples of (station, channel) to use. Can set to ‘all’ to use all thestation-channel pairs available. If detector is multiplexed, will just plot that.

• size (tuple) – Figure size.

• show (bool) – Whether or not to show the figure.

Returns Figure

3.5. Core 81









Return type matplotlib.pyplot.Figure

Note: See eqcorrscan.utils.plotting.subspace_detector_plot() for example.

read(filename)Read detector from a file, must be HDF5 format.

Reads a Detector object from an HDF5 file, usually created by eqcorrscan.

Parameters filename (str) – Filename to save the detector to.

write(filename)Write detector to a file - uses HDF5 file format.

Meta-data are stored alongside numpy data arrays. See h5py.org for details of the methods.


Functions

read_detector Read detector from a filename.multi Internal multiplexer for multiplex_detect.subspace_detect Conduct subspace detection with chosen detectors.

eqcorrscan.core.subspace.read_detector

eqcorrscan.core.subspace.read_detector(filename)Read detector from a filename.


Returns Detector object

Return type eqcorrscan.core.subspace.Detector

eqcorrscan.core.subspace.multi

eqcorrscan.core.subspace.multi(stream)Internal multiplexer for multiplex_detect.

Parameters stream (obspy.core.stream.Stream) – Stream to multiplex

Returns trace of multiplexed data

Return type obspy.core.trace.Trace

Maps a standard multiplexed stream of seismic data to a single traces of multiplexed data as follows:

Input: x = [x1, x2, x3, . . . ] y = [y1, y2, y3, . . . ] z = [z1, z2, z3, . . . ]

Output: xyz = [x1, y1, z1, x2, y2, z2, x3, y3, z3, . . . ]

eqcorrscan.core.subspace.subspace_detect

eqcorrscan.core.subspace.subspace_detect(detectors, stream, threshold, trig_int,moveout=0, min_trig=1, parallel=True,num_cores=None)

Conduct subspace detection with chosen detectors.

Parameters






https://docs.obspy.org/packages/autogen/obspy.core.trace.Trace.html#obspy.core.trace.Trace


• detectors (list) – list of eqcorrscan.core.subspace.Detector to beused for detection.

• stream (obspy.core.stream.Stream) – Stream to detect within.

• threshold (float) – Threshold between 0 and 1 for detection, see Detector.detect()

• trig_int (float) – Minimum trigger interval in seconds.

• moveout (float) – Maximum allowable moveout window for non-multiplexed, net-work detection. See note.

• min_trig (int) – Minimum number of stations exceeding threshold for non-multiplexed, network detection. See note in Detector.detect().

• parallel (bool) – Whether to run detectors in parallel in groups.

• num_cores (int) – How many cpu cores to use if parallel==True. If set to None(default), will use all available cores.

Return type list

Returns List of eqcorrscan.core.match_filter.Detection detections.

Note: This will loop through your detectors using their detect method. If the detectors are multiplexed itwill run groups of detectors with the same channels at the same time.

template_gen

Functions to generate template waveforms and information to go with them for the application of cross-correlationof seismic data for the detection of repeating events.

Note: By convention templates are generated with P-phases on the vertical channel and S-phases on the horizontalchannels, normal seismograph naming conventions are assumed, where Z denotes vertical and N, E, R, T, 1 and 2denote horizontal channels, either oriented or not. To this end we will only use Z channels if they have a P-pick,and will use one or other horizontal channels only if there is an S-pick on it.

Warning: If there is no phase_hint included in picks, and swin=all, all channels with picks will be used.

Note: If swin=all, then all picks will be used, not just phase-picks (e.g. it will use amplitude picks). If you donot want this then we suggest that you remove any picks you do not want to use in your templates before usingthe event.

Note: All functions use obspy filters, which are implemented such that if both highcut and lowcut are set abandpass filter will be used, but of highcut is not set (None) then a highpass filter will be used and if only thehighcut is set then a lowpass filter will be used.



3.5. Core 83










Classes & Functions

template_gen Generate processed and cut waveforms for use as tem-plates.

extract_from_stack Extract a multiplexed template from a stack of detec-tions.

from_client Generate multiplexed template from FDSN client.from_meta_file Generate a multiplexed template from a local file.from_sac Generate a multiplexed template from a list of SAC

files.from_seishub Generate multiplexed template from SeisHub

database.multi_template_gen Generate multiple templates from one stream of data.

eqcorrscan.core.template_gen.template_gen

eqcorrscan.core.template_gen.template_gen(method, lowcut, highcut, samp_rate,filt_order, length, prepick, swin, pro-cess_len=86400, all_horiz=False, de-layed=True, plot=False, debug=0,return_event=False, min_snr=None,parallel=False, num_cores=False,save_progress=False, **kwargs)

Generate processed and cut waveforms for use as templates.

Parameters

• method (str) – Template generation method, must be one of (‘from_client’,‘from_seishub’, ‘from_sac’, ‘from_meta_file’). - Each method requires associated ar-guments, see note below.

• lowcut (float) – Low cut (Hz), if set to None will not apply a lowcut.




• length (float) – Extract length in seconds.


• swin (str) – P, S, P_all, S_all or all, defaults to all: see note in eqcorrscan.core.template_gen.template_gen()

• process_len (int) – Length of data in seconds to download and process.

• all_horiz (bool) – To use both horizontal channels even if there is only a pick onone of them. Defaults to False.

• delayed (bool) – If True, each channel will begin relative to it’s own pick-time, ifset to False, each channel will begin at the same time.

• plot (bool) – Plot templates or not.

• debug (int) – Level of debugging output, higher=more

• return_event (bool) – Whether to return the event and process length or not.

• min_snr (float) – Minimum signal-to-noise ratio for a channel to be included inthe template, where signal-to-noise ratio is calculated as the ratio of the maximum am-plitude in the template window to the rms amplitude in the whole window given.

• parallel (bool) – Whether to process data in parallel or not.



















• num_cores (int) – Number of cores to try and use, if False and parallel=True, willuse either all your cores, or as many traces as in the data (whichever is smaller).


Returns List of obspy.core.stream.Stream Templates

Return type list

Note: Method specific arguments:

• from_client requires:

param str client_id string passable by obspy to generate Client

param obspy.core.event.Catalog catalog Catalog of events to generate template for

param float data_pad Pad length for data-downloads in seconds

• from_seishub requires:

param str url url to seishub database

param obspy.core.event.Catalog catalog Catalog of events to generate template for

param float data_pad Pad length for data-downloads in seconds

• from_sac requires:

param list sac_files osbpy.core.stream.Stream of sac waveforms, or list of paths to sacwaveforms.

• from_meta_file requires:

param str meta_file Path to obspy-readable event file.

param obspy.core.stream.Stream st Stream containing waveform data for template.Note that this should be the same length of stream as you will use for the continu-ous detection, e.g. if you detect in day-long files, give this a day-long file!

param bool process Whether to process the data or not, defaults to True.

Note: process_len should be set to the same length as used when computing detections usingmatch_filter.match_filter, e.g. if you read in day-long data for match_filter, process_len should be 86400.

Example

>>> from obspy.clients.fdsn import Client>>> from eqcorrscan.core.template_gen import template_gen>>> client = Client('NCEDC')>>> catalog = client.get_events(eventid='72572665', includearrivals=True)>>> # We are only taking two picks for this example to speed up the>>> # example, note that you don't have to!>>> catalog[0].picks = catalog[0].picks[0:2]>>> templates = template_gen(... method='from_client', catalog=catalog, client_id='NCEDC',... lowcut=2.0, highcut=9.0, samp_rate=20.0, filt_order=4, length=3.0,... prepick=0.15, swin='all', process_len=300, all_horiz=True)>>> templates[0].plot(equal_scale=False, size=(800,600))

3.5. Core 85





Example

>>> from obspy import read>>> from eqcorrscan.core.template_gen import template_gen>>> st = read('eqcorrscan/tests/test_data/WAV/TEST_/' +... '2013-09-01-0410-35.DFDPC_024_00')>>> quakeml = 'eqcorrscan/tests/test_data/20130901T041115.xml'>>> templates = template_gen(... method='from_meta_file', meta_file=quakeml, st=st, lowcut=2.0,... highcut=9.0, samp_rate=20.0, filt_order=3, length=2, prepick=0.1,... swin='S', all_horiz=True)>>> print(len(templates[0]))10>>> templates = template_gen(... method='from_meta_file', meta_file=quakeml, st=st, lowcut=2.0,... highcut=9.0, samp_rate=20.0, filt_order=3, length=2, prepick=0.1,... swin='S_all', all_horiz=True)>>> print(len(templates[0]))15

Example

>>> from eqcorrscan.core.template_gen import template_gen>>> import glob>>> # Get all the SAC-files associated with one event.>>> sac_files = glob.glob('eqcorrscan/tests/test_data/SAC/2014p611252/*')>>> templates = template_gen(





... method='from_sac', sac_files=sac_files, lowcut=2.0, highcut=10.0,

... samp_rate=25.0, filt_order=4, length=2.0, swin='all', prepick=0.1,

... all_horiz=True)>>> print(templates[0][0].stats.sampling_rate)25.0>>> print(len(templates[0]))15

eqcorrscan.core.template_gen.extract_from_stack

eqcorrscan.core.template_gen.extract_from_stack(stack, template, length, pre_pick,pre_pad, Z_include=False,pre_processed=True,samp_rate=None, lowcut=None,highcut=None, filt_order=3)

Extract a multiplexed template from a stack of detections.

Function to extract a new template from a stack of previous detections. Requires the stack, the templateused to make the detections for the stack, and we need to know if the stack has been pre-processed.

Parameters

• stack (obspy.core.stream.Stream) – Waveform stack from detections. Canbe of any length and can have delays already included, or not.

• template (obspy.core.stream.Stream) – Template used to make the detec-tions in the stack. Will use the delays of this for the new template.

• length (float) – Length of new template in seconds

• pre_pick (float) – Extract additional data before the detection, seconds

• pre_pad (float) – Pad used in seconds when extracting the data, e.g. the time beforethe detection extracted. If using clustering.extract_detections this half the length of theextracted waveform.

• Z_include (bool) – If True will include any Z-channels even if there is no templatefor this channel, as long as there is a template for this station at a different channel. Ifthis is False and Z channels are included in the template Z channels will be included inthe new_template anyway.

• pre_processed (bool) – Have the data been pre-processed, if True (default) thenwe will only cut the data here.

• samp_rate (float) – If pre_processed=False then this is required, desired samplingrate in Hz, defaults to False.

• lowcut (float) – If pre_processed=False then this is required, lowcut in Hz, defaultsto False.

• highcut (float) – If pre_processed=False then this is required, highcut in Hz, de-faults to False

• filt_order (int) – If pre_processed=False then this is required, filter order, de-faults to False

Returns Newly cut template.

Return type obspy.core.stream.Stream

3.5. Core 87














eqcorrscan.core.template_gen.from_client

eqcorrscan.core.template_gen.from_client(catalog, client_id, lowcut, highcut,samp_rate, filt_order, length, prepick,swin, process_len=86400, data_pad=90,all_horiz=False, delayed=True,plot=False, debug=0, return_event=False,min_snr=None)

Generate multiplexed template from FDSN client.

Function to generate templates from an FDSN client. Must be given an obspy.Catalog class and the client_idas input. The function returns a list of obspy.Stream classes containing steams for each desired template.

Parameters

• catalog (obspy.core.event.Catalog) – Catalog class containing desiredtemplate events

• client_id (str) – Name of the client, either url, or Obspy mappable (see theobspy.clients.fdsn documentation).









• data_pad (int) – Length of data (in seconds) required before and after any event forprocessing, use to reduce edge-effects of filtering on the templates.







Returns List of obspy.core.stream.Stream Templates

Return type list

Warning: This function is depreciated and will be removed in a forthcoming release. Please usetemplate_gen instead.




https://docs.obspy.org/packages/obspy.clients.fdsn.html#module-obspy.clients.fdsn


















Note: process_len should be set to the same length as used when computing detections usingmatch_filter.match_filter, e.g. if you read in day-long data for match_filter, process_len should be 86400.

Example

>>> from obspy.clients.fdsn import Client>>> from eqcorrscan.core.template_gen import from_client>>> client = Client('NCEDC')>>> catalog = client.get_events(eventid='72572665', includearrivals=True)>>> # We are only taking two picks for this example to speed up the>>> # example, note that you don't have to!>>> catalog[0].picks = catalog[0].picks[0:2]>>> templates = from_client(catalog=catalog, client_id='NCEDC',... lowcut=2.0, highcut=9.0, samp_rate=20.0,... filt_order=4, length=3.0, prepick=0.15,... swin='all', process_len=300,... all_horiz=True)>>> templates[0].plot(equal_scale=False, size=(800,600))

3.5. Core 89


eqcorrscan.core.template_gen.from_meta_file

eqcorrscan.core.template_gen.from_meta_file(meta_file, st, lowcut, highcut, samp_rate,filt_order, length, prepick, swin,all_horiz=False, delayed=True,plot=False, parallel=True, debug=0,return_event=False, min_snr=None)

Generate a multiplexed template from a local file.

Function to generate a template from a local observation file and an obspy.Stream object.

Parameters

• meta_file (str) – File containing pick information, can contain multipleevents. File must be formatted in a way readable by obspy.core.event.read_events().

• st (obspy.core.stream.Stream) – Stream containing waveform data for tem-plate (hopefully). Note that this should be the same length of stream as you will use forthe continuous detection, e.g. if you detect in day-long files, give this a day-long file!










• plot (bool) – Display template plots or not

• parallel (bool) – Whether to process data in parallel or not.




Returns List of obspy.core.stream.Stream newly cut templates

Return type list

Note: All picks must be associated with a station and channel, this is not the case for NonLinLoc HYPfiles, will not use any picks that do not have this association.

Warning: We suggest giving this function a full day of data, to ensure templates are generated withexactly the same processing as the continuous data. Not doing this will result in slightly reduced cross-correlation values.



https://docs.obspy.org/packages/autogen/obspy.core.event.read_events.html#obspy.core.event.read_events

https://docs.obspy.org/packages/autogen/obspy.core.event.read_events.html#obspy.core.event.read_events


















Example

>>> from obspy import read>>> from eqcorrscan.core.template_gen import from_meta_file>>> st = read('eqcorrscan/tests/test_data/WAV/TEST_/' +... '2013-09-01-0410-35.DFDPC_024_00')>>> quakeml = 'eqcorrscan/tests/test_data/20130901T041115.xml'>>> templates = from_meta_file(meta_file=quakeml, st=st, lowcut=2.0,... highcut=9.0, samp_rate=20.0, filt_order=3,... length=2, prepick=0.1, swin='S',... all_horiz=True)>>> print(len(templates[0]))10

eqcorrscan.core.template_gen.from_sac

eqcorrscan.core.template_gen.from_sac(sac_files, lowcut, highcut, samp_rate, filt_order,length, swin, prepick, all_horiz=False,delayed=True, plot=False, debug=0, re-turn_event=False, min_snr=None)

Generate a multiplexed template from a list of SAC files.

Function to read picks and waveforms from SAC data, and generate a template from these. Usually sac_filesis a list of all single-channel SAC files for a given event, a single, multi-channel template will be createdfrom these traces.

All files listed in sac_files should be associated with a single event.

Parameters

• sac_files (list) – osbpy.core.stream.Stream of sac waveforms, or list of paths tosac waveforms.




• filt_order (int) – Filter level.



• prepick (float) – Length to extract prior to the pick in seconds.



• plot (bool) – Turns template plotting on or off.

• debug (int) – Debug level, higher number=more output.



Returns Newly cut template.


3.5. Core 91
















Note: This functionality is not supported for obspy versions below 1.0.0 as references times are not readin by SACIO, which are needed for defining pick times.

Example

>>> from eqcorrscan.core.template_gen import from_sac>>> import glob>>> # Get all the SAC-files associated with one event.>>> sac_files = glob.glob('eqcorrscan/tests/test_data/SAC/2014p611252/*')>>> templates = from_sac(sac_files=sac_files, lowcut=2.0, highcut=10.0,... samp_rate=25.0, filt_order=4, length=2.0,... swin='all', prepick=0.1, all_horiz=True)>>> print(templates[0][0].stats.sampling_rate)25.0>>> print(len(templates[0]))15

eqcorrscan.core.template_gen.from_seishub

eqcorrscan.core.template_gen.from_seishub(catalog, url, lowcut, highcut, samp_rate,filt_order, length, prepick, swin,process_len=86400, data_pad=90,all_horiz=False, delayed=True,plot=False, debug=0, return_event=False,min_snr=None)

Generate multiplexed template from SeisHub database.

Function to generate templates from a SeisHub database. Must be given an obspy.Catalog class and theSeisHub url as input. The function returns a list of obspy.Stream classes containting steams for each desiredtemplate.

Parameters

• catalog (obspy.core.event.Catalog) – Catalog class containing desiredtemplate events

• url (str) – url of SeisHub database instance









• data_pad (int) – Length of data (in seconds) required before and after any event forprocessing, use to reduce edge-effects of filtering on the templates.





















Returns List of obspy.core.stream.Stream of newly cut templates

Return type list

Note: process_len should be set to the same length as used when computing detections usingmatch_filter.match_filter, e.g. if you read in day-long data fro match_filter, process_len should be 86400.

Warning: Not tested in continuous integration (due to lack of seishub client), let us know of anyfailures.

eqcorrscan.core.template_gen.multi_template_gen

eqcorrscan.core.template_gen.multi_template_gen(catalog, st, length, swin=’all’,prepick=0.05, all_horiz=False,delayed=True, plot=False, de-bug=0, return_event=False,min_snr=None)

Generate multiple templates from one stream of data.

Thin wrapper around _template_gen to generate multiple templates from one stream of continuous data.Takes processed (filtered and resampled) seismic data!

Parameters

• catalog (obspy.core.event.Catalog) – Events to extract templates for

• st (obspy.core.stream.Stream) – Processed stream to extract from, e.g. fil-tered and re-sampled to what you want using pre_processing.dayproc.

• length (float) – Length of template in seconds

• swin (string) – P, S, P_all, S_all or all, defaults to all: see note in eqcorrscan.core.template_gen.template_gen()

• prepick (float) – Length in seconds to extract before the pick time default is 0.05seconds.


• delayed (bool) –

If True, each channel will begin relative to it’s own pick-time, if set to False, eachchannel will begin at the same time.

• plot (bool) – To plot the template or not, default is True



3.5. Core 93


















Returns List of obspy.core.stream.Stream templates.

Return type list

Warning: Data must be processed before using this function - highcut, lowcut and filt_order are onlyused to generate the meta-data for the templates.

Note: By convention templates are generated with P-phases on the vertical channel and S-phases on thehorizontal channels, normal seismograph naming conventions are assumed, where Z denotes vertical and N,E, R, T, 1 and 2 denote horizontal channels, either oriented or not. To this end we will only use Z channelsif they have a P-pick, and will use one or other horizontal channels only if there is an S-pick on it.

Warning: If there is no phase_hint included in picks, and swin=all, all channels with picks will beused.

3.6 Utils

Utility functions for integration with other software, and for the analysis of waveforms detected by cross-correlation.

3.6.1 archive_read

Helper functions for reading data from archives for the EQcorrscan package.

Note: These functions are tools to aid simplification of general scripts, they do not cover all use cases, howeverif you have a use case you want to see here, then let the authors know, or implement it yourself and contribute itback to the project.



Classes & Functions

read_data Function to read the appropriate data from an archivefor a day.

eqcorrscan.utils.archive_read.read_data

eqcorrscan.utils.archive_read.read_data(archive, arc_type, day, stachans,length=86400)

Function to read the appropriate data from an archive for a day.

Parameters

• archive (str) – The archive source - if arc_type is seishub, this should be a url, if







the arc_type is FDSN then this can be either a url or a known obspy client. If arc_typeis day_vols, then this is the path to the top directory.

• arc_type (str) – The type of archive, can be: seishub, FDSN, day_volumes

• day (datetime.date) – Date to retrieve data for

• stachans (list) – List of tuples of Stations and channels to try and get, will not failif stations are not available, but will warn.

• length (float) – Data length to extract in seconds, defaults to 1 day.

Returns Stream of data


Note: A note on arc_types, if arc_type is day_vols, then this will look for directories labelled in the IRISDMC conventions of Yyyyy/Rjjj.01/. . . where yyyy is the year and jjj is the julian day. Data within thesefiles directories should be stored as day-long, single-channel files. This is not implemented in the fastedway possible to allow for a more general situation. If you require more speed you will need to re-write this.

Example

>>> from obspy import UTCDateTime>>> t1 = UTCDateTime(2012, 3, 26)>>> stachans = [('JCNB', 'SP1')]>>> st = read_data('NCEDC', 'FDSN', t1, stachans)>>> print(st)1 Trace(s) in Stream:BP.JCNB.40.SP1 | 2012-03-26T00:00:00.000000Z - 2012-03-26T23:59:59.950000Z |→˓20.0 Hz, 1728000 samples

Example, missing data

>>> t1 = UTCDateTime(2012, 3, 26)>>> stachans = [('JCNB', 'SP1'), ('GCSZ', 'HHZ')]>>> st = read_data('NCEDC', 'FDSN', t1, stachans)>>> print(st)1 Trace(s) in Stream:BP.JCNB.40.SP1 | 2012-03-26T00:00:00.000000Z - 2012-03-26T23:59:59.950000Z |→˓20.0 Hz, 1728000 samples

Example, local day-volumes

>>> t1 = UTCDateTime(2012, 3, 26)>>> stachans = [('WHYM', 'SHZ'), ('EORO', 'SHZ')]>>> st = read_data('eqcorrscan/tests/test_data/day_vols', 'day_vols',... t1, stachans)>>> print(st)2 Trace(s) in Stream:AF.WHYM..SHZ | 2012-03-26T00:00:00.000000Z - 2012-03-26T23:59:59.000000Z | 1.0→˓Hz, 86400 samplesAF.EORO..SHZ | 2012-03-26T00:00:00.000000Z - 2012-03-26T23:59:59.000000Z | 1.0→˓Hz, 86400 samples

3.6. Utils 95


https://docs.python.org/2.7/library/datetime.html#datetime.date




Private Functions

_check_available_data Function to check what stations are available in thearchive for a given day.

_get_station_file Helper function to find the correct file.

eqcorrscan.utils.archive_read._check_available_data

eqcorrscan.utils.archive_read._check_available_data(archive, arc_type, day)Function to check what stations are available in the archive for a given day.

Parameters

• archive (str) – The archive source

• arc_type (str) – The type of archive, can be:

• day (datetime.date) – Date to retrieve data for

Returns list of tuples of (station, channel) as available.

Note: Currently the seishub options are untested.

eqcorrscan.utils.archive_read._get_station_file

eqcorrscan.utils.archive_read._get_station_file(path_name, station, channel, de-bug=0)

Helper function to find the correct file.

Parameters path_name (str) – Path to files to check.

Returns list of filenames, str

3.6.2 catalog_to_dd

This module contains functions to convert seisan catalogue to files to hypoDD input files.

These functions will generate both a catalogue (dt.ct) file, event file (event.dat), station information file (sta-tion.dat), and a correlation oiutput file correlated every event in the catalogue with every other event to optimizethe picks (dt.cc).

The correlation routine relies on obspy’s xcorr_pick_correction function from the obspy.signal.cross_correlationmodule. This function optimizes picks to better than sample accuracy by interpolating the correlation functionand finding the maximum of this rather than the true maximum correlation value. The output from this function isstored in the dt.cc file.

Information for the station.dat file is read from SEISAN’s STATION0.HYP file

Earthquake picks and locations are taken from the catalogued s-files - these must be pre-located before enteringthis routine as origin times and hypocentre locations are needed for event.dat files.



Classes & Functions








readSTATION0 Read a Seisan STATION0.HYP file on the path given.read_phase Read hypoDD phase files into Obspy catalog class.sfiles_to_event Write an event.dat file from a list of Seisan eventswrite_catalog Generate a dt.ct for hypoDD for a series of events.write_correlations Write a dt.cc file for hypoDD input for a given list of

events.write_event Write obspy.core.event.Catalog to a hypoDD format

event.dat file.

eqcorrscan.utils.catalog_to_dd.readSTATION0

eqcorrscan.utils.catalog_to_dd.readSTATION0(path, stations)Read a Seisan STATION0.HYP file on the path given.

Outputs the information, and writes to station.dat file.

Parameters

• path (str) – Path to the STATION0.HYP file

• stations (list) – Stations to look for

Returns List of tuples of station, lat, long, elevation

Return type list

>>> readSTATION0('eqcorrscan/tests/test_data', ['WHFS', 'WHAT2', 'BOB'])[('WHFS', -43.261, 170.359, 60.0), ('WHAT2', -43.2793, 170.36038333333335, 95.→˓0), ('BOB', 41.408166666666666, -174.87116666666665, 101.0)]

eqcorrscan.utils.catalog_to_dd.read_phase

eqcorrscan.utils.catalog_to_dd.read_phase(ph_file)Read hypoDD phase files into Obspy catalog class.

Parameters ph_file (str) – Phase file to read event info from.

Returns Catalog of events from file.


>>> from obspy.core.event.catalog import Catalog>>> catalog = read_phase('eqcorrscan/tests/test_data/tunnel.phase')>>> isinstance(catalog, Catalog)True

eqcorrscan.utils.catalog_to_dd.sfiles_to_event

eqcorrscan.utils.catalog_to_dd.sfiles_to_event(sfile_list)Write an event.dat file from a list of Seisan events

Parameters sfile_list (list) – List of s-files to sort and put into the database

Returns List of tuples of event ID (int) and Sfile name

eqcorrscan.utils.catalog_to_dd.write_catalog

eqcorrscan.utils.catalog_to_dd.write_catalog(event_list, max_sep=8, min_link=8,debug=0)

Generate a dt.ct for hypoDD for a series of events.

3.6. Utils 97





Takes input event list from eqcorrscan.utils.catalog_to_dd.write_event() as a list oftuples of event id and sfile. It will read the pick information from the seisan formated s-file using thesfile_util utilities.

Parameters

• event_list (list) – List of tuples of event_id (int) and sfile (String)

• max_sep (float) – Maximum separation between event pairs in km

• min_link (int) – Minimum links for an event to be paired, e.g. minimum number ofpicks from the same station and channel (and phase) that are shared between two eventsfor them to be paired.

• debug (int) – Debug output level.

Returns list of stations that have been used in this catalog

Note: We have not yet implemented a method for taking unassociated event objects and wavefiles. Assuch if you have events with associated wavefiles you are advised to generate Sfiles for each event using theeqcorrscan.utils.sfile_util module prior to this step.

eqcorrscan.utils.catalog_to_dd.write_correlations

eqcorrscan.utils.catalog_to_dd.write_correlations(event_list, wavbase, ex-tract_len, pre_pick, shift_len,lowcut=1.0, highcut=10.0,max_sep=8, min_link=8,cc_thresh=0.0, plotvar=False,debug=0)

Write a dt.cc file for hypoDD input for a given list of events.

Takes an input list of events and computes pick refinements by correlation. Outputs two files, dt.cc anddt.cc2, each provides a different weight, dt.cc uses weights of the cross-correlation, and dt.cc2 providesweights as the square of the cross-correlation.

Parameters

• event_list (list) – List of tuples of event_id (int) and sfile (String)

• wavbase (str) – Path to the seisan wave directory that the wavefiles in the S-files arestored

• extract_len (float) – Length in seconds to extract around the pick

• pre_pick (float) – Time before the pick to start the correlation window

• shift_len (float) – Time to allow pick to vary

• lowcut (float) – Lowcut in Hz - default=1.0

• highcut (float) – Highcut in Hz - default=10.0

• max_sep (float) – Maximum separation between event pairs in km

• min_link (int) – Minimum links for an event to be paired

• cc_thresh (float) – Threshold to include cross-correlation results.

• plotvar (bool) – To show the pick-correction plots, defualts to False.

• debug (int) – Variable debug levels from 0-5, higher=more output.

















Warning: This is not a fast routine!

Warning: In contrast to seisan’s corr routine, but in accordance with the hypoDD manual, this outputscorrected differential time.

Note: Currently we have not implemented a method for taking unassociated event objects and wavefiles.As such if you have events with associated wavefiles you are advised to generate Sfiles for each event usingthe sfile_util module prior to this step.

Note: There is no provision to taper waveforms within these functions, if you desire this functionality, youshould apply the taper before calling this. Note the obspy.Trace.taper() functions.

eqcorrscan.utils.catalog_to_dd.write_event

eqcorrscan.utils.catalog_to_dd.write_event(catalog)Write obspy.core.event.Catalog to a hypoDD format event.dat file.

Parameters catalog (obspy.core.event.Catalog) – A catalog of obspy events.

3.6.3 catalog_utils

Helper functions for common handling tasks for catalog objects.

Note: These functions are tools to aid simplification of general scripts, they do not cover all use cases, howeverif you have a use case you want to see here, then let the authors know, or implement it yourself and contribute itback to the project, or, if its really good, give it to the obspy guys!



Classes & Functions

filter_picks Filter events in the catalog based on a number of pa-rameters.

eqcorrscan.utils.catalog_utils.filter_picks

eqcorrscan.utils.catalog_utils.filter_picks(catalog, stations=None, chan-nels=None, networks=None, lo-cations=None, top_n_picks=None,evaluation_mode=’all’)

Filter events in the catalog based on a number of parameters.

Parameters

• catalog (obspy.core.event.Catalog) – Catalog to filter.

• stations (list) – List for stations to keep picks from.

3.6. Utils 99





• channels (list) – List of channels to keep picks from.

• networks (list) – List of networks to keep picks from.

• locations (list) – List of location codes to use

• top_n_picks (int) – Filter only the top N most used station-channel pairs.

• evaluation_mode (str) – To select only manual or automatic picks, or use all(default).

Returns Filtered Catalog - if events are left with no picks, they are removed from the catalog.


Note: Will filter first by station, then by channel, then by network, if using top_n_picks, this will be donelast, after the other filters have been applied.

Note: Doesn’t work in place on the catalog, your input catalog will be safe unless you overwrite it.

Note: Doesn’t expand wildcard characters.

Example

>>> from obspy.clients.fdsn import Client>>> from eqcorrscan.utils.catalog_utils import filter_picks>>> from obspy import UTCDateTime>>> client = Client('NCEDC')>>> t1 = UTCDateTime(2004, 9, 28)>>> t2 = t1 + 86400>>> catalog = client.get_events(starttime=t1, endtime=t2, minmagnitude=3,... minlatitude=35.7, maxlatitude=36.1,... minlongitude=-120.6, maxlongitude=-120.2,... includearrivals=True)>>> print(len(catalog))12>>> filtered_catalog = filter_picks(catalog, stations=['BMS', 'BAP',... 'PAG', 'PAN',... 'PBI', 'PKY',... 'YEG', 'WOF'])>>> print(len(filtered_catalog))12>>> stations = []>>> for event in filtered_catalog:... for pick in event.picks:... stations.append(pick.waveform_id.station_code)>>> print(sorted(list(set(stations))))['BAP', 'BMS', 'PAG', 'PAN', 'PBI', 'PKY', 'WOF', 'YEG']

3.6.4 clustering

Functions to cluster seismograms by a range of constraints.









Classes & Functions

svd Compute the SVD of a number of templates.svd_to_stream Convert the singular vectors output by SVD to

streams.cluster Cluster template waveforms based on average corre-

lations.corr_cluster Group traces based on correlations above threshold

with the stack.cross_chan_coherence Calculate cross-channel coherency.dist_mat_km Compute the distance matrix for all a catalog using

epicentral separation.distance_matrix Compute distance matrix for waveforms based on

cross-correlations.empirical_svd Empirical subspace detector generation function.extract_detections Extract waveforms associated with detectionsgroup_delays Group template waveforms according to their arrival

times (delays).re_thresh_csv Remove detections by changing the threshold.space_cluster Cluster a catalog by distance only.space_time_cluster Cluster detections in space and time.

eqcorrscan.utils.clustering.svd

eqcorrscan.utils.clustering.svd(stream_list, full=False)Compute the SVD of a number of templates.

Returns the singular vectors and singular values of the templates.

Parameters

• stream_list (List of :class: obspy.Stream) – List of the templates tobe analysed

• full (bool) – Whether to compute the full input vector matrix or not.

Returns SValues(list) for each channel, SVectors(list of ndarray), UVectors(list of ndarray) foreach channel, stachans, List of String (station.channel)

Note: We recommend that you align the data before computing the SVD, e.g., the P-arrival on all templatesfor the same channel should appear at the same time in the trace. See the stacking.align_traces function fora way to do this.

Note: Uses the numpy.linalg.svd function, their U, s and V are mapped to UVectors, SValues and SVectorsrespectively. Their V (and ours) corresponds to V.H.

eqcorrscan.utils.clustering.svd_to_stream

eqcorrscan.utils.clustering.svd_to_stream(uvectors, stachans, k, sampling_rate)Convert the singular vectors output by SVD to streams.

One stream will be generated for each singular vector level, for all channels. Useful for plotting, and aidingseismologists thinking of waveforms!

Parameters

3.6. Utils 101



• svectors (list) – List of numpy.ndarray Singular vectors

• stachans (list) – List of station.channel Strings

• k (int) – Number of streams to return = number of SV’s to include

• sampling_rate (float) – Sampling rate in Hz

Returns svstreams, List of obspy.core.stream.Stream, with svStreams[0] being com-posed of the highest rank singular vectors.

eqcorrscan.utils.clustering.cluster

eqcorrscan.utils.clustering.cluster(template_list, show=True, corr_thresh=0.3, al-low_shift=False, shift_len=0, save_corrmat=False,cores=’all’, debug=1)

Cluster template waveforms based on average correlations.

Function to take a set of templates and cluster them, will return groups as lists of streams. Clustering is doneby computing the cross-channel correlation sum of each stream in stream_list with every other stream in thelist. scipy.cluster.hierarchy functions are then used to compute the complete distance matrix,where distance is 1 minus the normalised cross-correlation sum such that larger distances are less similarevents. Groups are then created by clustering the distance matrix at distances less than 1 - corr_thresh.

Will compute the distance matrix in parallel, using all available cores

Parameters

• template_list (list) – List of tuples of the template (obspy.core.stream.Stream) and the template id to compute clustering for

• show (bool) – plot linkage on screen if True, defaults to True

• corr_thresh (float) – Cross-channel correlation threshold for grouping

• allow_shift (bool) – Whether to allow the templates to shift when correlating

• shift_len (float) – How many seconds to allow the templates to shift

• save_corrmat (bool) – If True will save the distance matrix to dist_mat.npy in thelocal directory.

• cores (int) – number of cores to use when computing the distance matrix, defaultsto ‘all’ which will work out how many cpus are available and hog them.

• debug (int) – Level of debugging from 1-5, higher is more output, currently onlylevel 1 implemented.

Returns List of groups. Each group is a list of obspy.core.stream.Stream making upthat group.

eqcorrscan.utils.clustering.corr_cluster

eqcorrscan.utils.clustering.corr_cluster(trace_list, thresh=0.9)Group traces based on correlations above threshold with the stack.

Will run twice, once with a lower threshold to remove large outliers that would negatively affect the stack,then again with your threshold.

Parameters

• trace_list (list) – List of obspy.core.stream.Trace to compute similar-ity between

• thresh (float) – Correlation threshold between -1-1






https://docs.scipy.org/doc/scipy/reference/cluster.hierarchy.html#module-scipy.cluster.hierarchy













Returns numpy.ndarray of bool of whether that trace correlates well enough (above yourgiven threshold) with the stack.

Note: We recommend that you align the data before computing the clustering, e.g., the P-arrival on alltemplates for the same channel should appear at the same time in the trace. See the eqcorrscan.utils.stacking.align_traces() function for a way to do this.

eqcorrscan.utils.clustering.cross_chan_coherence

eqcorrscan.utils.clustering.cross_chan_coherence(st1, st2, allow_shift=False,shift_len=0.2, i=0,xcorr_func=’time_domain’)

Calculate cross-channel coherency.

Determine the cross-channel coherency between two streams of multichannel seismic data.

Parameters

• st1 (obspy.core.stream.Stream) – Stream one

• st2 (obspy.core.stream.Stream) – Stream two

• allow_shift (bool) – Whether to allow the optimum alignment to be found forcoherence, defaults to False for strict coherence

• shift_len (float) – Seconds to shift, only used if allow_shift=True

• i (int) – index used for parallel async processing, returned unaltered

• xcorr_func (str, callable) –

The method for performing correlations. Accepts either a string or callabe. Seeeqcorrscan.utils.correlate.register_array_xcorr() for moredetails

Returns cross channel coherence, float - normalized by number of channels, and i, where i isint, as input.

Return type tuple

eqcorrscan.utils.clustering.dist_mat_km

eqcorrscan.utils.clustering.dist_mat_km(catalog)Compute the distance matrix for all a catalog using epicentral separation.

Will give physical distance in kilometers.

Parameters catalog (obspy.core.event.Catalog) – Catalog for which to computethe distance matrix

Returns distance matrix


eqcorrscan.utils.clustering.distance_matrix

eqcorrscan.utils.clustering.distance_matrix(stream_list, allow_shift=False,shift_len=0, cores=1)

Compute distance matrix for waveforms based on cross-correlations.

3.6. Utils 103











Function to compute the distance matrix for all templates - will give distance as 1-abs(cccoh), e.g. a wellcorrelated pair of templates will have small distances, and an equally well correlated reverse image willhave the same distance as a positively correlated image - this is an issue.

Parameters

• stream_list (list) – List of the obspy.core.stream.Stream to computethe distance matrix for

• allow_shift (bool) – To allow templates to shift or not?

• shift_len (float) – How many seconds for templates to shift

• cores (int) – Number of cores to parallel process using, defaults to 1.

Returns distance matrix


Warning: Because distance is given as 1 − 𝑎𝑏𝑠(𝑐𝑜ℎ𝑒𝑟𝑒𝑛𝑐𝑒), negatively correlated and positivelycorrelated objects are given the same distance.

eqcorrscan.utils.clustering.empirical_svd

eqcorrscan.utils.clustering.empirical_svd(stream_list, linear=True)Empirical subspace detector generation function.

Takes a list of templates and computes the stack as the first order subspace detector, and the differential ofthis as the second order subspace detector following the empirical subspace method of Barrett & Beroza,2014 - SRL.

Parameters

• stream_list (list) – list of streams to compute the subspace detectors from,where streams are obspy.core.stream.Stream objects.

• linear (bool) – Set to true by default to compute the linear stack as the first subspacevector, False will use the phase-weighted stack as the first subspace vector.

Returns list of two obspy.core.stream.Stream s

eqcorrscan.utils.clustering.extract_detections

eqcorrscan.utils.clustering.extract_detections(detections, templates, archive,arc_type, extract_len=90.0, out-dir=None, extract_Z=True, addi-tional_stations=[])

Extract waveforms associated with detections

Takes a list of detections for the template, template. Waveforms will be returned as a list of obspy.core.stream.Stream containing segments of extract_len. They will also be saved if outdir is set. The defaultis unset. The default extract_len is 90 seconds per channel.

Parameters

• detections (list) – List of eqcorrscan.core.match_filter.Detection.

• templates (list) – A list of tuples of the template name and the template Streamused to detect detections.

• archive (str) – Either name of archive or path to continuous data, seeeqcorrscan.utils.archive_read() for details







http://srl.geoscienceworld.org/content/85/3/594.extract

http://srl.geoscienceworld.org/content/85/3/594.extract








• arc_type (str) – Type of archive, either seishub, FDSN, day_vols

• extract_len (float) – Length to extract around the detection (will be equally cutaround the detection time) in seconds. Default is 90.0.

• outdir (str) – Default is None, with None set, no files will be saved, if set eachdetection will be saved into this directory with files named according to the detectiontime, NOT than the waveform start time. Detections will be saved into template subdi-rectories. Files written will be multiplexed miniseed files, the encoding will be chosenautomatically and will likely be float.

• extract_Z (bool) – Set to True to also extract Z channels for detections delays willbe the same as horizontal channels, only applies if only horizontal channels were usedin the template.

• additional_stations (list) – List of tuples of (station, channel) to also extractdata for using an average delay.

Returns list of obspy.core.streams.Stream

Return type list

>>> from eqcorrscan.utils.clustering import extract_detections>>> from eqcorrscan.core.match_filter import Detection>>> from obspy import read, UTCDateTime>>> import os>>> # Use some dummy detections, you would use real one>>> detections = [Detection('temp1', UTCDateTime(2012, 3, 26, 9, 15), 2,... ['WHYM', 'EORO'], 2, 1.2, 'corr', 'MAD', 8.0),... Detection('temp2',UTCDateTime(2012, 3, 26, 18, 5), 2,... ['WHYM', 'EORO'], 2, 1.2, 'corr', 'MAD', 8.0)]>>> path_to_templates = os.path.join('eqcorrscan', 'tests', 'test_data')>>> archive = os.path.join(path_to_templates, 'day_vols')>>> template_files = [os.path.join(path_to_templates, 'temp1.ms'),... os.path.join(path_to_templates, 'temp2.ms')]>>> templates = [('temp' + str(i), read(filename))... for i, filename in enumerate(template_files)]>>> extracted = extract_detections(detections, templates,... archive=archive, arc_type='day_vols')Working on detections for day: 2012-03-26T00:00:00.000000ZCutting for detections at: 2012/03/26 09:15:00Cutting for detections at: 2012/03/26 18:05:00>>> print(extracted[0].sort())2 Trace(s) in Stream:AF.EORO..SHZ | 2012-03-26T09:14:15.000000Z - 2012-03-26T09:15:45.000000Z | 1.0→˓Hz, 91 samplesAF.WHYM..SHZ | 2012-03-26T09:14:15.000000Z - 2012-03-26T09:15:45.000000Z | 1.0→˓Hz, 91 samples>>> print(extracted[1].sort())2 Trace(s) in Stream:AF.EORO..SHZ | 2012-03-26T18:04:15.000000Z - 2012-03-26T18:05:45.000000Z | 1.0→˓Hz, 91 samplesAF.WHYM..SHZ | 2012-03-26T18:04:15.000000Z - 2012-03-26T18:05:45.000000Z | 1.0→˓Hz, 91 samples>>> # Extract from stations not included in the detections>>> extracted = extract_detections(... detections, templates, archive=archive, arc_type='day_vols',... additional_stations=[('GOVA', 'SHZ')])Adding additional stationsAdded station GOVA.SHZAdded station GOVA.SHZWorking on detections for day: 2012-03-26T00:00:00.000000ZCutting for detections at: 2012/03/26 09:15:00Cutting for detections at: 2012/03/26 18:05:00


3.6. Utils 105







>>> print(extracted[0].sort())3 Trace(s) in Stream:AF.EORO..SHZ | 2012-03-26T09:14:15.000000Z - 2012-03-26T09:15:45.000000Z | 1.0→˓Hz, 91 samplesAF.GOVA..SHZ | 2012-03-26T09:14:15.000000Z - 2012-03-26T09:15:45.000000Z | 1.0→˓Hz, 91 samplesAF.WHYM..SHZ | 2012-03-26T09:14:15.000000Z - 2012-03-26T09:15:45.000000Z | 1.0→˓Hz, 91 samples>>> # The detections can be saved to a file:>>> extract_detections(detections, templates, archive=archive,... arc_type='day_vols',... additional_stations=[('GOVA', 'SHZ')], outdir='.')Adding additional stationsAdded station GOVA.SHZAdded station GOVA.SHZWorking on detections for day: 2012-03-26T00:00:00.000000ZCutting for detections at: 2012/03/26 09:15:00Written file: ./temp1/2012-03-26_09-15-00.msCutting for detections at: 2012/03/26 18:05:00Written file: ./temp2/2012-03-26_18-05-00.ms

eqcorrscan.utils.clustering.group_delays

eqcorrscan.utils.clustering.group_delays(stream_list)Group template waveforms according to their arrival times (delays).

Parameters stream_list (list) – List of obspy.core.stream.Stream waveformsyou want to group.

Returns list of List of obspy.core.stream.Stream where each initial list is a group withthe same delays.

Return type list

eqcorrscan.utils.clustering.re_thresh_csv

eqcorrscan.utils.clustering.re_thresh_csv(path, old_thresh, new_thresh, chan_thresh)Remove detections by changing the threshold.

Can only be done to remove detection by increasing threshold, threshold lowering will have no effect.

Parameters

• path (str) – Path to the .csv detection file

• old_thresh (float) – Old threshold MAD multiplier

• new_thresh (float) – New threshold MAD multiplier

• chan_thresh (int) – Minimum number of channels for a detection

Returns List of detections

Return type list

Example

>>> from eqcorrscan.utils.clustering import re_thresh_csv>>> import os>>> det_file = os.path.join('eqcorrscan', 'tests', 'test_data',











... 'expected_tutorial_detections.txt')>>> detections = re_thresh_csv(path=det_file, old_thresh=8, new_thresh=10,... chan_thresh=3)Read in 22 detectionsLeft with 17 detections

Note: This is a legacy function, and will read detections from all versions.

Warning: Only works if thresholding was done by MAD.

eqcorrscan.utils.clustering.space_cluster

eqcorrscan.utils.clustering.space_cluster(catalog, d_thresh, show=True)Cluster a catalog by distance only.

Will compute the matrix of physical distances between events and utilize the scipy.clustering.hierarchy module to perform the clustering.

Parameters

• catalog (obspy.core.event.Catalog) – Catalog of events to clustered

• d_thresh (float) – Maximum inter-event distance threshold

Returns list of obspy.core.event.Catalog objects

Return type list

>>> from eqcorrscan.utils.clustering import space_cluster>>> from obspy.clients.fdsn import Client>>> from obspy import UTCDateTime>>> client = Client("NCEDC")>>> starttime = UTCDateTime("2002-01-01")>>> endtime = UTCDateTime("2002-02-01")>>> cat = client.get_events(starttime=starttime, endtime=endtime,... minmagnitude=2)>>> groups = space_cluster(catalog=cat, d_thresh=2, show=False)

>>> from eqcorrscan.utils.clustering import space_cluster>>> from obspy.clients.fdsn import Client>>> from obspy import UTCDateTime>>> client = Client("https://earthquake.usgs.gov")>>> starttime = UTCDateTime("2002-01-01")>>> endtime = UTCDateTime("2002-02-01")>>> cat = client.get_events(starttime=starttime, endtime=endtime,... minmagnitude=6)>>> groups = space_cluster(catalog=cat, d_thresh=1000, show=False)

eqcorrscan.utils.clustering.space_time_cluster

eqcorrscan.utils.clustering.space_time_cluster(catalog, t_thresh, d_thresh)Cluster detections in space and time.

Use to separate repeaters from other events. Clusters by distance first, then removes events in those groupsthat are at different times.

Parameters

3.6. Utils 107





• catalog (obspy.core.event.Catalog) – Catalog of events to clustered

• t_thresh (float) – Maximum inter-event time threshold in seconds

• d_thresh (float) – Maximum inter-event distance in km

Returns list of obspy.core.event.Catalog objects

Return type list

>>> from eqcorrscan.utils.clustering import space_time_cluster>>> from obspy.clients.fdsn import Client>>> from obspy import UTCDateTime>>> client = Client("https://earthquake.usgs.gov")>>> starttime = UTCDateTime("2002-01-01")>>> endtime = UTCDateTime("2002-02-01")>>> cat = client.get_events(starttime=starttime, endtime=endtime,... minmagnitude=6)>>> groups = space_time_cluster(catalog=cat, t_thresh=86400, d_thresh=1000)

3.6.5 correlate

Correlation functions for multi-channel cross-correlation of seismic data.

Various routines used mostly for testing, including links to a compiled routine using FFTW, a Numpy fft routinewhich uses bottleneck for normalisation and a compiled time-domain routine. These have varying levels of effi-ciency, both in terms of overall speed, and in memory usage. The time-domain is the most memory efficient butslowest routine (although fast for small cases of less than a few hundred correlations), the Numpy routine is fast,but memory inefficient due to a need to store large double-precision arrays for normalisation. The fftw compiledroutine is faster and more memory efficient than the Numpy routine.



Classes & Functions

fftw_multi_normxcorr Use a C loop rather than a Python loop - in some casesthis will be fast.

fftw_normxcorr Normalised cross-correlation using the fftw library.numpy_normxcorr Compute the normalized cross-correlation using

numpy and bottleneck.time_multi_normxcorr Compute cross-correlations in the time-domain using

C routine.get_array_xcorr Get an normalized cross correlation function that

takes arrays as inputs.get_stream_xcorr Return a function for performing normalized cross

correlation on lists of streams.register_array_xcorr Decorator for registering correlation functions.

eqcorrscan.utils.correlate.fftw_multi_normxcorr

eqcorrscan.utils.correlate.fftw_multi_normxcorr(template_array, stream_array,pad_array, seed_ids, cores_inner,cores_outer)

Use a C loop rather than a Python loop - in some cases this will be fast.

Parameters

• template_array (dict) –







https://docs.python.org/2.7/library/stdtypes.html#dict


• stream_array (dict) –

• pad_array (dict) –

• seed_ids (list) –

rtype: np.ndarray, list :return: 3D Array of cross-correlations and list of used channels.

eqcorrscan.utils.correlate.fftw_normxcorr

eqcorrscan.utils.correlate.fftw_normxcorr(templates, stream, pads, threaded=False,*args, **kwargs)

Normalised cross-correlation using the fftw library.

Internally this function used double precision numbers, which is definitely required for seismic data. Cross-correlations are computed as the inverse fft of the dot product of the ffts of the stream and the reversed,normalised, templates. The cross-correlation is then normalised using the running mean and standard devi-ation (not using the N-1 correction) of the stream and the sums of the normalised templates.

This python function wraps the C-library written by C. Chamberlain for this purpose.

Parameters

• templates (np.ndarray) – 2D Array of templates

• stream (np.ndarray) – 1D array of continuous data

• pads (list) – List of ints of pad lengths in the same order as templates

• threaded (bool) – Whether to use the threaded routine or not - note openMP andpython multiprocessing don’t seem to play nice for this.

Returns np.ndarray of cross-correlations

Returns np.ndarray channels used

eqcorrscan.utils.correlate.numpy_normxcorr

eqcorrscan.utils.correlate.numpy_normxcorr(templates, stream, pads, *args, **kwargs)Compute the normalized cross-correlation using numpy and bottleneck.

Parameters






eqcorrscan.utils.correlate.time_multi_normxcorr

eqcorrscan.utils.correlate.time_multi_normxcorr(templates, stream, pads,threaded=False, *args, **kwargs)

Compute cross-correlations in the time-domain using C routine.

Parameters




3.6. Utils 109





• threaded (bool) – Whether to use the threaded routine or not



eqcorrscan.utils.correlate.get_array_xcorr

eqcorrscan.utils.correlate.get_array_xcorr(name_or_func=None)Get an normalized cross correlation function that takes arrays as inputs.

See eqcorrscan.utils.correlate.array_normxcorr() for expected function signature.

Parameters name_or_func (str or callable) – Either a name of a registered xcorrfunction or a callable that implements the standard array_normxcorr signature.

Returns callable wth array_normxcorr interface

see also eqcorrscan.utils.correlate.get_stream_xcorr()

eqcorrscan.utils.correlate.get_stream_xcorr

eqcorrscan.utils.correlate.get_stream_xcorr(name_or_func=None, concur-rency=None)

Return a function for performing normalized cross correlation on lists of streams.

Parameters

• name_or_func – Either a name of a registered function or a callable that implementsthe standard array_normxcorr signature.

• concurrency – Optional concurrency strategy, options are below.

Returns A callable with the interface of stream_normxcorr

Concurrency options

• multithread - use a threadpool for concurrency;

• multiprocess - use a process pool for concurrency;

• concurrent - use a customized concurrency strategy for the function, if not definedthreading will be used.

eqcorrscan.utils.correlate.register_array_xcorr

eqcorrscan.utils.correlate.register_array_xcorr(name, func=None,is_default=False)

Decorator for registering correlation functions.

Each function must have the same interface as numpy_normxcorr, which is f(templates, stream, pads, *args,**kwargs) any number of specific kwargs can be used.

Register_normxcorr can be used as a decorator (with or without arguments) or as a callable.

Parameters

• name (str, callable) – The name of the function for quick access, or the callablethat will be wrapped when used as a decorator.

• func (callable, optional) – The function to register

• is_default (bool) – True if this function should be marked as default normxcorr

Returns callable







All functions within this module (and therefore all correlation functions used in EQcorrscan) are normalised cross-correlations, which follow the definition that Matlab uses for .

In the time-domain this is as follows

𝑐(𝑡) =

∑︀𝑦(𝑎𝑦 − 𝑎)(𝑏𝑡+𝑦 − 𝑏𝑡)√︁∑︀

𝑦(𝑎𝑦 − 𝑎)(𝑎𝑦 − 𝑎)∑︀

𝑦(𝑏𝑡+𝑦 − 𝑏𝑡)(𝑏𝑡+𝑦 − 𝑏𝑡)

where 𝑐(𝑡) is the normalised cross-correlation at at time 𝑡, 𝑎 is the template window which has length 𝑦, 𝑏 is thecontinuous data, and 𝑎 is the mean of the template and 𝑏𝑡 is the local mean of the continuous data.

In practice the correlations only remove the mean of the template once, but we do remove the mean from thecontinuous data at every time-step. Without doing this (just removing the global mean), correlations are affected byjumps in average amplitude, which is most noticeable during aftershock sequences, or when using short templates.

In the frequency domain (functions eqcorrscan.utils.correlate.numpy_normxcorr(),eqcorrscan.utils.correlate.fftw_normxcorr(), fftw_multi_normxcorr()), correla-tions are computed using an equivalent method. All methods are tested against one-another to check for internalconsistency, and checked against results computed using Matlab’s function. These routines also give the same(within 0.00001) of openCV cross-correlations.

Selecting a correlation function

EQcorrscan strives to use sensible default algorithms for calculating correlation values, however, you may want tochange how correlations are caclulated to be more advantageous to your specific needs.

There are currently 3 different correlations functions currently included in EQcorrscan:

1. eqcorrscan.utils.correlate.numpy_normxcorr() known as “numpy”

2. eqcorrscan.utils.correlate.time_multi_normxcorr() known as “time_domain”

3. eqcorrscan.utils.correlate.fftw_normxcorr() known as “fftw”

Number 3 is the default.

Using Fast Matched Filter within EQcorrscan

provides fast time-domain correlations for both CPU and GPU architectures. For massively multi-threaded en-vironment this runs faster than the frequency-domain routines mative to EQcorrscan (when more than 40 CPUcores, or an NVIDIA GPU card is available) with less memory consumption. Documentation on how to call FastMatched Filter from within EQcorrscan is provided here: fast_matched_filter

Switching which correlation function is used

You can switch between correlation functions using the xcorr_func parameter included in: - eqcorrscan.core.match_filter.match_filter(), - eqcorrscan.core.match_filter.Tribe.detect(), - eqcorrscan.core.match_filter.Template.detect()

by:

1. passing a string (eg “numpy”, “time_domain”, or “fftw”) or;

2. passing a function

for example:

>>> import obspy>>> import numpy as np>>> from eqcorrscan.utils.correlate import numpy_normxcorr, set_xcorr>>> from eqcorrscan.core.match_filter import match_filter


3.6. Utils 111

utils.correlate.fast_matched_filter.html



>>> # generate some toy templates and stream>>> random = np.random.RandomState(42)>>> template = obspy.read()>>> stream = obspy.read()>>> for num, tr in enumerate(stream): # iter stream and embed templates... data = tr.data... tr.data = random.randn(6000) * 5... tr.data[100: 100 + len(data)] = data

>>> # do correlation using numpy rather than fftw>>> detections = match_filter(['1'], [template], stream, .5, 'absolute',... 1, False, xcorr_func='numpy')

>>> # do correlation using a custom function>>> def custom_normxcorr(templates, stream, pads, *args, **kwargs):... # Just to keep example short call other xcorr function... print('calling custom xcorr function')... return numpy_normxcorr(templates, stream, pads, *args, **kwargs)

>>> detections = match_filter(... ['1'], [template], stream, .5, 'absolute', 1, False,... xcorr_func=custom_normxcorr)calling custom xcorr function...

You can also use the set_xcorr object (eqcorrscan.utils.correlate.set_xcorr) to change which correlation functionis used. This can be done permanently or within the scope of a context manager:

>>> # change the default xcorr function for all code in the with block>>> with set_xcorr(custom_normxcorr):... detections = match_filter(['1'], [template], stream, .5,... 'absolute', 1, False)calling custom xcorr function...

>>> # permanently set the xcorr function (until the python kernel restarts)>>> set_xcorr(custom_normxcorr)default changed to custom_normxcorr>>> detections = match_filter(['1'], [template], stream, .5, 'absolute',... 1, False)calling custom xcorr function...>>> set_xcorr.revert() # change it back to the previous state

Notes on accuracy

To cope with floating-point rounding errors, correlations may not be calculated for data with low variance. If yousee a warning saying: “Some correlations not computed, are there zeros in the data? If not consider increasinggain”, check whether your data have zeros, and if not, but have low, but real amplitudes, multiply your data bysome value.

Warning

If data are padded with zeros prior to filtering then correlations may be incorrectly calculated where there arezeros. You should always pad after filtering. If you see warnings saying “Low variance, possible zeros, checkresult”, you should check that you have padded correctly and check that correlations haven’t been calculated whenyou don’t expect them.



3.6.6 despike

Functions for despiking seismic data.

Warning: Despike functions are in beta, they do not work that well.

Todo: Deconvolve spike to remove it, find peaks in the f-domain.



Classes & Functions

median_filter Filter out spikes in data above a multiple of MAD ofthe data.

template_remove Looks for instances of template in the trace and re-moves the matches.

eqcorrscan.utils.despike.median_filter

eqcorrscan.utils.despike.median_filter(tr, multiplier=10, windowlength=0.5, in-terp_len=0.05, debug=0)

Filter out spikes in data above a multiple of MAD of the data.

Currently only has the ability to replaces spikes with linear interpolation. In the future we would aim to fillthe gap with something more appropriate. Works in-place on data.

Parameters

• tr (obspy.core.trace.Trace) – trace to despike

• multiplier (float) – median absolute deviation multiplier to find spikes above.

• windowlength (float) – Length of window to look for spikes in in seconds.

• interp_len (float) – Length in seconds to interpolate around spikes.

• debug (int) – Debug output level between 0 and 5, higher is more output.

Returns obspy.core.trace.Trace

Warning: Not particularly effective, and may remove earthquake signals, use with caution.

eqcorrscan.utils.despike.template_remove

eqcorrscan.utils.despike.template_remove(tr, template, cc_thresh, windowlength, in-terp_len, debug=0)

Looks for instances of template in the trace and removes the matches.

Parameters

• tr (obspy.core.trace.Trace) – Trace to remove spikes from.

• template (osbpy.core.trace.Trace) – Spike template to look for in data.

• cc_thresh (float) – Cross-correlation threshold (-1 - 1).

3.6. Utils 113











• windowlength (float) – Length of window to look for spikes in in seconds.

• interp_len (float) – Window length to remove and fill in seconds.

• debug (int) – Debug level.

Returns tr, works in place.


3.6.7 findpeaks

Functions to find peaks in data above a certain threshold.



Classes & Functions

coin_trig Find network coincidence triggers within peaks of de-tection statistics.

find_peaks2_short Determine peaks in an array of data above a certainthreshold.

eqcorrscan.utils.findpeaks.coin_trig

eqcorrscan.utils.findpeaks.coin_trig(peaks, stachans, samp_rate, moveout, min_trig,trig_int)

Find network coincidence triggers within peaks of detection statistics.

Useful for finding network detections from sets of detections on individual stations.

Parameters

• peaks (list) – List of lists of tuples of (peak, index) for each station-channel. Indexshould be in samples.

• stachans (list) – List of tuples of (station, channel) in the order of peaks.


• moveout (float) – Allowable network moveout in seconds.

• min_trig (int) – Minimum station-channels required to declare a trigger.

• trig_int (float) – Minimum allowable time between network triggers in seconds.

Returns List of tuples of (peak, index), for the earliest detected station.

Return type list

>>> peaks = [[(0.5, 100), (0.3, 800)], [(0.4, 120), (0.7, 850)]]>>> triggers = coin_trig(peaks, [('a', 'Z'), ('b', 'Z')], 10, 3, 2, 1)>>> print(triggers)[(0.45, 100)]

eqcorrscan.utils.findpeaks.find_peaks2_short

eqcorrscan.utils.findpeaks.find_peaks2_short(arr, thresh, trig_int, debug=0,starttime=False, samp_rate=1.0,full_peaks=False)

Determine peaks in an array of data above a certain threshold.












Uses a mask to remove data below threshold and finds peaks in what is left.

Parameters

• arr (numpy.ndarray) – 1-D numpy array is required

• thresh (float) – The threshold below which will be considered noise and peakswill not be found in.

• trig_int (int) – The minimum difference in samples between triggers, if multiplepeaks within this window this code will find the highest.

• debug (int) – Optional, debug level 0-5

• starttime (obspy.core.utcdatetime.UTCDateTime) – Starttime for plot-ting, only used if debug > 2.

• samp_rate (float) – Sampling rate in Hz, only used for plotting if debug > 2.

• full_peaks (bool) – If True, will remove the issue eluded to below, by declusteringwithin data-sections above the threshold, rather than just taking the peak within thatsection. This will take more time. This defaults to True for match_filter.

Returns peaks: Lists of tuples of peak values and locations.

Return type list

>>> import numpy as np>>> arr = np.random.randn(100)>>> threshold = 10>>> arr[40] = 20>>> arr[60] = 100>>> find_peaks2_short(arr, threshold, 3)[(20.0, 40), (100.0, 60)]

Note: peak-finding is optimised for zero-mean cross-correlation data where fluctuations are frequent.Because of this, in certain cases some peaks may be missed if the trig_int is short and the threshold is low.Consider the following case:

>>> arr = np.array([1, .2, .2, .2, .2, 1, .2, .2, .2, .2, 1])>>> find_peaks2_short(arr, thresh=.2, trig_int=3)[(1.0, 0)]

Whereas you would expect the following:

>>> arr = np.array([1, .2, .2, .2, .2, 1, .2, .2, .2, .2, 1])>>> find_peaks2_short(arr, thresh=.2, trig_int=3, full_peaks=True)[(1.0, 0), (1.0, 5), (1.0, 10)]

This is rare and unlikely to happen for correlation cases, where trigger intervals are usually large and thresh-olds high.

3.6.8 mag_calc

Functions to calculate local magnitudes automatically, and to calcualte relative moments for near-repeating earth-quakes using singular-value decomposition techniques.



3.6. Utils 115










Classes & Functions

amp_pick_event Pick amplitudes for local magnitude for a singleevent.

calc_b_value Calculate the b-value for a range of completenessmagnitudes.

calc_max_curv Calculate the magnitude of completeness using themaximum curvature method.

dist_calc Function to calculate the distance in km between twopoints.

svd_moments Calculate relative moments/amplitudes usingsingular-value decomposition.

eqcorrscan.utils.mag_calc.amp_pick_event

eqcorrscan.utils.mag_calc.amp_pick_event(event, st, respdir, chans=[’Z’],var_wintype=True, winlen=0.9,pre_pick=0.2, pre_filt=True, lowcut=1.0,highcut=20.0, corners=4, min_snr=1.0,plot=False, remove_old=False,ps_multiplier=0.34, velocity=False)

Pick amplitudes for local magnitude for a single event.

Looks for maximum peak-to-trough amplitude for a channel in a stream, and picks this amplitude andperiod. There are a few things it does internally to stabilise the result:

1. Applies a given filter to the data - very necessary for small magnitude earthquakes;

2. Keeps track of the poles and zeros of this filter and removes them from the picked amplitude;

3. Picks the peak-to-trough amplitude, but records half of this: the specification for the localmagnitude is to use a peak amplitude on a horizontal, however, with modern digital seismome-ters, the peak amplitude often has an additional, DC-shift applied to it, to stabilise this, and toremove possible issues with de-meaning data recorded during the wave-train of an event (e.g. themean may not be the same as it would be for longer durations), we use half the peak-to-troughamplitude;

4. Despite the original definition of local magnitude requiring the use of a horizontal channel,more recent work has shown that the vertical channels give more consistent magnitude esti-mations between stations, due to a reduction in site-amplification effects, we therefore use thevertical channels by default, but allow the user to chose which channels they deem appropriate;

5. We do not specify that the maximum amplitude should be the S-phase: The original definitionholds that the maximum body-wave amplitude should be used - while this is often the S-phase,we do not discriminate against the P-phase. We do note that, unless the user takes care whenassigning winlen and filters, they may end up with amplitude picks for surface waves;

6. We use a variable window-length by default that takes into account P-S times if available,this is in an effort to include only the body waves. When P-S times are not available we us theps_multiplier variable, which defaults to 0.34 x hypocentral distance.

Parameters

• event (obspy.core.event.event.Event) – Event to pick

• st (obspy.core.stream.Stream) – Stream associated with event

• respdir (str) – Path to the response information directory

• chans (list) – List of the channels to pick on, defaults to [‘Z’] - should just be theorientations, e.g. Z, 1, 2, N, E






• var_wintype (bool) – If True, the winlen will be multiplied by the P-S time ifboth P and S picks are available, otherwise it will be multiplied by the hypocentraldistance*ps_multiplier, defaults to True

• winlen (float) – Length of window, see above parameter, if var_wintype is Falsethen this will be in seconds, otherwise it is the multiplier to the p-s time, defaults to 0.9.

• pre_pick (float) – Time before the s-pick to start the cut window, defaults to 0.2.

• pre_filt (bool) – To apply a pre-filter or not, defaults to True

• lowcut (float) – Lowcut in Hz for the pre-filter, defaults to 1.0

• highcut (float) – Highcut in Hz for the pre-filter, defaults to 20.0

• corners (int) – Number of corners to use in the pre-filter

• min_snr (float) – Minimum signal-to-noise ratio to allow a pick - see note belowon signal-to-noise ratio calculation.

• plot (bool) – Turn plotting on or off.

• remove_old (bool) – If True, will remove old amplitude picks from event and over-write with new picks. Defaults to False.

• ps_multiplier (float) – A p-s time multiplier of hypocentral distance - defaultsto 0.34, based on p-s ratio of 1.68 and an S-velocity 0f 1.5km/s, deliberately chosen tobe quite slow.

• velocity (bool) – Whether to make the pick in velocity space or not. Originaldefinition of local magnitude used displacement of Wood-Anderson, MLv in seiscompand Antelope uses a velocity measurement.

Returns Picked event

Return type obspy.core.event.Event

Note: Signal-to-noise ratio is calculated using the filtered data by dividing the maximum amplitude in thesignal window (pick window) by the normalized noise amplitude (taken from the whole window supplied).

Warning: Works in place on data - will filter and remove response from data, you are recommended togive this function a copy of the data if you are using it in a loop.

eqcorrscan.utils.mag_calc.calc_b_value

eqcorrscan.utils.mag_calc.calc_b_value(magnitudes, completeness, max_mag=None,plotvar=True)

Calculate the b-value for a range of completeness magnitudes.

Calculates a power-law fit to given magnitudes for each completeness magnitude. Plots the b-values andresiduals for the fitted catalogue against the completeness values. Computes fits using numpy.polyfit, whichuses a least-squares technique.

Parameters

• magnitudes (list) – Magnitudes to compute the b-value for.

• completeness (list) – list of completeness values to compute b-values for.

• max_mag (float) – Maximum magnitude to attempt to fit in magnitudes.

• plotvar (bool) – Turn plotting on or off.

Return type list

3.6. Utils 117
















Returns List of tuples of (completeness, b-value, residual, number of magnitudes used)

Example

>>> from obspy.clients.fdsn import Client>>> from obspy import UTCDateTime>>> from eqcorrscan.utils.mag_calc import calc_b_value>>> client = Client('IRIS')>>> t1 = UTCDateTime('2012-03-26T00:00:00')>>> t2 = t1 + (3 * 86400)>>> catalog = client.get_events(starttime=t1, endtime=t2, minmagnitude=3)>>> magnitudes = [event.magnitudes[0].mag for event in catalog]>>> b_values = calc_b_value(magnitudes, completeness=np.arange(3, 7, 0.2),... plotvar=False)>>> round(b_values[4][1])1.0>>> # We can set a maximum magnitude:>>> b_values = calc_b_value(magnitudes, completeness=np.arange(3, 7, 0.2),... plotvar=False, max_mag=5)>>> round(b_values[4][1])1.0

eqcorrscan.utils.mag_calc.calc_max_curv

eqcorrscan.utils.mag_calc.calc_max_curv(magnitudes, plotvar=False)Calculate the magnitude of completeness using the maximum curvature method.

Parameters

• magnitudes (list) – List of magnitudes from which to compute the maximumcurvature which will give an estimate of the magnitude of completeness given the as-sumption of a power-law scaling.

• plotvar (bool) – Turn plotting on and off

Return type float

Returns Magnitude at maximum curvature

Note: Should be used as a guide, often under-estimates Mc.

Example

>>> import numpy as np>>> mags = []>>> for mag in np.arange(2.5,3, 0.1):... mags.extend([mag] * int(20000 - 10 * mag))>>> for mag in np.arange(3,7, 0.1):... mags.extend([mag] * int(10 ** (7 - 1 * mag)))>>> calc_max_curv(mags, plotvar=False)3.0

eqcorrscan.utils.mag_calc.dist_calc

eqcorrscan.utils.mag_calc.dist_calc(loc1, loc2)Function to calculate the distance in km between two points.





Uses the flat Earth approximation. Better things are available for this, like gdal.

Parameters

• loc1 (tuple) – Tuple of lat, lon, depth (in decimal degrees and km)

• loc2 (tuple) – Tuple of lat, lon, depth (in decimal degrees and km)

Returns Distance between points in km.

Return type float

eqcorrscan.utils.mag_calc.svd_moments

eqcorrscan.utils.mag_calc.svd_moments(u, s, v, stachans, event_list, n_svs=2)Calculate relative moments/amplitudes using singular-value decomposition.

Convert basis vectors calculated by singular value decomposition (see the SVD functions in clustering) intorelative moments.

For more information see the paper by Rubinstein & Ellsworth (2010).

Parameters

• u (list) – List of the numpy.ndarray input basis vectors from the SVD, one arrayfor each channel used.

• s (list) – List of the numpy.ndarray of singular values, one array for each chan-nel.

• v (list) – List of numpy.ndarray of output basis vectors from SVD, one array perchannel.

• stachans (list) – List of station.channel input

• event_list (list) – List of events for which you have data, such that event_list[i]corresponds to stachans[i], U[i] etc. and event_list[i][j] corresponds to event j in U[i].These are a series of indexes that map the basis vectors to their relative events andchannels - if you have every channel for every event generating these is trivial (seeexample).

• n_svs (int) – Number of singular values to use, defaults to 4.

Returns M, array of relative moments


Returns events_out, list of events that relate to M (in order), does not include the magnitudeinformation in the events, see note.

Return type obspy.core.event.event.Event

Note: M is an array of relative moments (or amplitudes), these cannot be directly compared to true momentswithout calibration.

Note: When comparing this method with the method used for creation of subspace detectors (Harris 2006)it is important to note that the input design set matrix in Harris contains waveforms as columns, whereas inRubinstein & Ellsworth it contains waveforms as rows (i.e. the transpose of the Harris data matrix). The Uand V matrices are therefore swapped between the two approaches. This is accounted for in EQcorrscan butmay lead to confusion when reviewing the code. Here we use the Harris approach.

3.6. Utils 119

http://www.gdal.org/


http://www.bssaonline.org/content/100/5A/1952.short








Example

>>> from eqcorrscan.utils.mag_calc import svd_moments>>> from obspy import read>>> import glob>>> import os>>> from eqcorrscan.utils.clustering import svd>>> import numpy as np>>> # Do the set-up>>> testing_path = 'eqcorrscan/tests/test_data/similar_events'>>> stream_files = glob.glob(os.path.join(testing_path, '*'))>>> stream_list = [read(stream_file) for stream_file in stream_files]>>> event_list = []>>> remove_list = [('WHAT2', 'SH1'), ('WV04', 'SHZ'), ('GCSZ', 'EHZ')]>>> for i, stream in enumerate(stream_list):... st_list = []... for tr in stream:... if (tr.stats.station, tr.stats.channel) not in remove_list:... stream.remove(tr)... continue... tr.detrend('simple')... tr.filter('bandpass', freqmin=5.0, freqmax=15.0)... tr.trim(tr.stats.starttime + 40, tr.stats.endtime - 45)... st_list.append(i)... event_list.append(st_list)>>> event_list = np.asarray(event_list).T.tolist()>>> SVec, SVal, U, stachans = svd(stream_list=stream_list)['GCSZ.EHZ', 'WV04.SHZ', 'WHAT2.SH1']>>> M, events_out = svd_moments(u=U, s=SVal, v=SVec, stachans=stachans,... event_list=event_list)

Private Functions


_sim_WA Remove the instrument response from a trace and sim-ulate a Wood-Anderson.

_pairwise Wrapper on itertools for SVD_magnitude._max_p2t Finds the maximum peak-to-trough amplitude and pe-

riod._find_resp Helper function to find the response information._GSE2_PAZ_read Read the instrument response information from a GSE

Poles and Zeros file.

eqcorrscan.utils.mag_calc._sim_WA

eqcorrscan.utils.mag_calc._sim_WA(trace, PAZ, seedresp, water_level, velocity=False)Remove the instrument response from a trace and simulate a Wood-Anderson.

Returns a de-meaned, de-trended, Wood Anderson simulated trace in its place.

Works in-place on data and will destroy your original data, copy the trace before giving it to this function!

Parameters

• trace (obspy.core.trace.Trace) – A standard obspy trace, generally shouldbe given without pre-filtering, if given with pre-filtering for use with amplitude deter-mination for magnitudes you will need to worry about how you cope with the responseof this filter yourself.




• PAZ (dict) – Dictionary containing lists of poles and zeros, the gain and the sensitivity.If unset will expect seedresp.

• seedresp (dict) – Seed response information - if unset will expect PAZ.

• water_level (int) – Water level for the simulation.

• velocity (bool) – Whether to return a velocity trace or not - velocity is non-standardfor Wood-Anderson instruments, but institutes that use seiscomp3 or Antelope requirepicks in velocity.

Returns Trace of Wood-Anderson simulated data


eqcorrscan.utils.mag_calc._pairwise

eqcorrscan.utils.mag_calc._pairwise(iterable)Wrapper on itertools for SVD_magnitude.

eqcorrscan.utils.mag_calc._max_p2t

eqcorrscan.utils.mag_calc._max_p2t(data, delta)Finds the maximum peak-to-trough amplitude and period. Originally designed to be used to calculatemagnitudes (by taking half of the peak-to-trough amplitude as the peak amplitude).

Parameters

• data (numpy.ndarray) – waveform trace to find the peak-to-trough in.

• delta (float) – Sampling interval in seconds

Returns tuple of (amplitude, period, time) with amplitude in the same scale as given in the inputdata, and period in seconds, and time in seconds from the start of the data window.

Return type tuple

eqcorrscan.utils.mag_calc._find_resp

eqcorrscan.utils.mag_calc._find_resp(station, channel, network, time, delta, directory)Helper function to find the response information.

Works for a given station and channel at a given time and return a dictionary of poles and zeros, gain andsensitivity.

Parameters

• station (str) – Station name (as in the response files)

• channel (str) – Channel name (as in the response files)

• network (str) – Network to scan for, can be a wildcard

• time (datetime.datetime) – Date-time to look for repsonse information

• delta (float) – Sample interval in seconds

• directory (str) – Directory to scan for response information

Returns dictionary of response information

Return type dict

3.6. Utils 121











https://docs.python.org/2.7/library/datetime.html#datetime.datetime





eqcorrscan.utils.mag_calc._GSE2_PAZ_read

eqcorrscan.utils.mag_calc._GSE2_PAZ_read(gsefile)Read the instrument response information from a GSE Poles and Zeros file.

Formatted for files generated by the SEISAN program RESP.

Format must be CAL2, not coded for any other format at the moment, contact the authors to add others in.

Parameters gsefile (string) – Path to GSE file

Returns Dictionary of poles, zeros, gain and sensitivity

Return type dict

3.6.9 parameters

Default parameters for eqcorrscan, only used if the quickstart options are run.



Classes

parameters.EQcorrscanParameters

class eqcorrscan.utils.parameters.EQcorrscanParameters(template_names, low-cut, highcut, filt_order,samp_rate, debug, start-date, enddate, archive,arc_type, cores, plotvar,plotdir, plot_format,tempdir, threshold,threshold_type, trig-ger_interval)

Bases: object

Standard class for defining parameters in EQcorrscan.

These parameters are set using the quickstart script of EQcorrscan for matched-filter analysis. The quickstartfunctionality is currently in development.

Parameters

• template_names (list) – List of str of template names.

• lowcut (float) – Low-cut iun Hz

• highcut (float) – High-cut in Hz

• filt_order (int) – Number of corners in filter

• samp_rate (float) – Desired sampling rate in Hz

• debug (int) – 0-5 debug level, higher number is more output

• startdate (obspy.core.utcdatetime.UTCDateTime) – Start date formatch-filter analysis.

• enddate (obspy.core.utcdatetime.UTCDateTime) – End date formatched-filter analysis

• archive (str) – Path to archive, or FDSN name














• arc_type (str) – Type of archive (see eqcorrscan.utils.archive_read() for available options.

• cores (int) – Number of cores to parallel over

• plotvar (bool) – Whether to show plots or not

• plotdir (str) – Output plot location

• plot_format (str) – Output plot type

• tempdir (str) – Location of temporary files (if needed)

• threshold (float) – Threshold for matched-filter detection

• threshold_type (str) – Threshold type for matched-filter detection, seeeqcorrscan.core.match_filter.match_filter() for available types.

• trigger_interval (float) – Minimum trigger interval in seconds.

Methods

write([outfile, overwrite]) Function to write the parameters to a file - userreadable.

__init__(template_names, lowcut, highcut, filt_order, samp_rate, debug, startdate, enddate,archive, arc_type, cores, plotvar, plotdir, plot_format, tempdir, threshold, thresh-old_type, trigger_interval)

Standard parameter options.

write(outfile=’../parameters/EQcorrscan_parameters.txt’, overwrite=False)Function to write the parameters to a file - user readable.

Parameters

• outfile (str) – Full path to filename to store parameters in.

• overwrite (bool) – Whether to overwrite the old file or not.

Functions

read_parameters Read the default parameters from file.

eqcorrscan.utils.parameters.read_parameters

eqcorrscan.utils.parameters.read_parameters(infile=’../parameters/EQcorrscan_parameters.txt’)Read the default parameters from file.

Parameters infile (str) – Full path to parameter file.

Returns parameters read from file.

Return type eqcorrscan.utils.parameters.EQcorrscanParameters

3.6.10 picker

Functions to pick earthquakes detected by EQcorrscan.

Designed primarily locate stacks of detections to give family locations. Extensions may later be written, not testedfor accuracy, just simple wrappers.


3.6. Utils 123















Classes & Functions

cross_net Generate picks using a simple envelope cross-correlation.

stalta_pick Basic sta/lta picker, suggest using alternative in obspy.

eqcorrscan.utils.picker.cross_net

eqcorrscan.utils.picker.cross_net(stream, env=False, debug=0, master=False)Generate picks using a simple envelope cross-correlation.

Picks are made for each channel based on optimal moveout defined by maximum cross-correlation withmaster trace. Master trace will be the first trace in the stream if not set. Requires good inter-station coher-ance.

Parameters

• stream (obspy.core.stream.Stream) – Stream to pick

• env (bool) – To compute cross-correlations on the envelope or not.

• debug (int) – Debug level from 0-5

• master (obspy.core.trace.Trace) – Trace to use as master, if False, will usethe first trace in stream.

Returns obspy.core.event.event.Event

Example

>>> from obspy import read>>> from eqcorrscan.utils.picker import cross_net>>> st = read()>>> event = cross_net(st, env=True)>>> print(event.creation_info.author)EQcorrscan

Warning: This routine is not designed for accurate picking, rather it can be used for a first-pass at picksto obtain simple locations. Based on the waveform-envelope cross-correlation method.

eqcorrscan.utils.picker.stalta_pick

eqcorrscan.utils.picker.stalta_pick(stream, stalen, ltalen, trig_on, trig_off,freqmin=False, freqmax=False, debug=0,show=False)

Basic sta/lta picker, suggest using alternative in obspy.

Simple sta/lta (short-term average/long-term average) picker, using obspy’s obspy.signal.trigger.classic_sta_lta() routine to generate the characteristic function.

Currently very basic quick wrapper, there are many other (better) options in obspy in the obspy.signal.trigger module.

Parameters








https://docs.obspy.org/packages/autogen/obspy.signal.trigger.classic_sta_lta.html#obspy.signal.trigger.classic_sta_lta

https://docs.obspy.org/packages/autogen/obspy.signal.trigger.classic_sta_lta.html#obspy.signal.trigger.classic_sta_lta

https://docs.obspy.org/packages/autogen/obspy.signal.trigger.html#module-obspy.signal.trigger

https://docs.obspy.org/packages/autogen/obspy.signal.trigger.html#module-obspy.signal.trigger


• stream (obspy.core.stream.Stream) – The stream to pick on, can be anynumber of channels.

• stalen (float) – Length of the short-term average window in seconds.

• ltalen (float) – Length of the long-term average window in seconds.

• trig_on (float) – sta/lta ratio to trigger a detection/pick

• trig_off (float) – sta/lta ratio to turn the trigger off - no further picks will be madebetween exceeding trig_on until trig_off is reached.

• freqmin (float) – Low-cut frequency in Hz for bandpass filter

• freqmax (float) – High-cut frequency in Hz for bandpass filter


• show (bool) – Show picks on waveform.

Returns obspy.core.event.event.Event

Example

>>> from obspy import read>>> from eqcorrscan.utils.picker import stalta_pick>>> st = read()>>> event = stalta_pick(st, stalen=0.2, ltalen=4, trig_on=10,... trig_off=1, freqmin=3.0, freqmax=20.0)>>> print(event.creation_info.author)EQcorrscan

Warning: This function is not designed for accurate picking, rather it can give a first idea of whetherpicks may be possible. Proceed with caution.

3.6.11 plotting

Utility code for most of the plots used as part of the EQcorrscan package.



Classes & Functions

chunk_data Downsample data for plotting.cumulative_detections Plot cumulative detections or detecton rate in time.detection_multiplot Plot a stream of data with a template on top of it at

detection times.freq_mag Plot a frequency-magnitude histogram and cumula-

tive density plot.interev_mag Plot inter-event times against magnitude.multi_event_singlechan Plot data from a single channel for multiple events.NR_plot Plot Network response alongside the stream used.obspy_3d_plot Plot obspy Inventory and obspy Catalog classes in

three dimensions.Continued on next page

3.6. Utils 125













Table 28 – continued from previous pagepeaks_plot Plot peaks to check that the peak finding routine is

running correctly.plot_repicked Plot a template over a detected stream, with picks cor-

rected by lag-calc.plot_synth_real Plot multiple channels of data for real data and syn-

thetic.pretty_template_plot Plot of a single template, possibly within background

data.spec_trace Plots seismic data with spectrogram behind.subspace_detector_plot Plotting for the subspace detector class.SVD_plot Plot singular vectors from the eqcorrscan.

utils.clustering routines.threeD_gridplot Plot in a series of grid points in 3D.threeD_seismplot Plot seismicity and stations in a 3D, movable,

zoomable space.triple_plot Plot a seismogram, correlogram and histogram.xcorr_plot Plot a template overlying an image aligned by corre-

lation.

eqcorrscan.utils.plotting.chunk_data

eqcorrscan.utils.plotting.chunk_data(tr, samp_rate, state=’mean’)Downsample data for plotting.

Computes the maximum of data within chunks, useful for plotting waveforms or cccsums, large datasetsthat would otherwise exceed the complexity allowed, and overflow.

Parameters

• tr (obspy.core.trace.Trace) – Trace to be chunked

• samp_rate (float) – Desired sampling rate in Hz

• state (str) – Either ‘Min’, ‘Max’, ‘Mean’ or ‘Maxabs’ to return one of these for thechunks. Maxabs will return the largest (positive or negative) for that chunk.

Returns obspy.core.trace.Trace

eqcorrscan.utils.plotting.cumulative_detections

eqcorrscan.utils.plotting.cumulative_detections(dates=None, tem-plate_names=None, detec-tions=None, plot_grouped=False,group_name=None, rate=False,show=True, plot_legend=True,ax=None, save=False, save-file=None)

Plot cumulative detections or detecton rate in time.

Simple plotting function to take a list of either datetime objects or eqcorrscan.core.match_filter.Detection objects and plot a cumulative detections list. Can take dates as a list oflists and will plot each list separately, e.g. if you have dates from more than one template it will overlaythem in different colours.

Parameters

• dates (list) – Must be a list of lists of datetime.datetime objects

• template_names (list) – List of the template names in order of the dates







• detections (list) – List of eqcorrscan.core.match_filter.Detection

• plot_grouped (bool) – Plot detections for each template individually, or groupthem all together - set to False (plot template detections individually) by default.

• rate (bool) – Whether or not to plot the rate of detection per day. Only works forplot_grouped=True

• show (bool) – Whether or not to show the plot, defaults to True.

• plot_legend (bool) – Specify whether to plot legend of template names. Defaultsto True.

• save (bool) – Save figure or show to screen, optional

• savefile (str) – String to save to, required is save=True

Returns matplotlib.figure.Figure

Note: Can either take lists of eqcorrscan.core.match_filter.Detection objects directly, ortwo lists of dates and template names - either/or, not both.

Example

>>> import datetime as dt>>> import numpy as np>>> from eqcorrscan.utils.plotting import cumulative_detections>>> dates = []>>> for i in range(3):... dates.append([dt.datetime(2012, 3, 26) + dt.timedelta(n)... for n in np.random.randn(100)])>>> cumulative_detections(dates, ['a', 'b', 'c'],... show=True)

3.6. Utils 127







https://matplotlib.org/api/_as_gen/matplotlib.figure.Figure.html#matplotlib.figure.Figure


2012/03/232012/03/24

2012/03/252012/03/26

2012/03/272012/03/28

2012/03/29

Date

0

20

40

60

80

100

Cum

ula

tive d

ete

ctio

ns

a

b

c

Example 2: Rate plotting

>>> import datetime as dt>>> import numpy as np>>> from eqcorrscan.utils.plotting import cumulative_detections>>> dates = []>>> for i in range(3):... dates.append([dt.datetime(2012, 3, 26) + dt.timedelta(n)... for n in np.random.randn(100)])>>> cumulative_detections(dates, ['a', 'b', 'c'], plot_grouped=True,... rate=True, show=True)



2012/03/242012/03/25

2012/03/262012/03/27

2012/03/282012/03/29

Date

0

5

10

15

20

25

30

35D

ete

ctio

ns

per

6 h

our

bin

Rate of detections

eqcorrscan.utils.plotting.detection_multiplot

eqcorrscan.utils.plotting.detection_multiplot(stream, template, times, stream-colour=’k’, templatecolour=’r’,save=False, savefile=None,size=(10.5, 7.5), title=None)

Plot a stream of data with a template on top of it at detection times.

Parameters

• stream (obspy.core.stream.Stream) – Stream of data to be plotted as thebackground.

• template (obspy.core.stream.Stream) – Template to be plotted on top ofthe base stream.

• times (list) – list of detection times, one for each event

• streamcolour (str) – String of matplotlib colour types for the stream

• templatecolour (str) – Colour to plot the template in.

• save (bool) – False will plot to screen, true will save plot and not show to screen.

• savefile (str) – Filename to save to, required for save=True


• title (str) – Title for plot.


3.6. Utils 129










Example

>>> from obspy import read, read_events>>> import os>>> from eqcorrscan.core import template_gen>>> from eqcorrscan.utils.plotting import detection_multiplot>>>>>> test_file = os.path.join('eqcorrscan', 'tests', 'test_data', 'REA',... 'TEST_', '01-0411-15L.S201309')>>> test_wavefile = os.path.join(... 'eqcorrscan', 'tests', 'test_data', 'WAV', 'TEST_',... '2013-09-01-0410-35.DFDPC_024_00')>>> event = read_events(test_file)[0]>>> st = read(test_wavefile)>>> st = st.filter('bandpass', freqmin=2.0, freqmax=15.0)>>> for tr in st:... tr = tr.trim(tr.stats.starttime + 30, tr.stats.endtime - 30)... # Hack around seisan 2-letter channel naming... tr.stats.channel = tr.stats.channel[0] + tr.stats.channel[-1]>>> template = template_gen._template_gen(event.picks, st, 2)>>> times = [min([pk.time -0.05 for pk in event.picks])]>>> detection_multiplot(stream=st, template=template,... times=times)

1.00.50.00.51.0

WV03.SZ

1.51.00.50.00.51.0WZ11.HZ

1.51.00.50.00.51.0WHYM.SZ

0.80.60.40.20.00.20.40.60.81.0GCSZ.EZ

0.80.60.40.20.00.20.40.60.81.0WZ02.EN

1.00.50.00.51.0

EORO.SZ

1.51.00.50.00.51.0WHYM.SN

1.51.00.50.00.51.0WZ11.HZ

1.51.00.50.00.51.0WHYM.SZ

1.00.50.00.51.0

WV03.SZ

0.80.60.40.20.00.20.40.60.81.0WZ02.EZ

1.00.50.00.51.0

EORO.SZ

1.00.50.00.51.0

EORO.SN

1.00.50.00.51.0

LABE.SN

04:11:10.00000004:11:15.000000

04:11:20.00000004:11:25.000000

04:11:30.00000004:11:35.000000

Time

1.51.00.50.00.51.0LABE.SZ

eqcorrscan.utils.plotting.freq_mag

eqcorrscan.utils.plotting.freq_mag(magnitudes, completeness, max_mag, binsize=0.2,save=False, savefile=None)

Plot a frequency-magnitude histogram and cumulative density plot.

Currently this will compute a b-value, for a goiven completeness. B-value is computed by linear fitting tosection of curve between completeness and max_mag.



Parameters

• magnitudes (list) – list of float of magnitudes

• completeness (float) – Level to compute the b-value above

• max_mag (float) – Maximum magnitude to try and fit a b-value to

• binsize (float) – Width of histogram bins, defaults to 0.2




Note: See eqcorrscan.utils.mag_calc.calc_b_value() for a least-squares method of es-timating completeness and b-value. For estimating maximum curvature see eqcorrscan.utils.mag_calc.calc_max_curv().

Example

>>> from obspy.clients.fdsn import Client>>> from obspy import UTCDateTime>>> from eqcorrscan.utils.plotting import freq_mag>>> client = Client('IRIS')>>> t1 = UTCDateTime('2012-03-26T00:00:00')>>> t2 = t1 + (3 * 86400)>>> catalog = client.get_events(starttime=t1, endtime=t2, minmagnitude=3)>>> magnitudes = [event.preferred_magnitude().mag for event in catalog]>>> freq_mag(magnitudes, completeness=4, max_mag=7)

3.0 3.5 4.0 4.5 5.0 5.5 6.0Magnitude

0

20

40

60

80

100

120

140

160

Frequency

0.0

0.5

1.0

1.5

2.0

2.5

3.0

3.5

Log

10 o

f cu

mula

tive d

ensi

ty

GR trend, b-value = 1.00 MC = 4

Magnitude cumulative density

3.6. Utils 131








eqcorrscan.utils.plotting.interev_mag

eqcorrscan.utils.plotting.interev_mag(times, mags, save=False, savefile=None,size=(10.5, 7.5))

Plot inter-event times against magnitude.

Parameters

• times (list) – list of the detection times, must be sorted the same as mags

• mags (list) – list of magnitudes



• size (tuple) – Size of figure in inches.


Example

>>> from obspy.clients.fdsn import Client>>> from obspy import UTCDateTime>>> from eqcorrscan.utils.plotting import interev_mag>>> client = Client('IRIS')>>> t1 = UTCDateTime('2012-03-26T00:00:00')>>> t2 = t1 + (3 * 86400)>>> catalog = client.get_events(starttime=t1, endtime=t2, minmagnitude=3)>>> magnitudes = [event.preferred_magnitude().mag for event in catalog]>>> times = [event.preferred_origin().time for event in catalog]>>> interev_mag(times, magnitudes)

5 0 5 10 15 20 25 30 35 40

Time (Minutes)

2.5

3.0

3.5

4.0

4.5

5.0

5.5

6.0

6.5

Magnit

ude

Pre-event times

5 0 5 10 15 20 25 30 35 40

Time (Minutes)

Post-event times






eqcorrscan.utils.plotting.multi_event_singlechan

eqcorrscan.utils.plotting.multi_event_singlechan(streams, catalog, station, chan-nel, clip=10.0, pre_pick=2.0,freqmin=False, freqmax=False,realign=False, cut=(-3.0,5.0), PWS=False, title=False,save=False, savefile=None)

Plot data from a single channel for multiple events.

Data will be aligned by their pick-time given in the appropriate picks. Requires an individual stream foreach event you want to plot, events are stored in the obspy.core.event.Catalog object, and theremust be picks present for the streams you wish to plot. Events will be aligned if realign=True, in this casethe traces will be aligned using the window defined by cut.

Parameters

• streams (list) – List of the obspy.core.stream.Stream objects to use, cancontain more traces than you plan on plotting (e.g. from more channels) - must be inthe same order as events in catalog.

• catalog (obspy.core.event.Catalog) – Catalog of events, one for eachstream.

• station (str) – Station to plot.

• channel (str) – Channel to plot.

• clip (float) – Length in seconds to plot, defaults to 10.0

• pre_pick (float) – Length in seconds to extract and plot before the pick, defaultsto 2.0

• freqmin (float) – Low cut for bandpass in Hz

• freqmax (float) – High cut for bandpass in Hz

• realign (bool) – To compute best alignment based on correlation with the stack ornot.

• cut (tuple) – tuple of start and end times for cut in seconds from the pick, used foralignment. Will only use this window to align the traces.

• PWS (bool) – compute Phase Weighted Stack, if False, will compute linear stack foralignment.

• title (str) – Plot title.



Returns Aligned and cut obspy.core.trace.Trace

Return type list

Returns New picks in based on alignment (if alignment is performed, if not will return the sameas input)


Returns Figure object for further editing

Return type matplotlib.figure.Figure

3.6. Utils 133



















Example

>>> from obspy import read, Catalog, read_events>>> from obspy.io.nordic.core import readwavename>>> from eqcorrscan.utils.plotting import multi_event_singlechan>>> import glob>>> sfiles = glob.glob('eqcorrscan/tests/test_data/REA/TEST_/*.S??????')>>> catalog = Catalog()>>> streams = []>>> for sfile in sfiles:... catalog += read_events(sfile)... wavfile = readwavename(sfile)[0]... stream_path = 'eqcorrscan/tests/test_data/WAV/TEST_/' + wavfile... stream = read(stream_path)... # Annoying coping with seisan 2 letter channels... for tr in stream:... tr.stats.channel = tr.stats.channel[0] + tr.stats.channel[-1]... streams.append(stream)>>> multi_event_singlechan(streams=streams, catalog=catalog,... station='GCSZ', channel='EZ')



3.6. Utils 135


eqcorrscan.utils.plotting.NR_plot

eqcorrscan.utils.plotting.NR_plot(stream, NR_stream, detections, false_detections=False,size=(18.5, 10), save=False, savefile=None, ti-tle=False)

Plot Network response alongside the stream used.

Highlights detection times in the network response.

Parameters

• stream (obspy.core.stream.Stream) – Stream to plot

• NR_stream (obspy.core.stream.Stream) – Stream for the network response

• detections (list) – List of the detection time as datetime.datetime

• false_detections (list) – Either False (default) or list of false detection times(datetime.datetime).

• size (tuple) – Size of figure, default is (18.5, 10)

• save (bool) – Save figure or plot to screen, if not False, must be string of save path.

• title (str) – String for the title of the plot, set to False


Note: Called by eqcorrscan.core.bright_lights, not a general use plot (hence no example)

eqcorrscan.utils.plotting.obspy_3d_plot

eqcorrscan.utils.plotting.obspy_3d_plot(inventory, catalog, save=False, savefile=None,size=(10.5, 7.5))

Plot obspy Inventory and obspy Catalog classes in three dimensions.

Parameters

• inventory (obspy.core.inventory.inventory.Inventory) – Obspyinventory class containing station metadata

• catalog (obspy.core.event.catalog.Catalog) – Obspy catalog classcontaining event metadata





Example:

>>> from obspy.clients.fdsn import Client>>> from obspy import UTCDateTime>>> from eqcorrscan.utils.plotting import obspy_3d_plot>>> client = Client('IRIS')>>> t1 = UTCDateTime(2012, 3, 26)>>> t2 = t1 + 86400>>> catalog = client.get_events(starttime=t1, endtime=t2, latitude=-43,... longitude=170, maxradius=5)>>> inventory = client.get_stations(starttime=t1, endtime=t2, latitude=-43,










https://docs.obspy.org/packages/autogen/obspy.core.inventory.inventory.Inventory.html#obspy.core.inventory.inventory.Inventory

https://docs.obspy.org/packages/autogen/obspy.core.event.catalog.Catalog.html#obspy.core.event.catalog.Catalog






... longitude=170, maxradius=10)>>> obspy_3d_plot(inventory=inventory, catalog=catalog)

Latitude (deg)

4644

4240

3836

34

Longitu

de (deg)

165

170

175

180

185

Ele

vati

on (

km)

25

20

15

10

5

0

5

HypocentersStations

eqcorrscan.utils.plotting.peaks_plot

eqcorrscan.utils.plotting.peaks_plot(data, starttime, samp_rate, save=False, peaks=[(0,0)], savefile=None)

Plot peaks to check that the peak finding routine is running correctly.

Used in debugging for the EQcorrscan module.

Parameters

• data (numpy.array) – Numpy array of the data within which peaks have beenfound

• starttime (obspy.core.utcdatetime.UTCDateTime) – Start time for thedata

• samp_rate (float) – Sampling rate of data in Hz

• save (bool) – Save figure or plot to screen.

• peaks (list) – List of tuples of peak locations and amplitudes (loc, amp)

• savefile (str) – Path to save to, only used if save=True


Example

3.6. Utils 137







>>> import numpy as np>>> from eqcorrscan.utils import findpeaks>>> from eqcorrscan.utils.plotting import peaks_plot>>> from obspy import UTCDateTime>>> data = np.random.randn(200)>>> data[30]=100>>> data[60]=40>>> threshold = 10>>> peaks = findpeaks.find_peaks2_short(data, threshold, 3)>>> peaks_plot(data=data, starttime=UTCDateTime("2008001"),... samp_rate=10, peaks=peaks)

eqcorrscan.utils.plotting.plot_repicked

eqcorrscan.utils.plotting.plot_repicked(template, picks, det_stream, size=(10.5, 7.5),save=False, savefile=None, title=False)

Plot a template over a detected stream, with picks corrected by lag-calc.

Parameters

• template (obspy.core.stream.Stream) – Template used to make the detec-tion, will be aligned according to picks.

• picks (list) – list of corrected picks, each pick must be an obspy.core.event.origin.Pick object.

• det_stream (obspy.core.stream.Stream) – Stream to plot in the back-ground, should be the detection, data should encompass the time the picks are made.

• size (tuple) – Plot size.

• save (bool) – To save figure or not, if false, will show to screen.

• savefile (str) – File name to save file, required if save==True.

• title (str) – Title for plot, defaults to None.

Returns Figure handle which can be edited.

Return type matplotlib.figure.Figure



https://docs.obspy.org/packages/autogen/obspy.core.event.origin.Pick.html#obspy.core.event.origin.Pick








eqcorrscan.utils.plotting.plot_synth_real

eqcorrscan.utils.plotting.plot_synth_real(real_template, synthetic, channels=False,size=(5, 10), save=False, savefile=None)

Plot multiple channels of data for real data and synthetic.

Parameters

• real_template (obspy.core.stream.Stream) – Stream of the real template

• synthetic (obspy.core.stream.Stream) – Stream of synthetic template

• channels (list) – List of tuples of (station, channel) to plot, default is False, whichplots all.

• size (tuple) – Plot size.




>>> from obspy import read, Stream, Trace>>> from eqcorrscan.utils.synth_seis import seis_sim>>> from eqcorrscan.utils.plotting import plot_synth_real>>> real = read()>>> synth = Stream(Trace(seis_sim(sp=100, flength=200)))>>> synth[0].stats.station = 'RJOB'>>> synth[0].stats.channel = 'EHZ'>>> synth[0].stats.sampling_rate = 100>>> synth = synth.filter('bandpass', freqmin=2, freqmax=8)>>> real = real.select(station='RJOB',... channel='EHZ').detrend('simple').filter('bandpass',... freqmin=2,


3.6. Utils 139








... freqmax=8)>>> real = real.trim(starttime=real[0].stats.starttime + 43,... endtime=real[0].stats.starttime +... 45).detrend('simple')>>> plot_synth_real(real_template=real, synthetic=synth,... size=(7, 4))

0.0 0.5 1.0 1.5 2.0 2.5Time (s)

RJOB.EHZ cc=0.13

eqcorrscan.utils.plotting.pretty_template_plot

eqcorrscan.utils.plotting.pretty_template_plot(template, size=(10.5, 7.5),save=False, savefile=None, ti-tle=False, background=False,picks=False)

Plot of a single template, possibly within background data.

Parameters

• template (obspy.core.stream.Stream) – Template stream to plot

• size (tuple) – tuple of plot size

• save (bool) – if False will plot to screen, if True will save

• savefile (str) – String to save plot as, required if save=True.

• title (bool) – String if set will be the plot title

• background (obspy.core.stream.stream) – Stream to plot the templatewithin.

• picks (list) – List of obspy.core.event.origin.Pick picks.


Example









>>> from obspy import read, read_events>>> import os>>> from eqcorrscan.core import template_gen>>> from eqcorrscan.utils.plotting import pretty_template_plot>>>>>> test_file = os.path.join('eqcorrscan', 'tests', 'test_data', 'REA',... 'TEST_', '01-0411-15L.S201309')>>> test_wavefile = os.path.join(... 'eqcorrscan', 'tests', 'test_data', 'WAV', 'TEST_',... '2013-09-01-0410-35.DFDPC_024_00')>>> event = read_events(test_file)[0]>>> st = read(test_wavefile)>>> st = st.filter('bandpass', freqmin=2.0, freqmax=15.0)>>> for tr in st:... tr = tr.trim(tr.stats.starttime + 30, tr.stats.endtime - 30)... # Hack around seisan 2-letter channel naming... tr.stats.channel = tr.stats.channel[0] + tr.stats.channel[-1]>>> template = template_gen._template_gen(event.picks, st, 2)>>> pretty_template_plot(template, background=st, # doctest +SKIP... picks=event.picks)

EORO.SZ

EORO.SZ

EORO.SN

LABE.SN

LABE.SZ

WHYM.SZ

WHYM.SN

WHYM.SZ

WV03.SZ

WV03.SZ

GCSZ.EZ

WZ02.EN

WZ02.EZ

WZ11.HZ

0 5 10 15 20 25 30Time (s) from start of template

WZ11.HZ

TemplateP-pickUnknown pickS-pick

eqcorrscan.utils.plotting.spec_trace

eqcorrscan.utils.plotting.spec_trace(traces, cmap=None, wlen=0.4, log=False, trc=’k’,tralpha=0.9, size=(10, 13), fig=None, title=None,show=True)

Plots seismic data with spectrogram behind.

Takes a stream or list of traces and plots the trace with the spectra beneath it.

Parameters

• traces (list) – Traces to be plotted, can be a single obspy.core.stream.

3.6. Utils 141




Stream, or a list of obspy.core.trace.Trace.

• cmap (str) – Matplotlib colormap.

• wlen (float) – Window length for fft in seconds

• log (bool) – Use a log frequency scale

• trc (str) – Color for the trace.

• tralpha (float) – Opacity level for the seismogram, from transparent (0.0) toopaque (1.0).

• size (tuple) – Plot size, tuple of floats, inches

• fig (matplotlib.figure.Figure) – Figure to plot onto, defaults to self gener-ating.

• title (str) – Title of plot.

• show (bool) – To show plot or not, if false, will return Fig.


Example

>>> from obspy import read>>> from eqcorrscan.utils.plotting import spec_trace>>> st = read()>>> spec_trace(st, trc='white')






http://matplotlib.org/examples/color/colormaps_reference.html










RJOB.EHE

1308.3 3000

2000

1000

0

1000

2000

RJOB.EHN

2297.42000

1000

0

1000

2000

3000

4000

0 5 10 15 20 25 30Time (s)

RJOB.EHZ

1293.8 3000

2000

1000

0

1000

2000

Frequency

(H

z)

eqcorrscan.utils.plotting.subspace_detector_plot

eqcorrscan.utils.plotting.subspace_detector_plot(detector, stachans, size, show)Plotting for the subspace detector class.

Plot the output basis vectors for the detector at the given dimension.

Corresponds to the first n horizontal vectors of the V matrix.

Parameters

• stachans (list) – list of tuples of station, channel pairs to plot.

3.6. Utils 143


• stachans – List of tuples of (station, channel) to use. Can set to ‘all’ to use all thestation-channel pairs available. If detector is multiplexed, will just plot that.


• show (bool) – Whether or not to show the figure.

Returns Figure

Return type matplotlib.pyplot.Figure

Example

>>> from eqcorrscan.core import subspace>>> import os>>> detector = subspace.Detector()>>> detector.read(os.path.join(os.path.abspath(os.path.dirname(__file__)),... '..', 'tests', 'test_data', 'subspace',... 'stat_test_detector.h5'))Detector: Tester>>> subspace_detector_plot(detector=detector, stachans='all', size=(10, 7),... show=True)

0.40.30.20.10.00.10.20.30.4

Basi

s 1 TMWZ.EHE TMWZ.EHN TMWZ.EHZ

0.40.30.20.10.00.10.20.30.4

Basi

s 2

0.40.30.20.10.00.10.20.30.4

Basi

s 3

0.40.30.20.10.00.10.20.30.4

Basi

s 4

0.40.30.20.10.00.10.20.30.4

Basi

s 5

0.40.30.20.10.00.10.20.30.4

Basi

s 6

0.40.30.20.10.00.10.20.30.4

Basi

s 7

0.40.30.20.10.00.10.20.30.4

Basi

s 8

0.40.30.20.10.00.10.20.30.4

Basi

s 9

0.40.30.20.10.00.10.20.30.4

Basi

s 10

0.40.30.20.10.00.10.20.30.4

Basi

s 11

0.40.30.20.10.00.10.20.30.4

Basi

s 12

0 2 4 6 8 10 12 14 16Time (s)

0.40.30.20.10.00.10.20.30.4

Basi

s 13

0 2 4 6 8 10 12 14 16Time (s)

0 2 4 6 8 10 12 14 16Time (s)

eqcorrscan.utils.plotting.SVD_plot

eqcorrscan.utils.plotting.SVD_plot(SVStreams, SValues, stachans, title=False,save=False, savefile=None)

Plot singular vectors from the eqcorrscan.utils.clustering routines.

One plot for each channel.

Parameters




• SVStreams (list) – See eqcorrscan.utils.clustering.SVD_2_stream() - these should be ordered by power, e.g. first singular vector inthe first stream.

• SValues (list) – List of floats of the singular values corresponding to the SVStreams

• stachans (list) – List of station.channel


• savefile (str) – Filename to save to, required for save=True, will label additionallyaccording to station and channel.


Example

>>> from obspy import read>>> import glob>>> from eqcorrscan.utils.plotting import SVD_plot>>> from eqcorrscan.utils.clustering import svd, svd_to_stream>>> wavefiles = glob.glob('eqcorrscan/tests/test_data/WAV/TEST_/*')>>> streams = [read(w) for w in wavefiles[1:10]]>>> stream_list = []>>> for st in streams:... tr = st.select(station='GCSZ', channel='EHZ')... tr = tr.detrend('simple').resample(100).filter('bandpass',... freqmin=2,... freqmax=8)... stream_list.append(tr)>>> uvec, sval, svec, stachans = svd(stream_list=stream_list)>>> SVstreams = svd_to_stream(uvectors=uvec, stachans=stachans, k=3,... sampling_rate=100)>>> SVD_plot(SVStreams=SVstreams, SValues=sval,... stachans=stachans)

3.6. Utils 145





SV 1 = 995.23

('GCSZ', 'EHZ')

SV 2 = 366.21

0.00 0.01 0.02 0.03 0.04 0.05 0.06 0.07 0.08 0.09Time (s)

SV 3 = 327.68

eqcorrscan.utils.plotting.threeD_gridplot

eqcorrscan.utils.plotting.threeD_gridplot(nodes, save=False, savefile=None)Plot in a series of grid points in 3D.

Parameters

• nodes (list) – List of tuples of the form (lat, long, depth)

• save (bool) – if True will save without plotting to screen, if False (default) will plotto screen but not save

• savefile (str) – required if save=True, path to save figure to.


Example

>>> from eqcorrscan.utils.plotting import threeD_gridplot>>> nodes = [(-43.5, 170.4, 4), (-43.3, 170.8, 12), (-43.4, 170.3, 8)]>>> threeD_gridplot(nodes=nodes)






Longitude (deg)

43.5543.50

43.4543.40

43.3543.30 La

titude (d

eg)+1.7

01e2

0.10.2

0.30.4

0.50.6

0.70.8

Depth

(km

)

4

6

8

10

12

eqcorrscan.utils.plotting.threeD_seismplot

eqcorrscan.utils.plotting.threeD_seismplot(stations, nodes, save=False, save-file=None, size=(10.5, 7.5))

Plot seismicity and stations in a 3D, movable, zoomable space.

Uses matplotlibs Axes3D package.

Parameters

• stations (list) – list of one tuple per station of (lat, long, elevation), with uppositive.

• nodes (list) – list of one tuple per event of (lat, long, depth) with down positive.





Note: See eqcorrscan.utils.plotting.obspy_3d_plot() for example output.

eqcorrscan.utils.plotting.triple_plot

eqcorrscan.utils.plotting.triple_plot(cccsum, cccsum_hist, trace, threshold,save=False, savefile=None)

Plot a seismogram, correlogram and histogram.

Parameters

3.6. Utils 147





• cccsum (numpy.ndarray) – Array of the cross-channel cross-correlation sum

• cccsum_hist (numpy.ndarray) – cccsum for histogram plotting, can be the sameas cccsum but included if cccsum is just an envelope.

• trace (obspy.core.trace.Trace) – A sample trace from the same time as ccc-sum

• threshold (float) – Detection threshold within cccsum

• save (bool) – If True will save and not plot to screen, vice-versa if False

• savefile (str) – Path to save figure to, only required if save=True


Example

>>> from obspy import read>>> from eqcorrscan.core.match_filter import normxcorr2>>> from eqcorrscan.utils.plotting import triple_plot>>> st = read()>>> template = st[0].copy().trim(st[0].stats.starttime + 8,... st[0].stats.starttime + 12)>>> tr = st[0]>>> ccc = normxcorr2(template=template.data, image=tr.data)>>> tr.data = tr.data[0:len(ccc[0])]>>> triple_plot(cccsum=ccc, cccsum_hist=ccc, trace=tr,... threshold=0.8)










eqcorrscan.utils.plotting.xcorr_plot

eqcorrscan.utils.plotting.xcorr_plot(template, image, shift=None, cc=None,cc_vec=None, save=False, savefile=None)

Plot a template overlying an image aligned by correlation.

Parameters

• template (numpy.ndarray) – Short template image

• image (numpy.ndarray) – Long master image

• shift (int) – Shift to apply to template relative to image, in samples

• cc (float) – Cross-correlation at shift

• cc_vec (numpy.ndarray) – Cross-correlation vector.

• save (bool) – Whether to save the plot or not.

• savefile (str) – File name to save to


Example

>>> from obspy import read>>> from eqcorrscan.utils.plotting import xcorr_plot>>> from eqcorrscan.utils.stacking import align_traces>>> st = read().detrend('simple').filter('bandpass', freqmin=2, freqmax=15)>>> shifts, ccs = align_traces([st[0], st[1]], 40)>>> shift = shifts[1] * st[1].stats.sampling_rate>>> cc = ccs[1]>>> xcorr_plot(template=st[1].data, image=st[0].data, shift=shift,... cc=cc)

3.6. Utils 149










3.6.12 pre_processing

Pre-processing modules take care of ensuring all data are processed the same. Note that gaps should be paddedafter filtering if you decide not to use these routines (see notes in correlation_warnings). Utilities module whosefunctions are designed to do the basic processing of the data using obspy modules (which also rely on scipy andnumpy).



Classes & Functions

dayproc Wrapper for dayproc to parallel multiple traces in astream.

process Basic function to process data, usually called bydayproc or shortproc.

shortproc Basic function to bandpass and downsample.

eqcorrscan.utils.pre_processing.dayproc

eqcorrscan.utils.pre_processing.dayproc(st, lowcut, highcut, filt_order, samp_rate,starttime, debug=0, parallel=True,num_cores=False, ignore_length=False,seisan_chan_names=False, fill_gaps=True)

Wrapper for dayproc to parallel multiple traces in a stream.

Works in place on data. This is employed to ensure all parts of the data are processed in the same way.





Parameters

• st (obspy.core.stream.Stream) – Stream to process (can be trace).

• lowcut (float) – Low cut in Hz for bandpass.

• highcut (float) – High cut in Hz for bandpass.

• filt_order (int) – Corners for bandpass.

• samp_rate (float) – Desired sampling rate in Hz.

• starttime (obspy.core.utcdatetime.UTCDateTime) – Desired start-dateof trace.

• debug (int) – Debug output level from 0-5, higher numbers = more output.

• parallel (bool) – Set to True to process traces in parallel, this is often faster thanserial processing of traces: defaults to True.

• num_cores (int) – Control the number of cores for parallel processing, if set to Falsethen this will use all the cores.

• ignore_length (bool) – See warning below.

• seisan_chan_names (bool) – Whether channels are named like seisan channels(which are two letters rather than SEED convention of three) - defaults to True.

• fill_gaps (bool) – Whether to pad any gaps found with zeros or not.

Returns Processed stream.


Note: Will convert channel names to two characters long.

Warning: Will fail if data are less than 19.2 hours long - this number is arbitrary and is chosen to alertthe user to the dangers of padding to day-long, if you don’t care you can ignore this error by settingignore_length=True. Use this option at your own risk! It will also warn any-time it has to pad data - ifyou see strange artifacts in your detections, check whether the data have gaps.

Example

>>> import obspy>>> if int(obspy.__version__.split('.')[0]) >= 1:... from obspy.clients.fdsn import Client... else:... from obspy.fdsn import Client>>> from obspy import UTCDateTime>>> from eqcorrscan.utils.pre_processing import dayproc>>> client = Client('NCEDC')>>> t1 = UTCDateTime(2012, 3, 26)>>> t2 = t1 + 86400>>> bulk_info = [('BP', 'JCNB', '40', 'SP1', t1, t2)]>>> st = client.get_waveforms_bulk(bulk_info)>>> st_keep = st.copy() # Copy the stream for later examples>>> # Example of bandpass filtering>>> st = dayproc(st=st, lowcut=2, highcut=9, filt_order=3, samp_rate=20,... starttime=t1, debug=0, parallel=True, num_cores=2)>>> print(st[0])BP.JCNB.40.SP1 | 2012-03-26T00:00:00.000000Z - 2012-03-26T23:59:59.950000Z |→˓20.0 Hz, 1728000 samples


3.6. Utils 151
















>>> # Example of lowpass filtering>>> st = dayproc(st=st, lowcut=None, highcut=9, filt_order=3, samp_rate=20,... starttime=t1, debug=0, parallel=True, num_cores=2)>>> print(st[0])BP.JCNB.40.SP1 | 2012-03-26T00:00:00.000000Z - 2012-03-26T23:59:59.950000Z |→˓20.0 Hz, 1728000 samples>>> # Example of highpass filtering>>> st = dayproc(st=st, lowcut=2, highcut=None, filt_order=3, samp_rate=20,... starttime=t1, debug=0, parallel=True, num_cores=2)>>> print(st[0])BP.JCNB.40.SP1 | 2012-03-26T00:00:00.000000Z - 2012-03-26T23:59:59.950000Z |→˓20.0 Hz, 1728000 samples

eqcorrscan.utils.pre_processing.process

eqcorrscan.utils.pre_processing.process(tr, lowcut, highcut, filt_order, samp_rate,debug, starttime=False, clip=False,length=86400, seisan_chan_names=False,ignore_length=False, fill_gaps=True)

Basic function to process data, usually called by dayproc or shortproc.

Functionally, this will bandpass, downsample and check headers and length of trace to ensure files startwhen they should and are the correct length. This is a simple wrapper on obspy functions, we include ithere to provide a system to ensure all parts of the dataset are processed in the same way.

Note: Usually this function is called via dayproc or shortproc.

Parameters

• tr (obspy.core.trace.Trace) – Trace to process

• lowcut (float) – Low cut in Hz, if set to None and highcut is set, will use a lowpassfilter.

• highcut (float) – High cut in Hz, if set to None and lowcut is set, will use ahighpass filter.

• filt_order (int) – Number of corners for filter.

• samp_rate (float) – Desired sampling rate in Hz.

• debug (int) – Debug output level from 0-5, higher numbers = more output.

• starttime (obspy.core.utcdatetime.UTCDateTime) – Desired start oftrace

• clip (bool) – Whether to expect, and enforce a set length of data or not.

• length (float) – Use to set a fixed length for data from the given starttime.


• ignore_length (bool) – See warning in dayproc.


Returns Processed trace.

Type obspy.core.stream.Trace















eqcorrscan.utils.pre_processing.shortproc

eqcorrscan.utils.pre_processing.shortproc(st, lowcut, highcut, filt_order,samp_rate, debug=0, parallel=False,num_cores=False, starttime=None, end-time=None, seisan_chan_names=False,fill_gaps=True)

Basic function to bandpass and downsample.

Works in place on data. This is employed to ensure all parts of the data are processed in the same way.

Parameters

• st (obspy.core.stream.Stream) – Stream to process

• lowcut (float) – Low cut for bandpass in Hz

• highcut (float) – High cut for bandpass in Hz

• filt_order (int) – Number of corners for bandpass filter

• samp_rate (float) – Sampling rate desired in Hz

• debug (int) – Debug flag from 0-5, higher numbers = more output

• parallel (bool) – Set to True to process traces in parallel, for small numbers oftraces this is often slower than serial processing, defaults to False

• num_cores (int) – Control the number of cores for parallel processing, if set to Falsethen this will use all the cores.

• starttime (obspy.core.utcdatetime.UTCDateTime) – Desired data starttime, will trim to this before processing

• endtime (obspy.core.utcdatetime.UTCDateTime) – Desired data endtime, will trim to this before processing



Returns Processed stream


Note: Will convert channel names to two characters long.

Warning: If you intend to use this for processing templates you should consider how resampling willimpact your cross-correlations. Minor differences in resampling between day-long files (which you arelikely to use for continuous detection) and shorter files will reduce your cross-correlations!

Example, bandpass

>>> from obspy import read>>> from eqcorrscan.utils.pre_processing import shortproc>>> st = read('eqcorrscan/tests/test_data/WAV/TEST_/' +... '2013-09-01-0410-35.DFDPC_024_00')>>> st = shortproc(st=st, lowcut=2, highcut=9, filt_order=3, samp_rate=20,... debug=0, parallel=True, num_cores=2)>>> print(st[0])AF.LABE..SHZ | 2013-09-01T04:10:35.700000Z - 2013-09-01T04:12:05.650000Z | 20.→˓0 Hz, 1800 samples (continues on next page)

3.6. Utils 153
















Example, low-pass

>>> from obspy import read>>> from eqcorrscan.utils.pre_processing import shortproc>>> st = read('eqcorrscan/tests/test_data/WAV/TEST_/' +... '2013-09-01-0410-35.DFDPC_024_00')>>> st = shortproc(st=st, lowcut=None, highcut=9, filt_order=3,... samp_rate=20, debug=0)>>> print(st[0])AF.LABE..SHZ | 2013-09-01T04:10:35.700000Z - 2013-09-01T04:12:05.650000Z | 20.→˓0 Hz, 1800 samples

Example, high-pass

>>> from obspy import read>>> from eqcorrscan.utils.pre_processing import shortproc>>> st = read('eqcorrscan/tests/test_data/WAV/TEST_/' +... '2013-09-01-0410-35.DFDPC_024_00')>>> st = shortproc(st=st, lowcut=2, highcut=None, filt_order=3,... samp_rate=20, debug=0)>>> print(st[0])AF.LABE..SHZ | 2013-09-01T04:10:35.700000Z - 2013-09-01T04:12:05.650000Z | 20.→˓0 Hz, 1800 samples

3.6.13 sac_util

Part of the EQcorrscan package: tools to convert SAC headers to obspy event objects.

Note: This functionality is not supported for obspy versions below 1.0.0 as references times are not read in bySACIO, which are needed for defining pick times.



Classes & Functions

sactoevent Convert SAC headers (picks only) to obspy eventclass.

eqcorrscan.utils.sac_util.sactoevent

eqcorrscan.utils.sac_util.sactoevent(st, debug=0)Convert SAC headers (picks only) to obspy event class.

Picks are taken from header values a, t[0-9].

Parameters

• st (obspy.core.stream.Stream) – Stream of waveforms including SAC head-ers.





• debug (int) – Debug level, larger number = more output.

Returns Event with picks taken from SAC headers.

Return type obspy.core.event.event.Event

Note: This functionality is not supported for obspy versions below 1.0.0 as reference times are not read inby SACIO, which are needed for defining pick times.

Note: Takes the event origin information from the first trace in the stream - to ensure this works as youexpect, please populate the evla, evlo, evdp and nzyear, nzjday, nzhour, nzmin, nzsec, nzmsec for all traceswith the same values.

>>> from obspy import read>>> st = read('eqcorrscan/tests/test_data/SAC/2014p611252/*')>>> event = sactoevent(st)>>> print(event.origins[0].time)2014-08-15T03:55:21.057000Z>>> print(event.picks[0].phase_hint)S

3.6.14 seismo_logs

Functions to read log-files for seismic data to determine whether there are timing issues present. Designed to beused with the EQcorrscan package and to flag data that has more than a threshold timing issue.

Note: Currently only written to read RefTek rt130 log-files, and will not read all parameters - only for use whenchecking logs during cross-correlation. For full log-file exploration, Passcal tools: logpeek is useful.



Classes & Functions

check_all_logs Check all the log-files in a directory tree for timingerrors.

flag_time_err Find large time errors in list.rt_location_log Extract location information from a RefTek raw log-

file.rt_time_log Open and read reftek raw log-file.

eqcorrscan.utils.seismo_logs.check_all_logs

eqcorrscan.utils.seismo_logs.check_all_logs(directory, time_thresh)Check all the log-files in a directory tree for timing errors.

Parameters

• directory (str) – Directory to search within

• time_thresh (float) – Time threshold in seconds

Returns List of datetime.datetime for which error timing is above threshold, e.g. timeswhen data are questionable.

3.6. Utils 155








Return type list

eqcorrscan.utils.seismo_logs.flag_time_err

eqcorrscan.utils.seismo_logs.flag_time_err(phase_err, time_thresh=0.02)Find large time errors in list.

Scan through a list of tuples of time stamps and phase errors and return a list of time stamps with timingerrors above a threshold.

Note: This becomes important for networks cross-correlations, where if timing information is uncertain atone site, the relative arrival time (lag) will be incorrect, which will degrade the cross-correlation sum.

Parameters

• phase_err (list) – List of Tuple of float, datetime.datetime

• time_thresh (float) – Threshold to declare a timing error for

Returns List of datetime.datetime when timing is questionable.

eqcorrscan.utils.seismo_logs.rt_location_log

eqcorrscan.utils.seismo_logs.rt_location_log(logfile)Extract location information from a RefTek raw log-file.

Function to read a specific RefTek RT130 log-file and find all location information.

Parameters logfile (str) – The logfile to look in

Returns list of tuples of lat, lon, elevation in decimal degrees and km.

Return type list

eqcorrscan.utils.seismo_logs.rt_time_log

eqcorrscan.utils.seismo_logs.rt_time_log(logfile, startdate)Open and read reftek raw log-file.

Function to open and read a log-file as written by a RefTek RT130 datalogger. The information within isthen scanned for timing errors above the threshold.

Parameters

• logfile (str) – The logfile to look in

• startdate (datetime.date) – The start of the file as a date - files contain timingand the julian day, but not the year.

Returns List of tuple of (datetime.datetime, float) as time stamps and phase error.

3.6.15 stacking

Utility module of the EQcorrscan package to allow for different methods of stacking of seismic signal in oneplace.












Classes & Functions

linstack Compute the linear stack of a series of seismic streamsof multiplexed data.

PWS_stack Compute the phase weighted stack of a series ofstreams.

align_traces Align traces relative to each other based on theircross-correlation value.

eqcorrscan.utils.stacking.linstack

eqcorrscan.utils.stacking.linstack(streams, normalize=True)Compute the linear stack of a series of seismic streams of multiplexed data.

Parameters

• streams (list) – List of streams to stack

• normalize (bool) – Normalize traces before stacking, normalizes by the RMS am-plitude.

Returns stacked data


eqcorrscan.utils.stacking.PWS_stack

eqcorrscan.utils.stacking.PWS_stack(streams, weight=2, normalize=True)Compute the phase weighted stack of a series of streams.

Note: It is recommended to align the traces before stacking.

Parameters

• streams (list) – List of obspy.core.stream.Stream to stack.

• weight (float) – Exponent to the phase stack used for weighting.

• normalize (bool) – Normalize traces before stacking.

Returns Stacked stream.


eqcorrscan.utils.stacking.align_traces

eqcorrscan.utils.stacking.align_traces(trace_list, shift_len, master=False, posi-tive=False, plot=False)

Align traces relative to each other based on their cross-correlation value.

Uses the eqcorrscan.core.match_filter.normxcorr2() function to find the optimum shift toalign traces relative to a master event. Either uses a given master to align traces, or uses the trace with thehighest MAD amplitude.

Parameters

• trace_list (list) – List of traces to align

• shift_len (int) – Length to allow shifting within in samples

3.6. Utils 157









• master (obspy.core.trace.Trace) – Master trace to align to, if set to Falsewill align to the largest amplitude trace (default)

• positive (bool) – Return the maximum positive cross-correlation, or the absolutemaximum, defaults to False (absolute maximum).

• plot (bool) – If true, will plot each trace aligned with the master.

Returns list of shifts and correlations for best alignment in seconds.

Return type list

3.6.16 synth_seis

Early development functions to do very basic simulations of seismograms to be used as general matched-filtertemplates and see how well a simple model would fit with real data. Mostly used in EQcorrscan for testing.



Classes & Functions

generate_synth_data Generate a synthetic dataset to be used for testing.seis_sim Generate a simulated seismogram from a given S-P

time.SVD_sim Generate basis vectors of a set of simulated seismo-

grams.template_grid Generate a group of synthetic seismograms for a grid

of sources.

eqcorrscan.utils.synth_seis.generate_synth_data

eqcorrscan.utils.synth_seis.generate_synth_data(nsta, ntemplates, nseeds,samp_rate, t_length, max_amp,max_lag, debug=0)

Generate a synthetic dataset to be used for testing.

This will generate both templates and data to scan through. Templates will be generated using theutils.synth_seis functions. The day of data will be random noise, with random signal-to-noise ratio copies ofthe templates randomly seeded throughout the day. It also returns the seed times and signal-to-noise ratiosused.

Parameters

• nsta (int) – Number of stations to generate data for < 15.

• ntemplates (int) – Number of templates to generate, will be generated with ran-dom arrival times.

• nseeds (int) – Number of copies of the template to seed within the day of noisy datafor each template.

• samp_rate (float) – Sampling rate to use in Hz

• t_length (float) – Length of templates in seconds.

• max_amp (float) – Maximum signal-to-noise ratio of seeds.

• max_lag (float) – Maximum lag time in seconds (randomised).

• debug (int) – Debug level, bigger the number, the more plotting/output.

Returns Templates: List of obspy.core.stream.Stream
















Return type list

Returns Data: obspy.core.stream.Stream of seeded noisy data


Returns Seeds: dictionary of seed SNR and time with time in samples.

Return type dict

eqcorrscan.utils.synth_seis.seis_sim

eqcorrscan.utils.synth_seis.seis_sim(sp, amp_ratio=1.5, flength=False, phaseout=’all’)Generate a simulated seismogram from a given S-P time.

Will generate spikes separated by a given S-P time, which are then convolved with a decaying sine function.The P-phase is simulated by a positive spike of value 1, the S-arrival is simulated by a decaying boxcar ofmaximum amplitude 1.5. These amplitude ratios can be altered by changing the amp_ratio, which is theratio S amplitude:P amplitude.

Note: In testing this can achieve 0.3 or greater cross-correlations with data.

Parameters

• sp (int) – S-P time in samples

• amp_ratio (float) – S:P amplitude ratio

• flength (int) – Fixed length in samples, defaults to False

• phaseout (str) – Either ‘P’, ‘S’ or ‘all’, controls which phases to cut around, de-faults to ‘all’. Can only be used with ‘P’ or ‘S’ options if flength is set.

Returns Simulated data.


eqcorrscan.utils.synth_seis.SVD_sim

eqcorrscan.utils.synth_seis.SVD_sim(sp, lowcut, highcut, samp_rate, amp_range=array([-10., -9.99, -9.98, ..., 9.97, 9.98, 9.99]))

Generate basis vectors of a set of simulated seismograms.

Inputs should have a range of S-P amplitude ratios, in theory to simulate a range of focal mechanisms.

Parameters

• sp (int) – S-P time in seconds - will be converted to samples according to samp_rate.

• lowcut (float) – Low-cut for bandpass filter in Hz

• highcut (float) – High-cut for bandpass filter in Hz


• amp_range (numpy.ndarray) – Amplitude ratio range to generate synthetics for.

Returns set of output basis vectors


3.6. Utils 159
















eqcorrscan.utils.synth_seis.template_grid

eqcorrscan.utils.synth_seis.template_grid(stations, nodes, travel_times, phase,PS_ratio=1.68, samp_rate=100,flength=False, phaseout=’all’)

Generate a group of synthetic seismograms for a grid of sources.

Used to simulate phase arrivals from a grid of known sources in a three-dimensional model. Lags must beknown and supplied, these can be generated from the bright_lights function: read_tt, and resampled to fitthe desired grid dimensions and spacing using other functions therein. These synthetic seismograms arevery simple models of seismograms using the seis_sim function herein. These approximate body-wave Pand S first arrivals as spikes convolved with damped sine waves.

Parameters

• stations (list) – List of the station names

• nodes (list) – List of node locations in (lon,lat,depth)

• travel_times (numpy.ndarray) – Array of travel times where travel_times[i][:]refers to the travel times for station=stations[i], and travel_times[i][j] refers to stations[i]for nodes[j]

• phase (str) – Can be either ‘P’ or ‘S’

• PS_ratio (float) – P/S velocity ratio, defaults to 1.68

• samp_rate (float) – Desired sample rate in Hz, defaults to 100.0

• flength (int) – Length of template in samples, defaults to False

• phaseout (str) – Either ‘S’, ‘P’, ‘all’ or ‘both’, determines which phases to cliparound. ‘all’ Encompasses both phases in one channel, but will return nothing if theflength is not long enough, ‘both’ will return two channels for each stations, one SYN_Zwith the synthetic P-phase, and one SYN_H with the synthetic S-phase.

Returns List of obspy.core.stream.Stream

3.6.17 trigger

Functions to enable simple energy-base triggering in a network setting where different stations have different noiseparameters.



Classes & Functions

network_trigger Main function to compute triggers for a network ofstations.

read_trigger_parameters Read the trigger parameters into trigger_parameterclasses.

TriggerParameters Base class for trigger parameters.

eqcorrscan.utils.trigger.network_trigger

eqcorrscan.utils.trigger.network_trigger(st, parameters, thr_coincidence_sum, move-out, max_trigger_length=60, despike=True,debug=0)

Main function to compute triggers for a network of stations. Computes single-channel characteristic func-tions using given parameters, then combines these to find network triggers on a number of stations within a











set moveout window.

Parameters

• st (obspy.core.stream.Stream) – Stream to compute detections within

• parameters (list) – List of parameter class

• thr_coincidence_sum (int) – Minimum number of stations required to raise anetwork trigger.

• moveout (float) – Window to find triggers within in the network detection stage.

• max_trigger_length (float) – Maximum trigger length in seconds, used to re-move long triggers - can set to False to not use.

• despike (bool) – Whether to apply simple despiking routine or not

• debug (int) – Debug output level, higher is more output.

Returns List of triggers

Return type list

Example

>>> from obspy import read>>> from eqcorrscan.utils.trigger import TriggerParameters, network_trigger>>> st = read("https://examples.obspy.org/" +... "example_local_earthquake_3stations.mseed")>>> parameters = []>>> for tr in st:... parameters.append(TriggerParameters({'station': tr.stats.station,... 'channel': tr.stats.channel,... 'sta_len': 0.5,... 'lta_len': 10.0,... 'thr_on': 10.0,... 'thr_off': 3.0,... 'lowcut': 2.0,... 'highcut': 15.0}))>>> triggers = network_trigger(st=st, parameters=parameters,... thr_coincidence_sum=5, moveout=30,... max_trigger_length=60, despike=False)Looking for coincidence triggers ...Found 1 Coincidence triggers

eqcorrscan.utils.trigger.read_trigger_parameters

eqcorrscan.utils.trigger.read_trigger_parameters(filename)Read the trigger parameters into trigger_parameter classes.

Parameters filename (str) – Parameter file

Returns List of eqcorrscan.utils.trigger.TriggerParameters

Return type list

Example

>>> from eqcorrscan.utils.trigger import read_trigger_parameters>>> parameters = read_trigger_parameters('parameters')

3.6. Utils 161









eqcorrscan.utils.trigger.TriggerParameters

class eqcorrscan.utils.trigger.TriggerParameters(header={})Bases: obspy.core.util.attribdict.AttribDict

Base class for trigger parameters.

>>> from eqcorrscan.utils.trigger import TriggerParameters>>> defaults = TriggerParameters()>>> defaults.station = 'TEST'>>> # Or use dictionaries>>> defaults['station'] = 'ALF'>>> defaults = TriggerParameters({'station': 'TEST',... 'channel': 'SHZ',... 'sta_len': 0.3,... 'lta_len': 10.0,... 'thr_on': 10,... 'thr_off': 3,... 'lowcut': 2,... 'highcut': 20})>>> print(defaults.station)TEST

__init__(header={})

Methods

__init__([header])clear()copy()get(k[,d])items()keys()pop(k[,d]) If key is not found, d is returned if given, otherwise

KeyError is raised.popitem() as a 2-tuple; but raise KeyError if D is empty.setdefault(k[,d])update([E, ]**F) If E present and has a .keys() method, does: for

k in E: D[k] = E[k] If E present and lacks .keys()method, does: for (k, v) in E: D[k] = v In eithercase, this is followed by: for k, v in F.items(): D[k]= v

values()write(filename[, append]) Write the parameters to a file as a human-readable

series of dicts.

Attributes

defaultsdo_not_warn_onreadonlywarn_on_non_default_key


https://docs.obspy.org/packages/autogen/obspy.core.util.attribdict.AttribDict.html#obspy.core.util.attribdict.AttribDict

Python Module Index

eeqcorrscan.core.bright_lights, 40eqcorrscan.core.lag_calc, 45eqcorrscan.core.match_filter, 49eqcorrscan.core.subspace, 78eqcorrscan.core.template_gen, 83eqcorrscan.utils.archive_read, 94eqcorrscan.utils.catalog_to_dd, 96eqcorrscan.utils.catalog_utils, 99eqcorrscan.utils.clustering, 100eqcorrscan.utils.correlate, 108eqcorrscan.utils.despike, 113eqcorrscan.utils.findpeaks, 114eqcorrscan.utils.mag_calc, 115eqcorrscan.utils.parameters, 122eqcorrscan.utils.picker, 123eqcorrscan.utils.plotting, 125eqcorrscan.utils.pre_processing, 150eqcorrscan.utils.sac_util, 154eqcorrscan.utils.seismo_logs, 155eqcorrscan.utils.stacking, 156eqcorrscan.utils.synth_seis, 158eqcorrscan.utils.trigger, 160

163


164 Python Module Index

Index

Symbols_GSE2_PAZ_read() (in module eq-

corrscan.utils.mag_calc), 122__init__() (eqcorrscan.core.match_filter.Detection

method), 50__init__() (eqcorrscan.core.match_filter.Family

method), 51__init__() (eqcorrscan.core.match_filter.Party method),

55__init__() (eqcorrscan.core.match_filter.Template

method), 60__init__() (eqcorrscan.core.match_filter.Tribe method),

65__init__() (eqcorrscan.core.subspace.Detector

method), 80__init__() (eqcorrscan.utils.parameters.EQcorrscanParameters

method), 123__init__() (eqcorrscan.utils.trigger.TriggerParameters

method), 162_channel_loop() (in module eqcorrscan.core.lag_calc),

47_check_available_data() (in module eq-

corrscan.utils.archive_read), 96_cum_net_resp() (in module eq-

corrscan.core.bright_lights), 44_day_loop() (in module eqcorrscan.core.lag_calc), 48_find_detections() (in module eq-

corrscan.core.bright_lights), 45_find_resp() (in module eqcorrscan.utils.mag_calc),

121_get_station_file() (in module eq-

corrscan.utils.archive_read), 96_group_detect() (in module eq-

corrscan.core.match_filter), 76_group_process() (in module eq-

corrscan.core.match_filter), 76_max_p2t() (in module eqcorrscan.utils.mag_calc), 121_node_loop() (in module eq-

corrscan.core.bright_lights), 44_pairwise() (in module eqcorrscan.utils.mag_calc), 121_prepare_data() (in module eqcorrscan.core.lag_calc),

49_read_family() (in module eq-

corrscan.core.match_filter), 78_read_tt() (in module eqcorrscan.core.bright_lights), 43_resample_grid() (in module eq-

corrscan.core.bright_lights), 43_rm_similarlags() (in module eq-

corrscan.core.bright_lights), 42_rms() (in module eqcorrscan.core.bright_lights), 42_sim_WA() (in module eqcorrscan.utils.mag_calc), 120_test_event_similarity() (in module eq-

corrscan.core.match_filter), 78_total_microsec() (in module eq-

corrscan.core.match_filter), 78_write_family() (in module eq-

corrscan.core.match_filter), 77_xcorr_interp() (in module eqcorrscan.core.lag_calc),

49

Aalign_traces() (in module eqcorrscan.utils.stacking),

157amp_pick_event() (in module eq-

corrscan.utils.mag_calc), 116append() (eqcorrscan.core.match_filter.Family

method), 51

Bbrightness() (in module eqcorrscan.core.bright_lights),

40

Ccalc_b_value() (in module eqcorrscan.utils.mag_calc),

117calc_max_curv() (in module eq-

corrscan.utils.mag_calc), 118check_all_logs() (in module eq-

corrscan.utils.seismo_logs), 155chunk_data() (in module eqcorrscan.utils.plotting), 126client_detect() (eqcorrscan.core.match_filter.Tribe

method), 65cluster() (eqcorrscan.core.match_filter.Tribe method),

67cluster() (in module eqcorrscan.utils.clustering), 102coherence() (in module eqcorrscan.core.bright_lights),

41

165


coin_trig() (in module eqcorrscan.utils.findpeaks), 114construct() (eqcorrscan.core.match_filter.Template

method), 60construct() (eqcorrscan.core.match_filter.Tribe

method), 67construct() (eqcorrscan.core.subspace.Detector

method), 80copy() (eqcorrscan.core.match_filter.Detection

method), 50copy() (eqcorrscan.core.match_filter.Family method),

51copy() (eqcorrscan.core.match_filter.Party method), 55copy() (eqcorrscan.core.match_filter.Template

method), 61copy() (eqcorrscan.core.match_filter.Tribe method), 67corr_cluster() (in module eqcorrscan.utils.clustering),

102cross_chan_coherence() (in module eq-

corrscan.utils.clustering), 103cross_net() (in module eqcorrscan.utils.picker), 124cumulative_detections() (in module eq-

corrscan.utils.plotting), 126

Ddayproc() (in module eqcorrscan.utils.pre_processing),

150decluster() (eqcorrscan.core.match_filter.Party

method), 56detect() (eqcorrscan.core.match_filter.Template

method), 62detect() (eqcorrscan.core.match_filter.Tribe method),

67detect() (eqcorrscan.core.subspace.Detector method),

80Detection (class in eqcorrscan.core.match_filter), 50detection_multiplot() (in module eq-

corrscan.utils.plotting), 129Detector (class in eqcorrscan.core.subspace), 79dist_calc() (in module eqcorrscan.utils.mag_calc), 118dist_mat_km() (in module eqcorrscan.utils.clustering),

103distance_matrix() (in module eq-

corrscan.utils.clustering), 103

Eempirical_svd() (in module eqcorrscan.utils.clustering),

104energy_capture() (eqcorrscan.core.subspace.Detector

method), 81eqcorrscan.core.bright_lights (module), 40eqcorrscan.core.lag_calc (module), 45eqcorrscan.core.match_filter (module), 49eqcorrscan.core.subspace (module), 78eqcorrscan.core.template_gen (module), 83eqcorrscan.utils.archive_read (module), 94eqcorrscan.utils.catalog_to_dd (module), 96eqcorrscan.utils.catalog_utils (module), 99eqcorrscan.utils.clustering (module), 100

eqcorrscan.utils.correlate (module), 108eqcorrscan.utils.despike (module), 113eqcorrscan.utils.findpeaks (module), 114eqcorrscan.utils.mag_calc (module), 115eqcorrscan.utils.parameters (module), 122eqcorrscan.utils.picker (module), 123eqcorrscan.utils.plotting (module), 125eqcorrscan.utils.pre_processing (module), 150eqcorrscan.utils.sac_util (module), 154eqcorrscan.utils.seismo_logs (module), 155eqcorrscan.utils.stacking (module), 156eqcorrscan.utils.synth_seis (module), 158eqcorrscan.utils.trigger (module), 160EQcorrscanParameters (class in eq-

corrscan.utils.parameters), 122extract_detections() (in module eq-

corrscan.utils.clustering), 104extract_from_stack() (in module eq-

corrscan.core.template_gen), 87extract_from_stream() (in module eq-

corrscan.core.match_filter), 71

FFamily (class in eqcorrscan.core.match_filter), 51fftw_multi_normxcorr() (in module eq-

corrscan.utils.correlate), 108fftw_normxcorr() (in module eq-

corrscan.utils.correlate), 109filter() (eqcorrscan.core.match_filter.Party method), 55filter_picks() (in module eqcorrscan.utils.catalog_utils),

99find_peaks2_short() (in module eq-

corrscan.utils.findpeaks), 114flag_time_err() (in module eq-

corrscan.utils.seismo_logs), 156freq_mag() (in module eqcorrscan.utils.plotting), 130from_client() (in module eq-

corrscan.core.template_gen), 88from_meta_file() (in module eq-

corrscan.core.template_gen), 90from_sac() (in module eqcorrscan.core.template_gen),

91from_seishub() (in module eq-

corrscan.core.template_gen), 92

Ggenerate_synth_data() (in module eq-

corrscan.utils.synth_seis), 158get_array_xcorr() (in module eq-

corrscan.utils.correlate), 110get_catalog() (eqcorrscan.core.match_filter.Party

method), 57get_catalog() (in module eqcorrscan.core.match_filter),

71get_stream_xcorr() (in module eq-

corrscan.utils.correlate), 110group_delays() (in module eqcorrscan.utils.clustering),

106

166 Index


Iinterev_mag() (in module eqcorrscan.utils.plotting),

132

Llag_calc() (eqcorrscan.core.match_filter.Family

method), 52lag_calc() (eqcorrscan.core.match_filter.Party method),

57lag_calc() (in module eqcorrscan.core.lag_calc), 46linstack() (in module eqcorrscan.utils.stacking), 157

Mmatch_filter() (in module eqcorrscan.core.match_filter),

72median_filter() (in module eqcorrscan.utils.despike),

113min_chans() (eqcorrscan.core.match_filter.Party

method), 58multi() (in module eqcorrscan.core.subspace), 82multi_event_singlechan() (in module eq-

corrscan.utils.plotting), 133multi_template_gen() (in module eq-

corrscan.core.template_gen), 93

Nnetwork_trigger() (in module eqcorrscan.utils.trigger),

160normxcorr2() (in module eqcorrscan.core.match_filter),

74NR_plot() (in module eqcorrscan.utils.plotting), 136numpy_normxcorr() (in module eq-

corrscan.utils.correlate), 109

Oobspy_3d_plot() (in module eqcorrscan.utils.plotting),

136

Ppartition() (eqcorrscan.core.subspace.Detector

method), 81Party (class in eqcorrscan.core.match_filter), 55peaks_plot() (in module eqcorrscan.utils.plotting), 137plot() (eqcorrscan.core.match_filter.Family method), 53plot() (eqcorrscan.core.match_filter.Party method), 56plot() (eqcorrscan.core.subspace.Detector method), 81plot_repicked() (in module eqcorrscan.utils.plotting),

138plot_synth_real() (in module eqcorrscan.utils.plotting),

139pretty_template_plot() (in module eq-

corrscan.utils.plotting), 140process() (in module eqcorrscan.utils.pre_processing),

152PWS_stack() (in module eqcorrscan.utils.stacking), 157

Rre_thresh_csv() (in module eqcorrscan.utils.clustering),

106read() (eqcorrscan.core.match_filter.Party method), 58read() (eqcorrscan.core.match_filter.Template method),

63read() (eqcorrscan.core.match_filter.Tribe method), 69read() (eqcorrscan.core.subspace.Detector method), 82read_data() (in module eqcorrscan.utils.archive_read),

94read_detections() (in module eq-

corrscan.core.match_filter), 75read_detector() (in module eqcorrscan.core.subspace),

82read_parameters() (in module eq-

corrscan.utils.parameters), 123read_party() (in module eqcorrscan.core.match_filter),

75read_phase() (in module eq-

corrscan.utils.catalog_to_dd), 97read_template() (in module eq-

corrscan.core.match_filter), 75read_tribe() (in module eqcorrscan.core.match_filter),

75read_trigger_parameters() (in module eq-

corrscan.utils.trigger), 161readSTATION0() (in module eq-

corrscan.utils.catalog_to_dd), 97register_array_xcorr() (in module eq-

corrscan.utils.correlate), 110remove() (eqcorrscan.core.match_filter.Tribe method),

70rethreshold() (eqcorrscan.core.match_filter.Party

method), 58rt_location_log() (in module eq-

corrscan.utils.seismo_logs), 156rt_time_log() (in module eqcorrscan.utils.seismo_logs),

156

Ssactoevent() (in module eqcorrscan.utils.sac_util), 154same_processing() (eq-

corrscan.core.match_filter.Template method),64

seis_sim() (in module eqcorrscan.utils.synth_seis), 159sfiles_to_event() (in module eq-

corrscan.utils.catalog_to_dd), 97shortproc() (in module eq-

corrscan.utils.pre_processing), 153sort() (eqcorrscan.core.match_filter.Family method), 53sort() (eqcorrscan.core.match_filter.Party method), 59sort() (eqcorrscan.core.match_filter.Tribe method), 70space_cluster() (in module eqcorrscan.utils.clustering),

107space_time_cluster() (in module eq-

corrscan.utils.clustering), 107spec_trace() (in module eqcorrscan.utils.plotting), 141stalta_pick() (in module eqcorrscan.utils.picker), 124

Index 167


subspace_detect() (in module eq-corrscan.core.subspace), 82

subspace_detector_plot() (in module eq-corrscan.utils.plotting), 143

svd() (in module eqcorrscan.utils.clustering), 101svd_moments() (in module eqcorrscan.utils.mag_calc),

119SVD_plot() (in module eqcorrscan.utils.plotting), 144SVD_sim() (in module eqcorrscan.utils.synth_seis),

159svd_to_stream() (in module eq-

corrscan.utils.clustering), 101

TTemplate (class in eqcorrscan.core.match_filter), 60template_gen() (in module eq-

corrscan.core.template_gen), 84template_grid() (in module eq-

corrscan.utils.synth_seis), 160template_remove() (in module eq-

corrscan.utils.despike), 113threeD_gridplot() (in module eqcorrscan.utils.plotting),

146threeD_seismplot() (in module eq-

corrscan.utils.plotting), 147time_multi_normxcorr() (in module eq-

corrscan.utils.correlate), 109Tribe (class in eqcorrscan.core.match_filter), 65TriggerParameters (class in eqcorrscan.utils.trigger),

162triple_plot() (in module eqcorrscan.utils.plotting), 147

Wwrite() (eqcorrscan.core.match_filter.Detection

method), 50write() (eqcorrscan.core.match_filter.Family method),

54write() (eqcorrscan.core.match_filter.Party method), 59write() (eqcorrscan.core.match_filter.Template

method), 64write() (eqcorrscan.core.match_filter.Tribe method), 70write() (eqcorrscan.core.subspace.Detector method), 82write() (eqcorrscan.utils.parameters.EQcorrscanParameters

method), 123write_catalog() (in module eq-

corrscan.core.match_filter), 75write_catalog() (in module eq-

corrscan.utils.catalog_to_dd), 97write_correlations() (in module eq-

corrscan.utils.catalog_to_dd), 98write_event() (in module eq-

corrscan.utils.catalog_to_dd), 99

Xxcorr_plot() (in module eqcorrscan.utils.plotting), 149

168 Index

eqcorrscan documentation · python package. 3.1.1why eqcorrscan? eqcorrscan is designed to compute...

Documents