Requake

Repeating earthquakes search and analysis.

Copyright:: 2021-2024 Claudio Satriano satriano@ipgp.fr
Release:: 0.6
Date:: May 06, 2024

Description

Requake is a command line tool to search and analyse repeating earthquakes.

It can either scan an existing earthquake catalog to search for similar events, or perform template matching on a continuous waveform stream.

Catalogs and waveforms can be read from local files or downloaded using standard FDSN web services.

Requake is written in Python and uses ObsPy as backend.

Installation

Installing the latest release

Using pip and PyPI (preferred method)

The latest release of Requake is available on the Python Package Index.

You can install it easily through pip:

pip install requake

Installing a development snapshot

If you need a recent feature that is not in the latest release (see the unreleased section in the Requake Changelog), you want to use the more recent development snapshot from the Requake GitHub repository.

Using pip

The easiest way to install the most recent development snapshot is to download and install it through pip, using its builtin git client:

pip install git+https://github.com/SeismicSource/requake.git

Run this command again, from times to times, to keep Requake updated with the development version.

Cloning the Requake GitHub repository

If you want to take a look at the source code (and possibly modify it 😉), clone the project using git:

git clone https://github.com/SeismicSource/requake.git

or, using SSH:

git clone git@github.com:SeismicSource/requake.git

(avoid using the “Download ZIP” option from the green “Code” button, since version number is lost).

Then, go into the requake main directory and install the code in “editable mode” by running:

pip install -e .

You can keep your local Requake repository updated by running git pull from times to times. Thanks to pip‘s “editable mode”, you don’t need to reinstall Requake after each update.

Running

Command line arguments

Requake is based on a single executable, aptly named requake 😉.

To get help, use:

requake -h

Different commands are available:

sample_config       write sample config file to current directory and exit
update_config       update an existing config file to the latest version
read_catalog        read an event catalog from web services or from a file
print_catalog       print the event catalog to screen
scan_catalog        scan an existing catalog for earthquake pairs
print_pairs         print pairs to screen
plot_pair           plot traces for a given event pair
build_families      build families of repeating earthquakes from a catalog
                    of pairs
print_families      print families to screen
plot_families       plot traces for one ore more event families
plot_timespans      plot family timespans
plot_cumulative     cumulative plot for one or more families
map_families        plot families on a map
flag_family         flag a family of repeating earthquakes as valid or not
                    valid.
build_templates     build waveform templates for one or more event
                    families
scan_templates      scan a continuous waveform stream using one or more
                    templates

Certain commands (e.g., plot_pair) require further arguments (use, e.g., requake plot_pair -h to get help).

Requake supports command line tab completion for commands and arguments, thanks to argcomplete. To enable command line tab completion, add the following line to your .bashrc or .zshrc:

eval "$(register-python-argcomplete requake)"

Typical workflow

The first thing you will want to do is to generate a sample Configuration File:

requake sample_config

Edit the Configuration File according to your needs, then read or download the event catalog:

requake read_catalog

or

requake read_catalog CATALOG_FILE

Now, build the catalog of event pairs with:

requake scan_catalog

Once done (it will take time!), you are ready to build repeating earthquake families:

requake build_families

Performances

requake scan_catalog took 53 minutes on my 2.7 GHz i7 MacBook Pro to process 14,100,705 earthquake pairs. Dowloaded traces are cached in memory to speed up execution. Processing is not yet parallel: some improvements might come in future versions, when parallelization will be implemented.
requake build_families is fast™.

Slip Models

Following Uchida [2019], Requake provides different models to estimate fault slip (or creep) from repeating earthquakes magnitude.

First of all, magnitude is converted to seismic moment using the well known formula of Hanks and Kanamori [1979] (seismic moment \(M_0\) in \(\Nm\)):

\[M_0 = 10^{1.5(M_w + 6.07)}\]

or (seismic moment \(M_0\) in \(\dynecm\)):

\[M_0 = 10^{1.5(M_w + 10.7)}\]

Then, slip is estimated using one of the three models discussed below, selectable using the mag_to_slip_model parameter in the Configuration File. See Figure 1 for a comparison of the three models.

slip vs magnitude for three models — **Figure 1** Relationship between magnitude (or seismic moment) and slip for three models. Figure from Uchida [2019].

Nadeau and Johnson (1998)

