tiebenn.tools.sb_tools module

tiebenn.tools.sb_tools.calculate_njobs(loop)[source]

Calculates the number of parallel jobs to be run at parallelizations

Parameters:: loop – The variable which will determine the number of simultaneous jobs. It can be e.g. the number of stations

tiebenn.tools.sb_tools.deepdenoiser(stream)[source]

DeepDenoiser (Zhu et al. 2019) as implemented on Seisbench.

Parameters:: stream (stream) – Obspy stream with the waveforms to be denoised
Returns:: The stream with denoised waveforms
Return type:: stream_denoise (stream)

tiebenn.tools.sb_tools.get_streams_fdsn_bulk(start_time, data, mult_windows, secs_before)[source]

Uses ObsPy FDSN client to generate a bulk request to download streams with 60 second long waveforms for a set of stations.

Parameters:

start_time (UTCDateTime) – Start of requested time window.
data (dict) – Station information dictionary.
mult_windows (bool) – If True, multiple time windows are used.
secs_before (float or list) – Time to subtract from start_time when mult_windows is False.

Returns:

Dictionary with the retrieved station streams.

Return type:

stream_output (dict)

tiebenn.tools.sb_tools.get_streams_sds(start_time, data, secs_before, mult_windows, sds_dir)[source]

Uses ObsPy SDS client to download ObsPy streams for a set of stations.

Parameters:

start_time (UTCDateTime) – Start of requested time window.
data (dict) – Dictionary with station information.
secs_before (float or list) – Seconds to subtract from event time (if mult_windows is False).
mult_windows (bool) – If True, uses a different time window (start_time - 10 to start_time + 60).
sds_dir (str) – Root directory of the SDS archive.

Returns:

Dictionary with retrieved station streams.

Return type:

streams (dict)

tiebenn.tools.sb_tools.parallel_phase_picking(station_streams, starttime, picker, model, start_list)[source]

Run phase picking in parallel for each station (stream) and each time window alignment.

Parameters:

station_streams (dict) – Keys are station names, values are ObsPy Stream objects
starttime (UTCDateTime) – The event time
picker (str) – Name of the phase picker to use
model – SeisBench phase picking model
start_list (list) – List of seconds before event time to try (e.g., [0, 2, 5, 10])

Returns:

A list of tuples (station, start, predictions, outputs)

Return type:

results (list)

tiebenn.tools.sb_tools.picks_mulwin(streams, start, starttime, picker, model)[source]

Phase picks on stations for single-windows.

Parameters:

streams (ObsPy Stream) – ObsPy Stream where the phases will be detected
start (int or float) – Seconds before event time for waveform time window to start
starttime (ObsPy UTCDateTime) – Event start time
picker (str) – Name of the phase picker to be used: either EQTransformer or PhaseNet
model (SeisBench PhasePicker) – The actual SeisBench model

Returns:

Probability time series of P-, S, and noise (for PhaseNet) or detection (for EQTransformer) outputs (SeisBench Outputs): Pick information. Time stamp, maximum probability, peak time, etc

Return type:

predictions (SeisBench Predictions)

tiebenn.tools.sb_tools.picks_sb(ev_time, ev_lon, ev_lat, data, max_dist, client, picker, velmod, secs_before, phase_assoc, pick_sel, mult_windows, plotpicks, min_detections=3, denoise=True, sds_dir='/')[source]

Produces probability functions and picks for P- and S-wave arrivals using SeisBench.

Parameters:

