_images/SplitPy_logo.png

Classes

splitpy defines the following base classes:

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:

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