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-2022 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-2022 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-2022 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-2022 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-2022 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-2022 Claudio Satriano <satriano@ipgp.fr>

license

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

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-2022 Claudio Satriano <satriano@ipgp.fr>

license

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

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-2022 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-2022 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, sourcepar)[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-2022 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, sourcepar)[source]

Compute local magnitude from max absolute W-A amplitude.

ssp_averages

Post processing of station source parameters.

copyright

2012-2022 Claudio Satriano <satriano@ipgp.fr>

license

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

ssp_averages.compute_averages(config, sourcepar)[source]

Compute average source parameters, find outliers

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-2022 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, sourcepar)[source]

Write results to a plain text file and/or to a SQLite database file.

ssp_residuals

Spectral residual routine for sourcespec.

copyright
2013-2014 Claudio Satriano <satriano@ipgp.fr>,

Agnes Chounet <chounet@ipgp.fr>

2015-2022 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, sourcepar)[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-2022 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 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, sourcepar)[source]

Show parameter statistics through box plots.

ssp_plot_stations

Station plotting routine.

copyright

2018-2022 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, sourcepar)[source]

Plot station map, color coded by magnitude or fc.

ssp_html_report

Generate an HTML report for source_spec.

copyright

2021-2022 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, sourcepar)[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-2022 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-2022 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.SourceParameters[source]

Source parameters for all stations.

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.

class ssp_data_types.StationSourceParameters(statId, params, errors)[source]

Source parameters for one station.

ssp_grid_sampling

A class for sampling a parameter space over a grid.

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

copyright

2022 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 perfomred 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 mininum.

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 paramter 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-2022 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.

copyright

2016-2022 Claudio Satriano <satriano@ipgp.fr>

license

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

ssp_radiation_pattern

Compute radiation pattern.

copyright

2021-2022 Claudio Satriano <satriano@ipgp.fr>

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_util

Utility functions for sourcespec.

copyright

2012-2022 Claudio Satriano <satriano@ipgp.fr>

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 NonLinLoc grid or config.

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

copyright

2012-2022 Claudio Satriano <satriano@ipgp.fr>

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.

copyright

2013-2022 Claudio Satriano <satriano@ipgp.fr>

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.

copyright

2022 Claudio Satriano <satriano@ipgp.fr>

license

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

savefig

Save Matplotlib figure. Optimize PNG format using PIL.

copyright

2022 Claudio Satriano <satriano@ipgp.fr>

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 funciton do_fft().

copyright

2012-2022 Claudio Satriano <satriano@ipgp.fr>

license

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

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.