Classes¶

splitpy defines the following base classes:

Split
PickPlot
DiagPlot

The class Split contains attributes and methods for the analysis of teleseismic shear-wave splitting from three-component seismograms.

The class PickPlot defines figure handles for a picking window showing the seismograms and the predicted teleseismic shear-wave phase arrivals. This figure is interactive and new picks can be generated to refine the analysis.

The class DiagPlot defines figure handles for a diagnostic figure showing a summary of the splitting results. It can be called after each application of the split.analyze method to show the summary of the analysis as a figure. This figure can also be saved as a .png file.

Split¶

class splitpy.classes.Split(sta)¶

A Split object contains dictionary attributes that associate station information with single event (i.e., earthquake) metadata, corresponding raw and rotated seismograms and splitting results.

Note

The object is initialized with the sta field only, and other attributes are added to the object as the analysis proceeds.

sta¶

Object containing station information - from stdb database.

Type: object

meta¶

Object of metadata information for single event.

Type: Meta

dataZNE¶

Object containing raw trace data in Trace format

Type: Data

dataLQT¶

Object containing rotated trace data in Trace format

Type: Data

add_event(event, gacmin=85.0, gacmax=120.0, phase='SKS', returned=False)¶

Adds event metadata to Split object as Meta object.

Parameters: event (event) – Event metadata

add_data(stream, returned=False, new_sr=5.0)¶

Adds stream of raw data as object attribute

Parameters

stream (Stream) – Stream container for NEZ seismograms
returned (bool) – Whether or not to return the accept attribute

Returns

accept – Whether or not the object is accepted for further analysis

Return type

bool

download_data(client, stdata=[], ndval=nan, new_sr=5.0, dts=120.0, returned=False, verbose=False)¶

Downloads seismograms based on event origin time and P phase arrival and adds as object attribute.

Parameters

client (Client) – Client object
ndval (float) – Fill in value for missing data
new_sr (float) – New sampling rate (Hz)
dts (float) – Time duration (sec)
stdata (List) – Station list
returned (bool) – Whether or not to return the accept attribute

Returns

accept – Whether or not the object is accepted for further analysis

Return type

bool

rotate(align=None)¶

Rotates 3-component seismograms from vertical (Z), east (E) and north (N) to longitudinal (L), radial (Q) and tangential (T) components of motion. Note that the method ‘rotate’ from obspy.core.stream.Stream is used for the rotation 'ZNE->ZRT' and 'ZNE->LQT'. Rotation 'ZNE->PVH' is implemented separately here due to different conventions.

Parameters: align (str) – Alignment of coordinate system for rotation (‘ZNE’ or ‘LQT’)

calc_snr(t1=None, dt=30.0)¶

Calculates signal-to-noise ratio on either Z, L or P component

Parameters

t1 (UTCDateTime) – Pick time of arrival (sec)
dt (float) – Duration (sec)
fmin (float) – Minimum frequency corner for SNR filter (Hz)
fmax (float) – Maximum frequency corner for SNR filter (Hz)

snrq¶

Signal-to-noise ratio on vertical component (dB)

Type: float

snrh¶

Signal-to-noise ratio on radial component (dB)

Type: float

analyze(t1=None, t2=None, verbose=False)¶

Calculates the shear-wave splitting parameters based on two alternative method: the Rotation-Correlation (RC) method and the Silver-Chan (SC) method. Each set of results is stored in a Dictionary as attributes of the split object.

Parameters

t1 (UTCDateTime) – Start time of picking window
t2 (UTCDateTime) – End time of picking window

RC_res¶

Object containing results of Rotation-Correlation method

Type: Result

SC_res¶

Object containing results of Silver-Chan method

Type: Result

is_null(snrTlim=3.0, verbose=False)¶

Determines if splitting result is a Null result

Parameters

snrTlim (float) – Threshold for snr on T component
ds (int) – Number of spaces to print out to screen (verbiage)

null¶

Boolean for Null result

Type: bool

get_quality(verbose=False)¶

Determines the quality of the estimate (either Null or non-Null) based on ratio of delay times and difference in fast axis directions between Rotation-Correlation and Silver-Chan methods

Parameters: ds (int) – Number of spaces to print out to screen (verbiage)

quality¶

String representing quality of estimate (‘Good’, ‘Fair’, ‘Poor’)

Type: str

display_results(ds=0)¶

Prints out best fitting results to screen

Parameters: ds (int) – Number of spaces to print out to screen (verbiage)

display_meta(ds=0)¶

Prints out content of metadata to screen

Parameters: ds (int) – Number of spaces to print out to screen (verbiage)

display_null_quality(ds=0)¶

Prints out null and quality estimates to screen

Parameters: ds (int) – Number of spaces to print out to screen (verbiage)

save(file)¶

Saves Split object to file

Parameters: file (str) – File name for split object

Meta¶

class splitpy.classes.Meta(sta, event, gacmin=85.0, gacmax=120.0, phase='SKS', maxdt=4.0, ddt=0.1, dphi=1.0)¶

A Meta object contains attributes associated with the station-event data for a single Teleseismic event.

time¶

