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) 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:
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:
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:
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.
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.
Two very common choices are:
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.
SourceSpec can read event information (event ID, location, origin time) in the following formats:
Event information can also be stored in the SAC file header (header fields: EVLA , EVLO , EVDP , O , KEVNM ).
Phase picks for P and S waves can be read from one of the following formats:
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 (coordinates, instrumental response) can be provided in one of the following formats:
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 .
The SourceSpec main code, source_spec will produce the following output files ( EVID is replaced by the actual event ID):
The following plots will be created, in png, pdf or svg format:
As an option, station maps can be created (requires Cartopy):
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.
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:
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) source model:
where the three parameters to determine are:
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:
Starting from the inverted parameters $M_0$ ( $M_w$ ), $fc$, $t^*$ and following the equations in Madariaga (2011) and Lancieri (2012), other quantities are computed for each station:
As a bonus, local magnitude $M_l$ can be computed as well.
Event summaries (mean, weighted mean, percentiles) are computed from single station estimates. For mean and weighted mean estimation, outliers are rejected based on the interquartile range rule.
See the official documentation for more details.
Example three-component trace plot (in velocity), showing noise and S-wave windows
Example displacement spectrum for noise and S-wave, including inversion results
SourceSpec requires at least Python 3.7. All the required dependencies will be downloaded and installed during the setup process.
The following command will automatically create an Anaconda environment named sourcespec , install the required packages and install the latest version of SourceSpec via pip :
conda env create --file https://raw.githubusercontent.com/SeismicSource/sourcespec/main/sourcespec_conda_env.yml If you want a different name for your environment, use:
conda env create -n YOUR_ENV_NAME --file https://raw.githubusercontent.com/SeismicSource/sourcespec/main/sourcespec_conda_env.yml Activate the environment with:
conda activate sourcespec (or conda activate YOUR_ENV_NAME )
To keep SourceSpec updated run:
pip install --upgrade sourcespec from within your environment.
The latest release of SourceSpec is available on the Python Package Index.
You can install it easily through pip :
pip install sourcespec To upgrade from a previously installed version:
pip install --upgrade sourcespec Download the latest release from the releases page, in zip or tar.gz format, then:
pip install sourcespec-X.Y.zip pip install sourcespec-X.Y.tar.gz Where, X.Y is the version number (e.g., 1.2 ). You don't need to uncompress the release files yourself.
If you need a recent feature that is not in the latest release (see the unreleased section in CHANGELOG), you want to use the more recent development snapshot from the SourceSpec GitHub repository.
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/sourcespec.git Run this command again, from times to times, to keep SourceSpec updated with the development version.
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/sourcespec.git git clone git@github.com:SeismicSource/sourcespec.git (avoid using the "Download ZIP" option from the green "Code" button, since version number is lost).
Then, go into the sourcespec main directory and install the code in "editable mode" by running:
pip install -e . You can keep your local SourceSpec repository updated by running git pull from times to times. Thanks to pip 's "editable mode", you don't need to reinstall SourceSpec after each update.
The official SourceSpec documentation can be find at sourcespec.readthedocs.io.
Several sample runs are available in the sourcespec_testruns repository.
Join the SourceSpec Discussions and feel free to ask!
I'm very open to contributions: if you have new ideas, please open an Issue. Don't hesitate sending me pull requests with new features and/or bugfixes!
If you used SourceSpec for a scientific paper, please cite it as:
Satriano, C. (2024). SourceSpec – Earthquake source parameters from P- or S-wave displacement spectra (X.Y). doi: 10.5281/ZENODO.3688587
Please replace X.Y with the SourceSpec version number you used.
You can also cite the following abstract presented at the 2016 AGU Fall Meeting:
Satriano, C., Mejia Uquiche, A. R., & Saurel, J. M. (2016). Spectral estimation of seismic moment, corner frequency and radiated energy for earthquakes in the Lesser Antilles. In AGU Fall Meeting Abstracts (Vol. 2016, pp. S13A-2518), bibcode: 2016AGUFM.S13A2518S
A, probably incomplete, list of papers that used SourceSpec can be found in the Citing Literature section of the documentation. If you have used SourceSpec in a publication and would like to have it listed, please let me know.