SourceSpec

Earthquake source parameters from P- or S-wave displacement spectra

[![changelog-badge]][changelog-link] [![PyPI-badge]][PyPI-link] [![license-badge]][license-link] [![docs-badge]][docs-link] [![DeepWiki-badge]][DeepWiki-link] [![DOI-badge]][DOI-link]

Description

SourceSpec is a collection of command line tools to compute earthquake source parameters (seismic moment, corner frequency, radiated energy, source size, static stress drop, apparent stress) from the inversion of P-wave and S-wave displacement spectra recorded at one or more seismic stations. SourceSpec also computes attenuation parameters (t-star, quality factor) and, as a bonus, local magnitude.

See [Madariaga (2011)][Madariaga2011] for a primer on earthquake source parameters and scaling laws.

Go to section Theoretical background below to get more information on how the code works. More details are available on the official SourceSpec [documentation].

SourceSpec is written in Python and requires a working Python environment to run (see Installation below). However, since SourceSpec is based on command line, you don't have to know how to code in Python to use it.

The SourceSpec package is made of several command line tools:

source_spec: Compute earthquake source parameters from the inversion of P- or S-wave spectra.
source_model: Direct modelling of P- or S-wave spectra, based on user-defined earthquake source parameters.
source_residuals: Compute station residuals from source_spec output.
clipping_detection: Test the clipping detection algorithm.
plot_sourcepars: 1D or 2D plot of source parameters from a sqlite parameter file.

Getting Started

For the impatient

Note that the default config parameters are suited for a M<5 earthquake recorded within ~100 km. Adjust win_length, noise_pre_time, the frequency bands (bp_freqmin_*, bp_freqmax_*, freq1_*, freq2_*), and the bounds on fc and t_star, according to your problem.

Use case: miniSEED + StationXML + QuakeML

If you have seismic recordings in [miniSEED] format (e.g., traces.mseed), metadata in [StationXML] format (e.g., station.xml) and event information in [QuakeML] format (e.g., event.xml), then:

Generate a config file via source_spec -S;
Edit the config file variable station_metadata to point to station.xml file;
Run source_spec -t traces.mseed -q event.xml.

Use case: SAC + PAZ + SourceSpec Event File

If you have seismic recordings in [SAC] format (e.g., in a directory named sac_data), metadata as [SAC polezero (PAZ)] (e.g., in a directory named paz) and event information in any format, then:

Generate a config file via source_spec -S;
Edit the config file variable station_metadata to point to the paz directory;
Generate a sample [SourceSpec Event File] using source_spec -y; this will create a file named ssp_event.yaml;
Edit the file ssp_event.yaml with your event information;
Run source_spec -t sac_data -H ssp_event.yaml.

Command line arguments

After successfully installed SourceSpec (see Installation below), you can get help on the command line arguments used by each code by typing from your terminal:

source_spec -h

(or source_model -h, or source_residuals -h).

source_spec and source_model require you to provide the path to seismic traces via the --trace_path command line argument (see File formats below).

Information on the seismic event can be stored in the trace header ([SAC] format), or provided through a [QuakeML] file (--qmlfile) or or, alternatively (--hypocenter), through a [SourceSpec Event File], a [HYPO71] file, or a [HYPOINVERSE-2000] file. See File formats below for more information on the supported file formats.

Configuration file

source_spec and source_model require a configuration file. The default file name is source_spec.conf, other file names can be specified via the --configfile command line argument.

You can generate a sample configuration file through:

source_spec -S

Take your time to go through the generated configuration file (named source_spec.conf): the comments within the file will guide you on how to set up the different parameters.

File Formats

Trace formats

SourceSpec can read all the [trace formats supported by ObsPy][obspy_trace_formats].

Two very common choices are:

[miniSEED]
[SAC]

The SAC format can carry additional information in its header, like event location and origin time, phase picks, instrument sensitivity.

Input trace files can be provided --through the -t option-- as a list of files, as a directory containing the files, or as a TAR(GZ) or ZIP archive containing the files.

Event formats

SourceSpec can read event information (event ID, location, origin time) in the following formats:

[SourceSpec Event File]: this file can contain additional event information, such as magnitude, moment tensor or focal mechanism
[QuakeML]: this file can contain additional event information, such as magnitude, moment tensor or focal mechanism. If phase picks are available, they will be read as well
[HYPO71]
[HYPOINVERSE-2000]: if phase picks are available, they will be read as well