ev_time (str) – Origin time of the event. Format: yyyy-mm-dd hh:mm:ss.ss
ev_lon (float) – Longitude of the located event
ev_lat (float) – Latitude of the located event
data (dict) – A dictionary with the nearest stations (ObsPy streams) to the event which contain useful channels for phase-picking
max_dist (float) – The stations used to seismic detection and P- and S-traveltime picks will be within this radius (in km)
client (str) – Choose between SDS or FDSN ObsPy client to retrieve waveforms. If SDS, make sure the SDS-directory is correctly defined
picker (str) – The pretrained model for phase picking: SeisBench_Phasenet or SeisBench_EQTransformer
velmod (int) – The velocity model used for phase association with PyOcto
secs_before (float or list) – If the picks will be predicted on multiple windows, this parameter is a list of seconds to be substracted from the event time. Otherwise, it is a constant value to be substracted from the event time
phase_assoc (str) – Implements a phase associator to the detected phase picks. Options are the GaMMA associator (https://github.com/AI4EPS/GaMMA) and PyOcto (https://github.com/yetinam/pyocto)
pick_sel (char) – If picks are calculated on multiple time windows, the selected criterion is applied for selecting picks. Options are: max_prob (for a given station, it looks for the pick(s) –P and/or S– on that station at the time window where the probability was maximal), min_res (for a given station, it selects the pick(s) –P and/or S– on time windows where the residual has the minimum value. This option is only available for the phase association with PyOcto)
mult_windows (bool) – If true, it will fetch waveforms for pick prediction with SeisBench starting at different times with respect to the event time
plotpicks (bool) – If True it will plot for each station with detections the event waveforms on the three components and their P- and S-arrivals. It will also plot the time series of the probabilities of an event, of a P- and a S-arrival. The phase association will also be plotted under an individual directory
min_detections (int) – For a given max_dist, it will define the minimum amount of stations on which the event was detected. If this minimum amount of detections is not achieved, the station radius will be increased and the detection process will be repeated. Value must be >= 3. Default = 3
denoise (bool) – If True it will apply the deep neural network DeepDenoiser (Zhu et al. 2019) as implemented on Seisbench (https://github.com/seisbench/seisbench) to denoise the retrieved waveforms before phase picking. Default is True

Returns:

.csv files containing, for each station with sucessfully detected arrival times, all the detections and picking results. <station><datetime>.pdf (optional): .pdf files with plots of the waveforms, P- and S- probability functions and picks on each station

Return type:

<station>_<datetime>_prediction_results.csv

tiebenn.tools.sb_tools.picks_singwin(stream, picker, model)[source]

Phase picks on stations for single-windows.

Parameters:

stream (ObsPy Stream) – ObsPy Stream where the phases will be detected
picker (str) – Name of the phase picker to be used: either EQTransformer or PhaseNet
model (SeisBench PhasePicker) – The actual SeisBench model

Returns:

Probability time series of P-, S, and noise (for PhaseNet) or detection (for EQTransformer) outputs (SeisBench Outputs): Pick information. Time stamp, maximum probability, peak time, etc

Return type:

predictions (SeisBench Predictions)

tiebenn.tools.sb_tools.process_client_waveforms(client, data, start_t, end_t)[source]

Process waveform retrieval for a single client. It builds a bulk request for all stations associated with the client and retrieves the corresponding waveforms.

Parameters:

client (str) – ObsPy client to request waveform bulk
data (dict) – A dictionary with information about the stations. Example: {‘LANDS’: {‘network’: ‘SX’, ‘channels’: [‘HHN’, ‘HHE’, ‘HHZ’], ‘coords’: [51.526, 12.163, 115.0], ‘client’: ‘BGR’, ‘epic_distance’: ‘53.61’}
start_t (str) – Start of requested time window. Format: yyyy-mm-dd hh:mm:ss.ss
end_t (str) – End of requested time window. Format: yyyy-mm-dd hh:mm:ss.ss

Returns:

A dictionary with the retrieved streams which may be empty if no data is retrieved

Return type:

stream (dict)

tiebenn.tools.sb_tools.process_station_sds(st, station_info, start_t, end_t, sds_dir)[source]

Helper function to retrieve waveform data for a single station using the SDS client.

Parameters:

st (str) – Station name.
station_info (dict) – Dictionary with station information.
start_t (UTCDateTime) – Start time for data retrieval.
end_t (UTCDateTime) – End time for data retrieval.
sds_dir (str) – Root directory of the SDS archive.

Returns:

(station name, retrieved ObsPy Stream or None if fetching failed)

Return type:

tuple

tiebenn.tools.sb_tools.select_picks(outputs, outputs_assoc, phase_assoc, mode)[source]

When the multiple-window approach (Park et al. 2023) is employed, phase picks will likely be associated in different time windows for a single station. Afterwards, only one(pair) P- and/or S-pick must be selected for depth estimation.

Parameters:

outputs (dict) – Dictionary of predicted picks for each station
outputs_assoc (dict) – Dictionary of predicted picks which were associated to the event of interest
phase_assoc (char) – The utilized phase associator. Current options are GaMMA and PyOcto. The latter exports a residual for each associated phase
mode (char) – How a P- or S-phase will be selected. Options are ‘max_prob’, in which the selected phase will be that at the time window which had the highest probability; and ‘min_res’, in which the selected phase will be that at the time window which had the lowest residual. This option is only available if the PyOcto phase associator was employed

Returns:

A Pandas dataframe with the selected picks for depth estimation

Return type:

outputs_final (Pandas dataframe)

tiebenn.tools.sb_tools.waveform_preprocessing(stream, denoise, distance)[source]

Waveform processing with ObsPy

Parameters:: stream (ObsPy Stream) – Stream with station channels to be pre-processed. Dead channels are removed, masked channels are split, data are detrended, bandpass-filtered and tapered
Returns:: Pre-processed ObsPy stream
Return type:: stream (ObsPy stream)