Nadeau and Johnson [1998] proposed the following empirical relationship between the seismic moment of a repeting earthquake (\(M_0\) in \(\dynecm\)) and the fault slip around it (\(d\) in \(\cm\)):

\[d = 10^{-2.36} M_0^{0.17}\]

This formula is selected by setting the mag_to_slip_model parameter to N1998.

Beeler et al. (2001)

Beeler et al. [2001] proposed an alternative empirical model to explain the recurrence intervals of the Parkfield repeaters, which accounts for the possibility of aseismic slip around the repeating earthquakes asperities. In this model the repeating earthquake asperity is allowed to continuously creep and strain harden until reaching a failure threshold stress. Their model for fault slip \(d\) (in \(\cm\)) is the following:

\[d = \Delta\sigma \left[ \frac{1}{1.81\mu} \left( \frac{M_0}{\Delta\sigma} \right)^{\frac{1}{3}} + \frac{1}{C} \right]\]

where \(\Delta\sigma\) is the static stress drop (in \(\MPa\)), \(\mu\) is the rigidity (in \(\MPa\)), \(M_0\) is the seismic moment (in \(\Nm\)), and \(C\) is the strain hardening coefficient (in \(\MPacm\)).

This formula is selected by setting the mag_to_slip_model parameter to B2001. The values for staticx stress drop, rigidity and strain hardening coefficient must be set in the Configuration File.

Eshelby (1957) circular crack model

A somehow simpler approach is to assume that the fault creep around the repeater asperity is equal to the slip released by the repeater rupture. Assuming a circular crack with constant stress-drop, one can derive the slip (\(d\), in \(\cm\)) as:

\[d = \frac{M_0}{\pi \mu a^2}\]

where \(M_0\) is the seismic moment (in \(\Nm\)), \(\mu\) is the rigidity (in \(\MPa\)) and \(a\) is the fault radius (in \(\cm\)).

The source radius (in \(\cm\)) is obtained from the Eshelby [1957] formula:

\[a = \left( \frac{7}{16} \frac{M_0}{\Delta \sigma} \right)^{\frac{1}{3}}\]

Where \(\Delta \sigma\) is the static stress drop (in \(\MPa\)).

This formula is selected by setting the mag_to_slip_model parameter to E1957. The value for static stress drop must be set in the Configuration File.

Configuration File

Configuration file (default name: requake.conf) is a plain text file with keys and values in the form key = value. Comment lines start with #.

Here is the default config file, generated through requake sample_config:

#### Configuration file for Requake

#### Station metadata and waveform data
## FDSN station webservice URL to retrieve station metadata.
## Use a full URL or a ObsPy shortcut (e.g., IRIS, RESIF, GEOFON, ...)
fdsn_station_url = http://example.com
## Alternatively, you can provide the path to a local file with station
## metadata in any format supported by ObsPy (note that some formats may not
## contain station coordinates, which are required for the scan,
## see https://docs.obspy.org/packages/obspy.core.inventory.html).
## If both fdsn_station_url and stationxml_file are provided, the
## local file will be used.
station_metadata_path = None
## FDSN dataselect webservice URL to retrieve waveforms.
## Use a full URL or a ObsPy shortcut (e.g., IRIS, RESIF, GEOFON, ...)
fdsn_dataselect_url = http://example.com
## Alternatively, you can provide the path to a local SDS waveform archive
## (see https://docs.obspy.org/packages/autogen/obspy.clients.filesystem.sds.html)
waveform_data_path = None

#### Catalog-based scan
### The following parameters are for a catalog-based scan:
### each catalog event is compared with the other catalog events within
### a certain distance range. Similarity is checked by waveform
### cross-correlation at one or more stations.
### To perform a catalog-based scan use:
###    requake scan_catalog
## FDSN event webservice URL to retrieve event catalogs.
## Use a full URL or a ObsPy shortcut (e.g., IRIS, RESIF, GEOFON, ...)
catalog_fdsn_event_url = http://example.com
## start time for event selection (UTC date time)
catalog_start_time = 2021-08-23T00:00:00
## end time for event selection (UTC date time or 'now')
catalog_end_time = 2021-08-24T00:00:00
## Optionally, up to three other sources can be defined for different
## time intervals
catalog_fdsn_event_url_1 = None
catalog_start_time_1 = None
catalog_end_time_1 = None
catalog_fdsn_event_url_2 = None
catalog_start_time_2 = None
catalog_end_time_2 = None
catalog_fdsn_event_url_3 = None
catalog_start_time_3 = None
catalog_end_time_3 = None
## geographic selection (decimal degrees)
catalog_lat_min = 12.5
catalog_lat_max = 18.5
catalog_lon_min = -62.5
catalog_lon_max = -58.5
## depth selection (km, positive down)
catalog_depth_min = 0
catalog_depth_max = 60
## magnitude selection
catalog_mag_min = 2
catalog_mag_max = 4
## maximum distance range to search for similar earthquakes (radius, km)
catalog_search_range = 30
## trace id(s) to compute cross-correlation, in NET.STA.LOC.CHAN format.
## Waveform data for this trace(s) id will be retrieved using the station
## webservice.
## If more than a trace_id is specified (separated by commas), the closest
## station will be used for a given event pair.
catalog_trace_id = NET.STA.LOC.CHAN