Event information can also be stored in the [SAC file header] (header fields: EVLA, EVLO, EVDP, O, KEVNM).

Note: Any depth value provided in the event file or in the SAC header can be overridden using the command line option --depth.

Phase pick formats

Phase picks for P and S waves can be read from one of the following formats:

[QuakeML]
[HYPO71]
[HYPOINVERSE-2000]

Phase picks can also be stored in the [SAC file header], using the header fields A and T0 through T9. A pick label can be specified (header fields KA and KT0 through KT9) to identify the pick; the pick label can be a standard 4-characters SAC label (e.g., "IPU0", " S 1") or a label starting with "P" or "S" (lowercase or uppercase, e.g., "P", "pP", "Pg", "S", "Sn"). Picks with labels that cannot be parsed by SourceSpec will be ignored. If no label is specified, then SourceSpec will assume that A is the P-pick and T0 is the S-pick.

Station metadata formats

Station metadata (coordinates, instrumental response) can be provided in one of the following formats:

[StationXML]
[Dataless SEED]
[SEED RESP]
[SAC polezero (PAZ)]

Note that SEED RESP and PAZ formats do not contain station coordinates, which should therefore be in the trace header (traces in SAC format).

The station metadata file name or file directory is provided in the configuration file through the parameter station_metadata.

Alternatively, instrument sensitivity can be provided in the SAC header or as a constant in the configuration file. In both cases, use the configuration parameter sensitivity.

Output files

The SourceSpec main code, source_spec will produce the following output files (EVID is replaced by the actual event ID):

EVID.ssp.yaml: [YAML] file containing the estimated spectral parameters (summary values and per station values)
EVID.ssp.out (deprecated): text file containing the estimated spectral parameters (summary values and per station values)
EVID.ssp.log: log file in text format (including the command line arguments, for [reproducibility])
EVID.ssp.conf: the input config file (for [reproducibility])
EVID.residuals.hdf5: station residuals in [HDF5] format
EVID.spectra.hdf5: (optional) spectra in [HDF5] format
EVID.ssp.h: hypocenter file in [HYPO71] format with the estimated moment magnitude (only if an input HYPO71 file is provided)
EVID.xml: updated [QuakeML] file with the results of the SourceSpec inversion (only if an input QuakeML file is provided)

The following plots will be created, in png, pdf or svg format:

EVID.traces.png[.pdf,.svg]: trace plots
EVID.ssp.png[.pdf,.svg]: spectral plots
EVID.sspweight.png[.pdf,.svg]: spectral weight plots
EVID.boxplot.png[.pdf,.svg]: [box plots][box_plot] for the earthquake source parameters retrieved at each station
Misfit plots, when using "grid search" or "importance sampling" for the spectral inversion

As an option, station maps can be created (requires [Cartopy]):

EVID.map_mag.png[.pdf,.svg]: station map with symbols colored by estimated moment magnitude
EVID.map_fc.png[.pdf,.svg]: station map with symbols colored by estimated corner frequency

As an option, the retrieved source parameters (per station and summary) can be appended to a [SQLite] database, whose path is defined in the configuration file.

Finally, always as an option, source_spec can generate a report in HTML format.

Theoretical Background

For each station, the code computes P- or S-wave displacement amplitude spectra for each component (e.g., Z, N, E), then combines the component spectra through the root sum of squares:

$$ S(f) = \sqrt{S^2_z(f) + S^2_n(f) + S^2_e(f)} $$

where $f$ is frequency and $S_x(f)$ is the P- or S-wave spectrum for component $x$.

It then inverts spectra for a 3-parameter [Brune (1970)][Brune1970] source model:

$$ S(f) = C \cdot \frac{M_0}{1+(f/f_c)^2} \cdot e^{-\pi f t^*} $$

where the three parameters to determine are:

the seismic moment $M_0$
the corner frequency $f_c$
the attenuation parameter $t^*$

and $C$ is a coefficient containing geometrical spreading, radiation pattern, seismic wave speed and medium density.

The inversion is performed in moment magnitude $M_w$ units (logarithmic amplitude). Different inversion algorithms can be used:

TNC: [truncated Newton algorithm] (with bounds)
LM: [Levenberg-Marquardt algorithm] (warning: [Trust Region Reflective alg

Sourcespec

Install / Use

README