Origin time of earthquake

Type: UTCDateTime

dep¶

Depth of hypocenter (km)

Type: float

lon¶

Longitude coordinate of epicenter

Type: float

lat¶

Latitude coordinate of epicenter

Type: float

mag¶

Magnitude of earthquake

Type: float

gac¶

Great arc circle between station and epicenter (degrees)

Type: float

epi_dist¶

Epicentral distance between station and epicenter (km)

Type: float

baz¶

Back-azimuth - pointing to earthquake from station (degrees)

Type: float

az¶

Azimuth - pointing to station from earthquake (degrees)

Type: float

slow¶

Horizontal slowness of phase

Type: float

inc¶

Incidence angle of phase at surface

Type: float

Result¶

class splitpy.classes.Result(Emat, trQ_c, trT_c, trFast, trSlow, phi, dtt, phi_min, edtt, ephi, errc)¶

A Result object contains attributes associated with the result of a single splitting analysis. These are equally applicable to the RC or SC method - see analyze().

Emat¶

Error minimization matrix

Type: ndarray

trQ_c¶

Corrected radial (Q) component

Type: Trace

trT_c¶

Corrected transverse (T) component

Type: Trace

trFast¶

Corrected Fast component

Type: Trace

trSlow¶

Corrected Slow component

Type: Trace

phi¶

Azimuth of fast axis (deg)

Type: float

dtt¶

Delay time between fast and slow axes (sec)

Type: float

phi_min¶

Azimuth used in plotting method

Type: float

ephi¶

Error on azimuth of fast axis (deg)

Type: float

edtt¶

Error on delay time between fast and slow axes (sec)

Type: float

errc¶

Error contours on Emat

Type: float

PickPlot¶

class splitpy.classes.PickPlot(split)¶

A PickPlot object contains figure handles and method to plot seismic data for picking/refining the SKS time window. The figure displays the LQT seismograms and predicted arrival times for common shear-wave arrivals in the time window. The figure can be picked to refine the time window for calculating the splitting results.

Note

The object is initialized with a Split object, which is temporarily stored as an attribute. All the split attributes are therefore available to the PickPlot object for plotting.

split¶

Split object containing attributes after analysis has been carried out.

Type: Split object

fp¶

List of figure handles ([fig, ax1, ax2, ax3])

Type: List

plot_LQT_phases(dts, t1=None, t2=None)¶

Plots rotated three-components of motion for picking.

Parameters

tt (TauPyModel) – Taup object containing travel time and phase info
dts (float) – Time interval (?)
t1 (UTCDateTime) – Start time of picking window
t2 (UTCDateTime) – End time of picking window

ll¶

List of axvline objects for plotting the start and end times of the picking window.

Type: List

update_LQT(tp1, tp2)¶

Updates LQT figure with newly picked times

Parameters

tp1 (float) – New start time of picking window
tp2 (float) – New end time of picking window

save(file)¶

Saves current figure into file

Parameters: file (str) – File name for diagnostic figure

DiagPlot¶

class splitpy.classes.DiagPlot(split)¶

A DiagPlot object contains figure handles and methods to plot the diagnostic figure, which displays the LQT seismograms, the corrected/un-corrected seismograms, the particle motions, the minimization matrix and a text box with a summary of the analysis - for each of the two analysis methods (‘RC’ or ‘SC’)

Note

The object is initialized with a Split object, which is temporarily stored as an attribute. All the split attributes are therefore available to the DiagPlot object for plotting.

split¶

Split object containing attributes after analysis has been carried out.

Type: Split object

fd¶

List of figure handles ([fig, ax0, axt, axRC1, axRC2, axRC3, axRC4, axSC1, axSC2, axSC3, axSC4])

Type: List

plot_diagnostic(t1=None, t2=None)¶

Plots diagnostic window with estimates from both ‘RC’ and ‘SC’ methods

Parameters

t1 (UTCDateTime) – Start time of picking window
t2 (UTCDateTime) – End time of picking window

save(file)¶

Saves current figure into file

Parameters: file (str) – File name for diagnostic figure

GUI classes¶

Module containing the main GUI widget classes based on PyQt5:

Pick
Keep
Save
Repeat

These classes simply open a Qt5 message box and contain a boolean attribute corresponding the anwer to simple yes/no buttons.

class splitpy.gui.Pick¶: GUI message box for picking new SKS analysis window

class splitpy.gui.Keep¶: GUI message box for keeping current split estimates

class splitpy.gui.Save¶: GUI message box for overwriting saved split

class splitpy.gui.Repeat¶: GUI message box for repeating a saved result

Modules¶

calc¶

splitpy.calc.split_SilverChan(trQ, trT, baz, t1, t2, maxdt, ddt, dphi)¶

Calculates splitting based on the minimization of energy on the corrected transverse component (Silver and Chan, 1990)

Parameters

trQ (Trace) – Radial component seismogram
trT (Trace) – Tangential component seismogram
baz (float) – Back-azimuth - pointing to earthquake from station (degrees)
t1 (UTCDateTime) – Start time of picking window
t2 (UTCDateTime) – End time of picking window

Returns

