swspy.splitting package

Submodules

swspy.splitting.forward_model module

exception swspy.splitting.forward_model.CustomError

Bases: Exception

swspy.splitting.forward_model.add_splitting(ZNE_st, phi_from_N, dt, back_azi, event_inclin_angle_at_station, snr=None)

Function to add splitting to waveforms in ZNE notation.

Parameters

phi_from_Nfloat

Angle of fast direction, in degrees from N.

dtfloat

Delay time between fast and slow S-waves, in seconds.

back_azifloat

Back-azimuth from source to receiver, in degrees from N.

event_inclin_angle_at_stationfloat

Inclination of ray at station, in degrees from vertical up.

phi_from_upfloat

Angle of fast direction, in degrees from vertical up. Optional. Default = 0 degrees.

snrfloat

Signal-to-noise-ratio of output source-time function. Optional. If not None, then will add white gaussian noise to data.

swspy.splitting.forward_model.create_src_time_func(dur, fs, src_pol_from_N=0, src_pol_from_up=0, src_freq=10.0, wavelet='ricker', t_src=1.0)

Function to create synthetic source time function.

Parameters

fsfloat

Sampling rate, in Hz.

src_pol_from_Nfloat

Source polarisation from North, in degrees. Optional. Default = 0 degrees.

src_pol_from_upfloat

Source polarisation from vertical up, in degrees. Optional. Default = 0 degrees.

src_freqfloat

Dominant source frequency, in Hz. Optional. Default is 10 Hz.

waveletstr

Type of wavelet to use for the source-time function. Optional. Default is ricker. Other options not currently implemented.

t_srcfloat

Time, in seconds, from the beginning of the trace when the source-time function peaks. Optional. Default = 1 s.

swspy.splitting.split module

exception swspy.splitting.split.CustomError

Bases: Exception

swspy.splitting.split.calc_dof(y)

Finds the number of degrees of freedom using a noise trace, y. Uses definition as in Walsh2013. Note: Doesn’t apply any form of smoothing filter (f(t,h)).

class swspy.splitting.split.create_splitting_object(st, nonlinloc_event_path=None, event_uid=None, stations_in=[], S_phase_arrival_times=[], back_azis_all_stations=[], receiver_inc_angles_all_stations=[])

Bases: object

Class to create splitting object to perform shear wave splitting on.

Parameters:

  • sts (obspy Stream object) – Obspy stream containing all the waveform data for all the stations and channels to perform the splitting on.

  • nonlinloc_event_path (str) – Path to NonLinLoc .grid0.loc.hyp file for the event.

overall_win_start_pre_fast_S_pick

Overall window start time in seconds before S pick.

Type:

float (default = 0.1 s)

overall_win_start_post_fast_S_pickfloat (default = 0.2 s)

Overall window start time in seconds after S pick.

win_S_pick_tolerancefloat (default = 0.1 s)

Time before and after S pick to not allow windows to start within (in seconds). For example, start windows start at: S arrival time - (<overall_win_start_pre_fast_S_pick> + <win_S_pick_tolerance>) And end times windows start at: S arrival time + <win_S_pick_tolerance> + <overall_win_start_post_fast_S_pick>

rotate_step_degfloat (default = 2.0 degrees)

Rotation step size of phi in degrees for the grid search in phi-delay-time space.

max_t_shift_sfloat (default = 0.1 s)

The maximum time shift the data by in seconds.

n_winint (default = 10)

The number of window start and end times to pick. Currently implemented as constant window step sizes within the specified range, as defined by <overall_win_start_pre_fast_S_pick> amd <win_S_pick_tolerance>. Therefore, will calculate splitting for n_win^2 windows in total.

perform_sws_analysis : Function to perform shear-wave splitting analysis.
plot : Function to plot the shear-wave splitting results.
save_result : Function to save sws results to file.
save_wfs : Function to save uncorrected and corrected waveforms to file.
perform_sws_analysis(coord_system='ZNE', sws_method='EV', return_clusters_data=True, num_threads=2)

Function to perform splitting analysis. Works in LQT coordinate system as then performs shear-wave-splitting in 3D.

Parameters:

  • coord_system (str) – Coordinate system to perform analysis in. Options are: LQT, ZNE. Will convert splitting angles back into coordinates relative to ZNE whatever system it performs the splitting within. Default = ZNE.

  • sws_method (str) – Method with which to calculate sws parameters. Options are: EV, EV_and_XC. EV - Eigenvalue method (as in Silver and Chan (1991), Teanby (2004), Walsh et al. (2013)). EV_and_XC - Same as EV, except also performs cross-correlation for automation approach, as in Wustefeld et al. (2010). Default is EV.

  • return_clusters_data (bool) – If True, returns clustering data information. This is primarily used for plotting. Default is False.

  • num_threads (int) – Number of threads to use for parallel computing. Default is to use all available threads on the system.

