SourceSpec API

SourceSpec has a modular structure. Each module corresponds to a specific function or class of functions.

Main modules

SourceSpec main modules are presented below, following the logical order on which they’re used within source_spec.py.

source_spec.py

Earthquake source parameters from inversion of P- or S-wave spectra.

copyright

2012 Claudio Satriano <satriano@ipgp.fr>

2013-2014 Claudio Satriano <satriano@ipgp.fr>,: Emanuela Matrullo <matrullo@geologie.ens.fr>, Agnes Chounet <chounet@ipgp.fr>

2015-2023 Claudio Satriano <satriano@ipgp.fr>

license

CeCILL Free Software License Agreement v2.1 (http://www.cecill.info/licences.en.html)

source_spec.main()[source]: Main routine for source_spec.

ssp_parse_arguments

Argument parser for sourcespec.

copyright: 2021-2023 Claudio Satriano <satriano@ipgp.fr>
license: CeCILL Free Software License Agreement v2.1 (http://www.cecill.info/licences.en.html)

ssp_parse_arguments.parse_args(progname)[source]: Parse command line arguments.

ssp_setup

Setup functions for sourcespec.

copyright

2012 Claudio Satriano <satriano@ipgp.fr>

2013-2014 Claudio Satriano <satriano@ipgp.fr>,: Emanuela Matrullo <matrullo@geologie.ens.fr>, Agnes Chounet <chounet@ipgp.fr>

2015-2023 Claudio Satriano <satriano@ipgp.fr>

license

CeCILL Free Software License Agreement v2.1 (http://www.cecill.info/licences.en.html)

ssp_setup.configure(options, progname, config_overrides=None)[source]

Parse command line arguments and read config file.

Parameters

options (object) – An object containing command line options
progname (str) – The name of the program
config_overrides (dict) – A dictionary with parameters that override or extend those defined in the config file

Returns

A Config object with both command line and config options.

ssp_setup.move_outdir(config)[source]: Move outdir to a new dir named from evid (and optional run_id).

ssp_setup.remove_old_outdir(config)[source]: Try to remove the old outdir.

ssp_setup.save_config(config)[source]: Save config file to output dir.

ssp_setup.setup_logging(config, basename=None, progname='source_spec')[source]

Set up the logging infrastructure.

This function is typically called twice: the first time without basename and a second time with a basename (typically the eventid). When called the second time, the previous logfile is renamed using the given basename.

ssp_read_traces

Read traces in multiple formats of data and metadata.

copyright

2012 Claudio Satriano <satriano@ipgp.fr>

2013-2014 Claudio Satriano <satriano@ipgp.fr>,: Emanuela Matrullo <matrullo@geologie.ens.fr>
2015-2023 Claudio Satriano <satriano@ipgp.fr>,: Sophie Lambotte <sophie.lambotte@unistra.fr>

license

CeCILL Free Software License Agreement v2.1 (http://www.cecill.info/licences.en.html)

ssp_read_traces.read_traces(config)[source]: Read traces, store waveforms and metadata.

ssp_process_traces

Trace processing for sourcespec.

copyright

2012 Claudio Satriano <satriano@ipgp.fr>

2013-2014 Claudio Satriano <satriano@ipgp.fr>,: Emanuela Matrullo <matrullo@geologie.ens.fr>

2015-2023 Claudio Satriano <satriano@ipgp.fr>

license

CeCILL Free Software License Agreement v2.1 (http://www.cecill.info/licences.en.html)

ssp_process_traces.process_traces(config, st)[source]: Remove mean, deconvolve and ignore unwanted components.

ssp_build_spectra

Build spectral objects.

copyright

2012 Claudio Satriano <satriano@ipgp.fr>

2013-2014 Claudio Satriano <satriano@ipgp.fr>,: Emanuela Matrullo <matrullo@geologie.ens.fr>, Agnes Chounet <chounet@ipgp.fr>

2015-2023 Claudio Satriano <satriano@ipgp.fr>

license

CeCILL Free Software License Agreement v2.1 (http://www.cecill.info/licences.en.html)

exception ssp_build_spectra.SpectrumIgnored(message, reason)[source]

ssp_build_spectra.build_spectra(config, st)[source]

Build spectra and the spec_st object.

Computes P- or S-wave (displacement) spectra from accelerometers and velocimeters, uncorrected for anelastic attenuation, corrected for instrumental constants, normalized by geometrical spreading.

ssp_plot_traces

Trace plotting routine.

copyright: 2015-2023 Claudio Satriano <satriano@ipgp.fr>
license: CeCILL Free Software License Agreement v2.1 (http://www.cecill.info/licences.en.html)

class ssp_plot_traces.ScalarFormatter(*args: Any, **kwargs: Any)[source]

ssp_plot_traces.plot_traces(config, st, ncols=None, block=True)[source]

Plot traces in the original instrument unit (velocity or acceleration).

Display to screen and/or save to file.

ssp_inversion

Spectral inversion routines for sourcespec.

copyright

2012 Claudio Satriano <satriano@ipgp.fr>

2013-2014 Claudio Satriano <satriano@ipgp.fr>,: Emanuela Matrullo <matrullo@geologie.ens.fr>, Agnes Chounet <chounet@ipgp.fr>

2015-2023 Claudio Satriano <satriano@ipgp.fr>

license

CeCILL Free Software License Agreement v2.1 (http://www.cecill.info/licences.en.html)

ssp_inversion.spectral_inversion(config, spec_st, weight_st)[source]: Inversion of displacement spectra.

ssp_radiated_energy

Compute radiated energy from spectral integration.

copyright

2012 Claudio Satriano <satriano@ipgp.fr>

2013-2014 Claudio Satriano <satriano@ipgp.fr>,: Emanuela Matrullo <matrullo@geologie.ens.fr>, Agnes Chounet <chounet@ipgp.fr>

2015-2023 Claudio Satriano <satriano@ipgp.fr>

license

CeCILL Free Software License Agreement v2.1 (http://www.cecill.info/licences.en.html)

ssp_radiated_energy.radiated_energy(config, spec_st, specnoise_st, sspec_output)[source]: Compute radiated energy, using eq. (3) in Lancieri et al. (2012).

ssp_local_magnitude

Local magnitude calculation for sourcespec.

copyright

2012 Claudio Satriano <satriano@ipgp.fr>

2013-2014 Claudio Satriano <satriano@ipgp.fr>,: Emanuela Matrullo <matrullo@geologie.ens.fr>

2015-2023 Claudio Satriano <satriano@ipgp.fr>

license

CeCILL Free Software License Agreement v2.1 (http://www.cecill.info/licences.en.html)

ssp_local_magnitude.local_magnitude(config, st, proc_st, sspec_output)[source]: Compute local magnitude from max absolute W-A amplitude.

ssp_summary_statistics

Post processing of station source parameters.

copyright: 2012-2023 Claudio Satriano <satriano@ipgp.fr>
license: CeCILL Free Software License Agreement v2.1 (http://www.cecill.info/licences.en.html)

ssp_summary_statistics.compute_summary_statistics(config, sspec_output)[source]: Compute summary statistics from station spectral parameters.

ssp_output

Output functions for source_spec.

copyright

2012 Claudio Satriano <satriano@ipgp.fr>

2013-2014 Claudio Satriano <satriano@ipgp.fr>,: Emanuela Matrullo <matrullo@geologie.ens.fr>

2015-2023 Claudio Satriano <satriano@ipgp.fr>

license

CeCILL Free Software License Agreement v2.1 (http://www.cecill.info/licences.en.html)

ssp_output.write_output(config, sspec_output)[source]: Write results into different formats.

ssp_residuals

Spectral residual routine for sourcespec.

copyright

2013-2014 Claudio Satriano <satriano@ipgp.fr>,: Agnes Chounet <chounet@ipgp.fr>

2015-2023 Claudio Satriano <satriano@ipgp.fr>

license

CeCILL Free Software License Agreement v2.1 (http://www.cecill.info/licences.en.html)

ssp_residuals.spectral_residuals(config, spec_st, sspec_output)[source]

Compute spectral residuals with respect to an average spectral model.

Saves a stream of residuals to disk using pickle.

ssp_plot_spectra

Spectral plotting routine.

copyright

2012 Claudio Satriano <satriano@ipgp.fr>

2013-2014 Claudio Satriano <satriano@ipgp.fr>,: Emanuela Matrullo <matrullo@geologie.ens.fr>

2015-2023 Claudio Satriano <satriano@ipgp.fr>

license

CeCILL Free Software License Agreement v2.1 (http://www.cecill.info/licences.en.html)

ssp_plot_spectra.plot_spectra(config, spec_st, specnoise_st=None, ncols=None, stack_plots=False, plot_type='regular')[source]

Plot spectra for signal and noise.

Display to screen and/or save to file.

ssp_plot_params_stats

Plot parameter statistics.

copyright: 2022-2023 Claudio Satriano <satriano@ipgp.fr>
license: CeCILL Free Software License Agreement v2.1 (http://www.cecill.info/licences.en.html)

ssp_plot_params_stats.box_plots(config, sspec_output)[source]: Show parameter statistics through box plots.

ssp_plot_stations

Station plotting routine.

copyright: 2018-2023 Claudio Satriano <satriano@ipgp.fr>
license: CeCILL Free Software License Agreement v2.1 (http://www.cecill.info/licences.en.html)

ssp_plot_stations.plot_stations(config, sspec_output)[source]: Plot station map, color coded by magnitude or fc.

ssp_html_report

Generate an HTML report for source_spec.

copyright: 2021-2023 Claudio Satriano <satriano@ipgp.fr>
license: CeCILL Free Software License Agreement v2.1 (http://www.cecill.info/licences.en.html)

ssp_html_report.html_report(config, sspec_output)[source]: Generate an HTML report.

Other modules

These modules, in alphabetical order, are used by the main modules.

ssp_correction

Spectral station correction calculated from ssp_residuals.

copyright

2013-2014 Claudio Satriano <satriano@ipgp.fr>,: Agnes Chounet <chounet@ipgp.fr>

2015-2023 Claudio Satriano <satriano@ipgp.fr>

license

CeCILL Free Software License Agreement v2.1 (http://www.cecill.info/licences.en.html)

ssp_correction.station_correction(spec_st, config)[source]

Correct spectra using station-average residuals.

Residuals are obtained from a previous run.

ssp_data_types

Classes for spectral inversion routines.

copyright: 2017-2023 Claudio Satriano <satriano@ipgp.fr>
license: CeCILL Free Software License Agreement v2.1 (http://www.cecill.info/licences.en.html)

class ssp_data_types.Bounds(config, spec, initial_values)[source]

Bounds for bounded spectral inversion.

property bounds: Get bounds for minimize() as sequence of (min, max) pairs.

get_bounds_curve_fit()[source]: Get bounds for curve-fit().

class ssp_data_types.InitialValues(Mw_0=None, fc_0=None, t_star_0=None)[source]: Initial values for spectral inversion.

class ssp_data_types.OrderedAttribDict[source]: An ordered dictionary whose values can be accessed as classattributes.

class ssp_data_types.SourceSpecOutput[source]

The output of SourceSpec.

find_outliers(key, n)[source]

Find outliers using the IQR method.

    Q1-n*IQR   Q1   median  Q3    Q3+n*IQR
                |-----:-----|
o      |--------|     :     |--------|    o  o
                |-----:-----|
outlier         <----------->            outliers
                     IQR

If n is None, then the above check is skipped. Nan and inf values are also marked as outliers.

mean_uncertainties()[source]: Return a dictionary of mean uncertainties.

mean_values()[source]: Return a dictionary of mean values.

percentiles_uncertainties()[source]: Return a dictionary of percentile uncertainties.

percentiles_values()[source]: Return a dictionary of percentile values.

reference_summary_parameters()[source]: Return a dictionary of reference summary parameters, each being a SummaryStatistics() object.

reference_uncertainties()[source]: Return a dictionary of reference uncertainties.

reference_values()[source]: Return a dictionary of reference values.

weighted_mean_uncertainties()[source]: Return a dictionary of weighted mean uncertainties.

weighted_mean_values()[source]: Return a dictionary of weighted mean values.

class ssp_data_types.SpectralParameter(id, name=None, units=None, value=None, uncertainty=None, lower_uncertainty=None, upper_uncertainty=None, confidence_level=None, format=None)[source]

A spectral parameter measured at one station.

value_uncertainty()[source]: Return value and uncertainty as 3-element tuple.

class ssp_data_types.StationParameters(id, instrument_type=None, latitude=None, longitude=None, hypo_dist_in_km=None, epi_dist_in_km=None, azimuth=None)[source]

The parameters describing a given station (e.g., its id and location) and the spectral parameters measured at that station.

Spectral parameters are provided as attributes, using SpectralParameter() objects.

class ssp_data_types.SummarySpectralParameter(id, name=None, units=None, format=None)[source]: A summary spectral parameter comprising one ore more summary statistics.

class ssp_data_types.SummaryStatistics(type, value=None, uncertainty=None, lower_uncertainty=None, upper_uncertainty=None, confidence_level=None, lower_percentage=None, mid_percentage=None, upper_percentage=None, nobs=None, message=None, format=None)[source]

A summary statistics (e.g., mean, weighted_mean, percentile), along with its uncertainty.

compact_uncertainty()[source]: Return uncertainty in a compact form.

ssp_grid_sampling

A class for sampling a parameter space over a grid.

Sampling can be performed by several approaches. The class provides optimal solutions, uncertainties and plotting methods.

copyright: 2022-2023 Claudio Satriano <satriano@ipgp.fr>
license: CeCILL Free Software License Agreement v2.1 (http://www.cecill.info/licences.en.html)

class ssp_grid_sampling.GridSampling(misfit_func, bounds, nsteps, sampling_mode, params_name, params_unit)[source]

A class for sampling a parameter space over a grid.

Sampling can be performed by several approaches. The class provides optimal solutions, uncertainties and plotting methods.

property conditional_misfit

Compute conditional misfit along each dimension.

Conditional misfit is computed by fixing the other parameters to their optimal value.

property conditional_peak_widths: Find width of conditional misfit around its minimum.

grid_search()[source]: Sample the misfit function by simple grid search.

plot_conditional_misfit(config, label)[source]: Plot conditional misfit for each parameter.

plot_misfit_2d(config, plot_par_idx, label)[source]: Plot a 2D conditional misfit map.

property values_1d: Extract a 1D array of parameter values along one dimension.

ssp_grid_sampling.peak_width(x, peak_idx, rel_height, negative=False)[source]

Find width of a single peak at a given relative height.

rel_height: float parameter between 0 and 1: 0 means the base of the curve and 1 the peak value (Note: this is the opposite of scipy.peak_widths)

ssp_spectral_model

Spectral model and objective function.

copyright

2012 Claudio Satriano <satriano@ipgp.fr>

2013-2014 Claudio Satriano <satriano@ipgp.fr>,: Emanuela Matrullo <matrullo@geologie.ens.fr>, Agnes Chounet <chounet@ipgp.fr>

2015-2023 Claudio Satriano <satriano@ipgp.fr>

license

CeCILL Free Software License Agreement v2.1 (http://www.cecill.info/licences.en.html)

ssp_spectral_model.objective_func(xdata, ydata, weight)[source]: Objective function generator for bounded inversion.

ssp_spectral_model.spectral_model(freq, Mw, fc, t_star, alpha=1.0)[source]

Spectral model.

\[Y_{data} = M_w + \frac{2}{3} \left[ - \log_{10} \left( 1+\left(\frac{f}{f_c}\right)^2 \right) - \pi \, f t^* \log_{10} e \right]\]

see Theoretical Background for a detailed derivation of this model.

ssp_qml_output

QuakeML output for source_spec.

license: CeCILL Free Software License Agreement, Version 2.1 (http://www.cecill.info/index.en.html)

class ssp_qml_output.SSPContainerTag(*args: Any, **kwargs: Any)[source]: Container for nested custom tags.

class ssp_qml_output.SSPExtra(*args: Any, **kwargs: Any)[source]: Container for custom tags.

class ssp_qml_output.SSPTag(*args: Any, **kwargs: Any)[source]: Custom tag object.

ssp_radiation_pattern

Compute radiation pattern.

license: CeCILL Free Software License Agreement v2.1 (http://www.cecill.info/licences.en.html)

ssp_radiation_pattern.radiation_pattern(strike, dip, rake, takeoff_angle, azimuth, wave)[source]

Body wave radiation pattern.

From Lay-Wallace, page 340.

ssp_sqlite_output

SQLite output for source_spec.

license: CeCILL Free Software License Agreement v2.1 (http://www.cecill.info/licences.en.html)

ssp_util

Utility functions for sourcespec.

license: CeCILL Free Software License Agreement v2.1 (http://www.cecill.info/licences.en.html)

ssp_util.bsd(Mo_in_N_m, ra_in_m)[source]

Compute Brune stress drop in MPa.

Madariaga (2009), doi:10.1007/978-1-4419-7695-6_22, eq. 27

ssp_util.get_vel(lon, lat, depth_in_km, wave, config)[source]: Get velocity at a given point from NLL grid, config or taup model.

ssp_util.hypo_dist(trace)[source]: Compute hypocentral and epicentral distance (in km) for a trace.

ssp_util.mag_to_moment(magnitude)[source]: Convert magnitude to moment.

ssp_util.moment_to_mag(moment)[source]: Convert moment to magnitude.

ssp_util.quality_factor(travel_time_in_s, t_star_in_s)[source]: Compute quality factor from travel time and t_star.

ssp_util.remove_instr_response(trace, pre_filt=(0.5, 0.6, 40.0, 45.0))[source]

Remove instrument response from a trace.

Trace is converted to the sensor units (m for a displacement sensor, m/s for a short period or broadband velocity sensor, m/s**2 for a strong motion sensor).

Parameters

trace (Trace) – Trace to be corrected.
pre_filt (tuple of four floats) – Pre-filter frequencies (None means no pre-filtering).

ssp_util.select_trace(stream, traceid, instrtype)[source]: Select trace from stream using traceid and instrument type.

ssp_util.source_radius(fc_in_hz, vs_in_m_per_s)[source]

Compute source radius in meters.

Madariaga (2009), doi:10.1007/978-1-4419-7695-6_22, eq. 31

ssp_wave_arrival

Arrival time calculation for sourcespec.

license: CeCILL Free Software License Agreement v2.1 (http://www.cecill.info/licences.en.html)

ssp_wave_arrival.add_arrivals_to_trace(trace, config)[source]

Add P and S arrival times and takeoff angles to trace.

Uses the theoretical arrival time if no pick is available or if the pick is too different from the theoretical arrival.

config

Config class for sourcespec.

license: CeCILL Free Software License Agreement v2.1 (http://www.cecill.info/licences.en.html)

class config.Config[source]: Config class for sourcespec.

kdtree

Grid importance sampling using a k-d tree.

license: CeCILL Free Software License Agreement v2.1 (http://www.cecill.info/licences.en.html)

savefig

Save Matplotlib figure. Optimize PNG format using PIL.

license: CeCILL Free Software License Agreement v2.1 (http://www.cecill.info/licences.en.html)

savefig.savefig(fig, figfile, fmt, quantize_colors=True, **kwargs)[source]: Save Matplotlib figure. Optimize PNG format using PIL.

spectrum

A Spectrum() class defined as a modification of the ObsPy class Trace().

Provides the high-level function do_spectrum() and the low-level function do_fft().

license: CeCILL Free Software License Agreement v2.1 (http://www.cecill.info/licences.en.html)

class spectrum.Spectrum(*args: Any, **kwargs: Any)[source]

spectrum.do_fft(signal, delta)[source]: Compute the complex Fourier transform of a signal.

spectrum.do_spectrum(trace)[source]: Compute the spectrum of an ObsPy Trace object.

clipping_detection

Check trace for clipping using kernel density estimation of the trace= amplitude values.

Two methods are available:

clipping_score(): compute a trace clipping score based on the shape of the kernel density estimation.
clipping_peaks(): check if trace is clipped, based on the number of peaks in the kernel density estimation;

copyright

2023 Claudio Satriano <satriano@ipgp.fr>,: Kris Vanneste <kris.vanneste@oma.be>

license

CeCILL Free Software License Agreement v2.1 (http://www.cecill.info/licences.en.html)

clipping_detection.clipping_peaks(trace, sensitivity=3, clipping_percentile=10, debug=False)[source]

Check if a trace is clipped, based on the number of peaks in the kernel density estimation of the trace amplitude values.

The algorithm is based on the following steps:

The trace is demeaned.
A kernel density estimation is computed on the trace amplitude values.
The kernel density estimation is weighted by the distance from the zero mean amplitude value, using a parabolic function, between 1 and 5.
Peaks are detected in the weighted kernel density estimation. The sensitivity of the peak detection algorithm is controlled by the sensitivity parameter, based on which a minimum prominence threshold is set.
The trace is considered clipped if there is at least one peak in the amplitude range corresponding to the clipping_percentile parameter.

Parameters

trace (obspy.core.trace.Trace) – Trace to check.
sensitivity (int) – Sensitivity level, from 1 (least sensitive) to 5 (most sensitive). (default: 3). The sensitivity level controls the minimum prominence threshold used for peak detection in the kernel density estimation. See the scipy.signal.find_peaks() documentation for more details.
clipping_percentile (float, between 0 and 100) – Percentile of trace amplitude range (expressed as percentage) to check for clipping. Default is 10, which means that the 10% highest and lowest values of the trace amplitude will be checked for clipping. A value of 0 means that no clipping check will be performed.
debug (bool) – If True, plot trace, samples histogram and kernel density.

Returns

trace_clipped (bool) – True if trace is clipped, False otherwise.
properties (dict) – Dictionary with the properties used for the clipping detection. The dictionary contains the following keys:
- npeaks (int): number of peaks found in the kernel density
- npeaks_clipped (int): number of peaks found in the kernel density that are considered clipped
- peaks (numpy.ndarray): list of peaks found in the kernel density
- prominences (numpy.ndarray): list of prominences of the peaks found in the kernel density

clipping_detection.clipping_score(trace, remove_baseline=False, debug=False)[source]

Compute a trace clipping score based on the shape of the kernel density estimation of the trace amplitude values.

The algorithm is based on the following steps:

The trace is detrended and demeaned. Optionally, the trace baseline can be removed.
A kernel density estimation is computed on the trace amplitude values.
Two weighted kernel density functions are computed:
- a full weighted kernel density, where the kernel density is weighted by the distance from the zero mean amplitude value, using a 8th order power function between 1 and 100.
- a weighted kernel density without the central peak, where the kernel density is weighted by the distance from the zero mean amplitude value, using a 8th order power function between 0 and 100.
In both cases, the weight gives more importance to samples far from the zero mean value. In the second case, the central peak is ignored.
The score, ranging from 0 to 100, is the sum of the squared weighted kernel density without the central peak, normalized by the sum of the squared full weighted kernel density. The score is 0 if there is no additional peak beyond the central peak.

Parameters

trace (Trace) – Trace to check for clipping.
remove_baseline (bool, optional) – If set, remove the trace baseline before computing the score.
debug (bool, optional) – If set, plot the trace, the samples histogram, the kernel density (unweighted and weighted), the kernel baseline model, and the misfit. Default is False.

Returns

clipping_score – Clipping score, in percentage.

Return type

float

Note

Distorted traces (e.g., signals with strong baselines) can also get a high clipping score. To avoid this, the trace baseline can be removed.

A debug mode is available to plot the trace, the samples histogram, the kernel density (unweighted and weighted), the kernel baseline model, and the misfit.

plot_sourcepars

plot_sourcepars.py

1D or 2D plot of source parameters from a sqlite parameter file.

license: CeCILL Free Software License Agreement v2.1 (http://www.cecill.info/licences.en.html)

plot_sourcepars.calc_r2(x, y, yerr, a, b, f)[source]: Coefficient of determination.

plot_sourcepars.stress_drop_curve_Er_mw(delta_sigma, vs, rho, mw)[source]

Constant stress drop curve in Er vs Mw.

Madariaga (2009), doi:10.1007/978-1-4419-7695-6_22, eq. 33., page 374.

plot_sourcepars.stress_drop_curve_fc_mw(delta_sigma, vs, mw, b=-0.5)[source]

Constant stress drop curve in fc vs Mw.

Chounet et al. (2013), https://hal.science/hal-03965701, eq. 9, page 9.