Ematrix (ndarray) – Matrix of T component energy
trQ_c (Trace) – Trace of corrected radial component of motion
trT_c (Trace) – Trace of corrected tangential component of motion
trFast (Trace) – Trace of corrected fast direction of motion
trSlow (Trace) – Trace of corrected slow direction of motion phiSC : float Azimuth of fast axis (deg)
dttSC (foat) – Delay time between fast and slow axes (sec)
phi_min (float) – Azimuth used in plotting routine

splitpy.calc.split_RotCorr(trQ, trT, baz, t1, t2, maxdt, ddt, dphi)¶

Calculates splitting based on the maximum correlation between corrected radial and tangential components of motion

Parameters

trQ (Trace) – Radial component seismogram
trT (Trace) – Tangential component seismogram
baz (float) – Back-azimuth - pointing to earthquake from station (degrees)
t1 (UTCDateTime) – Start time of picking window
t2 (UTCDateTime) – End time of picking window

Returns

Ematrix (ndarray) – Matrix of T component energy
trQ_c (Trace) – Trace of corrected radial component of motion
trT_c (Trace) – Trace of corrected tangential component of motion
trFast (Trace) – Trace of corrected fast direction of motion
trSlow (Trace) – Trace of corrected slow direction of motion phiSC : float Azimuth of fast axis (deg)
dttSC (foat) – Delay time between fast and slow axes (sec)
phi_min (float) – Azimuth used in plotting routine

splitpy.calc.tshift(trace, tt)¶

Shifts a Trace object

Parameters

trace (Trace) – Seismogram to apply shift
tt (float) – Lag time for shifting

Returns

rtrace – Shifted version of trace

Return type

Trace

splitpy.calc.split_dof(tr)¶

Determines the degrees of freedom to calculate the confidence region of the misfit function

Parameters

tr (Trace) – Seismogram

Returns

dof (float) – Degrees of freedom
From Walsh, JGR, 2013

splitpy.calc.split_errorSC(tr, t1, t2, q, Emat, maxdt, ddt, dphi)¶

Calculate error bars based on a F-test and a given confidence interval q

Parameters

tr (Trace) – Seismogram
t1 (UTCDateTime) – Start time of picking window
t2 (UTCDateTime) – End time of picking window
q (float) – Confidence level
Emat (ndarray) – Energy minimization matrix

Returns

err_dtt (float) – Error in dt estimate (sec)
err_phi (float) – Error in phi estimate (degrees)
err_contour (ndarray) – Error contour for plotting

splitpy.calc.split_errorRC(tr, t1, t2, q, Emat, maxdt, ddt, dphi)¶

Calculates error bars based on a F-test and a given confidence interval q.

Note

This version uses a Fisher transformation for correlation-type misfit.

Parameters

tr (Trace) – Seismogram
t1 (UTCDateTime) – Start time of picking window
t2 (UTCDateTime) – End time of picking window
q (float) – Confidence level
Emat (ndarray) – Energy minimization matrix

Returns

err_dtt (float) – Error in dt estimate (sec)
err_phi (float) – Error in phi estimate (degrees)
err_contour (ndarray) – Error contour for plotting

utils¶

splitpy.utils.traceshift(trace, tt)¶: Function to shift traces in time given travel time

splitpy.utils.list_local_data_stn(lcldrs=<class 'list'>, sta=None, net=None, altnet=[])¶

Function to take the list of local directories and recursively find all data that matches the station name

Parameters

lcldrs (List) – List of local directories
sta (Dict) – Station metadata from StDb
net (str) – Network name
altnet (List) – List of alternative networks

Returns

fpathmatch – Sorted list of matched directories

Return type

List

splitpy.utils.parse_localdata_for_comp(comp='Z', stdata=[], sta=None, start=<class 'obspy.core.utcdatetime.UTCDateTime'>, end=<class 'obspy.core.utcdatetime.UTCDateTime'>, ndval=nan)¶

Function to determine the path to data for a given component and alternate network

Parameters

comp (str) – Channel for seismogram (one letter only)
stdata (List) – Station list
sta (Dict) – Station metadata from StDb data base
start (UTCDateTime) – Start time for request
end (UTCDateTime) – End time for request
ndval (float or nan) – Default value for missing data

Returns

err (bool) – Boolean for error handling (False is associated with success)
st (Stream) – Stream containing North, East and Vertical components of motion

splitpy.utils.download_data(client=None, sta=None, start=None, end=None, stdata=[], ndval=nan, new_sr=0.0, verbose=False)¶

Function to build a stream object for a seismogram in a given time window either by downloading data from the client object or alternatively first checking if the given data is already available locally.

Note

Currently only supports NEZ Components!

Parameters

client (Client) – Client object
sta (Dict) – Station metadata from StDb data base
start (UTCDateTime) – Start time for request
end (UTCDateTime) – End time for request
stdata (List) – Station list
ndval (float or nan) – Default value for missing data

Returns

err (bool) – Boolean for error handling (False is associated with success)
trN (Trace) – Trace of North component of motion
trE (Trace) – Trace of East component of motion
trZ (Trace) – Trace of Vertical component of motion