Returns:

self.sws_result_df – A pandas DataFrame containing the key splitting results.

Return type:

pandas DataFrame

perform_sws_analysis_multi_layer(coord_system='ZNE', multi_layer_method='explicit', num_threads=2)
Function to perform splitting analysis for a multi-layered medium. Currently

only a 2-layer medium is supported. Works in LQT coordinate system, therefore

supporting shear-wave-splitting in 3D. Currently doesn’t support any method other than <sws_method> = EV and doesn’t support returning clustered data. Method assumes that apparent delay-time is longer than fast S-wave arrival duration.

Parameters:

  • coord_system (str) – Coordinate system to perform analysis in. Options are: LQT, ZNE. Will convert splitting angles back into coordinates relative to ZNE whatever system it performs the splitting within. Default = ZNE.

  • multi_layer_method (str) – Multi-layer method algorithm to apply. Two options are: 1. explicit - Applies layers individually, one at a time. Efficient and far fewer free parameters, as computation scales as (n_phi * n_dt) * n-layers. 2. direct - Applies layers directly together in the inversion. Computationally expensive relative to explicit method, with many free parameters, as computation scales as (n_phi * n_dt) ^ n-layers.

  • num_threads (int) – Number of threads to use for parallel computing. Default is to use all available threads on the system.

Returns:

  • self.sws_result_df (pandas DataFrame) – A pandas DataFrame containing the key splitting results for an apparent splitting measurement (i.e. assuming only one layer).

  • self.sws_multi_layer_result_df pandas DataFrame – A pandas DataFrame containing the key splitting results for hte multi-layer result.

plot(outdir=None, suppress_direct_plotting=False)

Function to perform plotting…

save_result(outdir='/home/docs/checkouts/readthedocs.org/user_builds/swspy/checkouts/latest/docs/source')

Function to save output. Output is a csv file with all the splitting data for the event, for all stations. Saves result as <event_uid>, to <outdir>.

save_wfs(outdir='/home/docs/checkouts/readthedocs.org/user_builds/swspy/checkouts/latest/docs/source')

Function to save waveforms outputs. Outputs are unccorrected and corrected waveforms for all events. Saves result as <event_uid>.mseed, to <outdir>.

swspy.splitting.split.direct_multi_layer_inv_fun(params, theta_app, alpha_app)

Function combining eqns 1-3 from Ozalaybey and Savage (1994). Note: All angles in radians.

swspy.splitting.split.find_nearest(array, value)
swspy.splitting.split.find_nearest_2D(array, value)
swspy.splitting.split.ftest(data, dof, alpha=0.05, k=2, min_max='min')

Finds the confidence bounds value associated with data. Note that this version uses the minumum of the data by default. :param data: Data to process. :type data: np array :param dof: Number of degrees of freedom. :type dof: int :param alpha: Confidence level (e.g. if alpha = 0.05, then 95pc confidence level found). :type alpha: float :param k: Number of parameters (e.g. phi, dt). :type k: int :param min_max: Whether performs ftest on min or max of data. :type min_max: specific str

Returns:

conf_bound – Value of the confidence bounds for the specified confidence level, alpha.

Return type:

float

swspy.splitting.split.remove_splitting(st_ZNE_uncorr, phi, dt, back_azi, event_inclin_angle_at_station, return_BPA=False, src_pol=0.0, return_FS=True)

Function to remove SWS from ZNE data for a single station. Note: Consistency in this function with sws measurement. Uses T in x-direction and Q in y direction convention.

Parameters:

  • st_LQT_uncorr (obspy stream object) – Stream data for station corresponding to splitting parameters.

  • phi (float) – Splitting angle, for LQT coordinates.

  • dt (float) – Fast-slow delay time (lag) for splitting.

  • back_azi (float) – Back azimuth angle from reciever to event in degrees from North.

  • event_inclin_angle_at_station (float) – Inclination angle of arrival at receiver, in degrees from vertical down.

  • return_BPA (bool) – If True, will return obspy stream with Z,N,E and B,P,A channels (as in Walsh (2013)). Optional. Default = False.

  • src_pol (float) – If <return_BPA> = True, then uses src_pol to calculate the polarisiation and null (P,A) vectors. Units are degrees clockwise from North.

  • return_FS (bool) – If True, will return obspy stream with F (fast) and S (slow) channels also included. Optional. Default = True.

Returns:

st_ZNE_corr – Corrected data, in ZNE coordinates (unless <return_BPA> = True, then will also output BPA channels too).

Return type:

obspy stream object

Module contents

Submodule for undertaking splitting analysis.