#### Template-based scan
### The following parameters are for template-based scan:
### A template is used to search for similar waveforms at a given station
### over a givent time interval.
### To perform a template-based scan use:
###    requake scan_templates
## start time for template search (UTC date time)
template_start_time = 2021-08-23T00:00:00
## end time for event template search (UTC date time or 'now')
template_end_time = 2021-08-24T00:00:00
## Time chunk (in seconds) to analyze continuous data.
## Large values (1 hour or more) will result in fewer data requests and
## faster execution. However, cross-correlation can be slow for too large
## values. No more than one event per time chunk can be detected, so the
## length of time chunk should be smaller than the minimum inter-event time
## you want to detect.
time_chunk = 3600
## Overlap between time chunks (in seconds)
time_chunk_overlap = 60
## Minimum ratio between cross-correlation (cc) and median absolute deviation
## (MAD) of cross-correlation (cc_mad). A detection id declared when:
##  cc/cc_mad > min_cc_mad_ratio
min_cc_mad_ratio = 50

#### Processing parameters
## Seconds before P arrival to cut trace (only used for catalog search)
cc_pre_P = 5
## Trace length in seconds (only used for catalog search)
cc_trace_length = 120
## Frequency range for computing cross-correlation (Hz)
cc_freq_min = 2
cc_freq_max = 10
## Maximum authorized shift for computing cross-correlation (s)
cc_max_shift = 5
## Minimum cross-correlation value to declare similar waveforms
## (between 0 and 1)
cc_min = 0.95
## Clustering algorithm to create families of similar events.
## Possible options are:
##  shared : families are created by clustering all event pairs sharing
##           an event
##  UPGMA : families are created through the Unweighted Pair Group Method
##          with Arithmetic Mean (UPGMA) algorithm
##          (see https://en.wikipedia.org/wiki/UPGMA)
clustering_algorithm = shared
## Search for anticorrelated events (negative CC)
cc_allow_negative = false
## How families should be sorted when assigning family numbers.
## Possible options are:
##  time : increasing origin time of first event in family (default option)
##  longitude : increasing longitude
##  latitude : increasing latitude
##  depth : increasing depth
##  distance_from : increasing horizontal distance from a given point
sort_families_by = time
## Longitude and latitude of reference point,
## if sort_families_by = 'distance_from'
distance_from_lon = None
distance_from_lat = None
## Templates are built by averaging the traces in the family.
## Set the following paramter to True if you want to normalize the traces
## before averaging.
## Normalization will produce an average trace which is more representative
## of the family, but will be less effective in reducing noise.
normalize_traces_before_averaging = False

#### Post-processing parameters
## Estimation of fault slip (in cm) from repetater's magnitude
## Choose between:
##  NJ1998 : Nadeau and Johnson (1998)
##  B2001 : Beeler et al. (2001)
##  E1957 : Eshelby (1957), circular crack model
## See Uchida (2019, https://doi.org/10.1186/s40645-019-0284-z) for details
## on the models.
mag_to_slip_model = NJ1998
## Static stress drop value for B2001 and E1957 models (MPa)
static_stress_drop = 10.0
## Rigidity value for B2001 and E1957 models (GPa)
rigidity = 30.0
## Strain hardening coefficient for B2001 model (MPa/cm)
strain_hardening = 0.5

Requake Changelog

v0.6 - 2024-05-04

Note: you might want to run requake update_config to update your config file to the latest version.

Verb plot_slip renamed to plot_cumulative. This new verb has new options to plot cumulative slip, cumulative moment, and cumulative number of events, and to make the plot logarithmic.
New verb print_catalog: print the event catalog to screen
New verb print_pairs: print the event pairs to screen
print_families: also print minimum and maximum family magnitudes
Additional models to convert magnitude to slip. Currently supported models are: Nadeau and Johnson (1998), Beeler et al. (2001), Eshelby (1957). Model selection is done using the mag_to_slip_model config parameter.
New verb update_config: update an existing config file to the latest version

v0.5 - 2024-04-23

New config options: station_metadata_path and waveform_data_path to read station metadata and waveform data from files. Supports any metadata format supported by ObsPy and SDS (SeisComp Data Structure) waveform archives.
Filter catalog files on reading using the criteria in the config file
Improved time axes in plot_timespans and plot_slip for short time intervals
print_families: autoset duration units based on the average duration
plot_timespans: default sorting changed to family_number

v0.4.1 - 2024-03-11

Bugfix: requake executable was not installed

v0.4 - 2024-03-11

Package license changed to GPL-3.0 or later
New verb: read_catalog: read a catalog from web services or from a file (FDSN text, QuakeML, or CSV)
New verb: scan_templates: scan a continuous waveform stream using one or more templates. Templates can be from families or from file
New verb: print_families: print families to screen
New verb: plot_slip: plot cumulative slip for one or more families
New config parameter: clustering_algorithm to select the algorithm for building event families. Currently supported options are shared and UPGMA (default: shared)
family_numbers argument is no more mandatory (default: all)
- argument added to map_families and plot_timespans
Config parameter trace_average_from_normalized_traces renamed to normalize_traces_before_averaging
plot_timespans: possibility to sort by family_number
New options for map_families to select a map style and a zoom level for the map tiles
New option --minevents (-m) for many verbs, to select families with a minimum number of events
Support for events with no location
Bugfix: plot_timespans: correctly plot x time axis when sort by time

v0.3 - 2021-11-08

New verb: build_templates
New option: cc_allow_negative to search for anticorrelated events
New progressbar, using tqdm
plot_families:
- show average trace
- pan/zoom traces using arrows
- show/hide theoretical arrivals using ‘a’ (command line option removed)
- show event origin time as y-label
- show trace mean CC
- also shift theoretical arrivals when aligning traces
Bugfix: last family was not read from family file

v0.2 - 2021-09-24

Mostly a bugfix release with a slightly improved trace plotting.

Bugfix: scan_catalog could not run properly due to missing variable
Bugfix: detrend traces before filtering
plot_families: print number of events and station-event distance

v0.1 - 2021-09-16

Initial release, not yet feature complete

How to Cite

If you used Requake for a scientific paper, please cite it as:

Satriano, C. (2024). Requake: Repeating earthquakes search and analysis (X.Y). doi: 10.5281/ZENODO.10832204

Please replace X.Y with the Requake version number you used.

You can also cite the following abstract presented at the 2016 AGU Fall Meeting:

Satriano, C., Doucet, A. & Bouin, M.-P. (2021). Probing the creep rate along the Lesser Antilles Subduction Zone through repeating earthquakes. In AGU Fall Meeting Abstracts (Vol. 2021, pp. T25A-0167), bibcode: 2021AGUFM.T25A0167S

References

[1]

Naoki Uchida. Detection of repeating earthquakes and their application in characterizing slow fault slip. Progress in Earth and Planetary Science, May 2019. doi:10.1186/s40645-019-0284-z.

[2]

Thomas C. Hanks and Hiroo Kanamori. A moment magnitude scale. Journal of Geophysical Research: Solid Earth, 84(B5):2348–2350, May 1979. doi:10.1029/jb084ib05p02348.

[3]

Robert M. Nadeau and Lane R. Johnson. Seismological studies at parkfield vi: moment release rates and estimates of source parameters for small repeating earthquakes. Bulletin of the Seismological Society of America, 88(3):790–814, June 1998. doi:10.1785/bssa0880030790.

[4]

N. M. Beeler, D. L. Lockner, and S. H. Hickman. A simple stick-slip and creep-slip model for repeating earthquakes and its implication for microearthquakes at parkfield. Bulletin of the Seismological Society of America, 91(6):1797–1804, December 2001. doi:10.1785/0120000096.

[5]

J D Eshelby. The determination of the elastic field of an ellipsoidal inclusion, and related problems. Proc. R. Soc. Lond., 241(1226):376–396, August 1957. doi:10.1098/rspa.1957.0133.