tiebenn.tools.nicetools module

tiebenn.tools.nicetools.azimuthal_gaps(event_lat, event_lon, station_coords)[source]

Calculates the primary and secondary azimuthal gaps given an event location and station coordinates.

Parameters:

  • event_lat (float) – Epicentral latitude

  • event_lon (float) – Epicentral longitude

  • station_coords (list) – List of station coordinates tuples: [(lat1, lon1), (lat2, lon2), (lat3, lon3), …]

Returns:

(primary_gap, secondary_gap:

Return type:

tuple

tiebenn.tools.nicetools.azimuthal_uniformity_index(azimuths)[source]

Calculate the Azimuthal Uniformity Index (AUI) for a set of station azimuths.

Parameters:

azimuths (NumPy array) – Array of station azimuths

Returns:

Azimuthal Uniformity Index

Return type:

aui (float)

tiebenn.tools.nicetools.calculate_azimuths(epicenter, stations)[source]

Calculates azimuths from the epicenter to each station.

Parameters:

  • epicenter (tuple) – (epicenter_latitude, epicenter_longitude)

  • stations (list) – List of (lat, lon) tuples of the coordinates of each station

Returns:

Array of station azimuths

Return type:

azimuths (NumPy array)

tiebenn.tools.nicetools.calculate_lqs(loc_file, sta_file)[source]

Calculates the Location Quality Score (LQS) metric, as in the work of Ramos et al. (2025, in preparation). This metric describes the quality of automatic locations based on location parameters and station network distribution in the vicinities of the epicenter.

Parameters:
Returns:

A dataframe with the original event datetime (from the catalog) and the datetime calculated by NonLinLoc, the LQS metric of the event and the eight normalized parameters used for the calculation of the LQS.

Return type:

parameters (Pandas Dataframe)

tiebenn.tools.nicetools.chan_comma(chanlist)[source]

Transforms the channel list for a given station in a string of channels, each separated by a comma. This is the multiple channel format for a FDSN waveform request

Parameters:

chanlist (list) – List of channels from which waveforms will be downloaded

Returns:

String of channels separated by a comma

Return type:

string (str)

tiebenn.tools.nicetools.create_input_for_phassoc(outputs, seconds_before)[source]

Slight modification of the outputs with phase picks, as necessary for the phase association

Parameters:

  • outputs (dict) – The predicted phases/arrival times obtained from SeisBench for each station

  • seconds_before (list) – List of the seconds before the event

Returns:

Modfied structure of the outputs dictionary

Return type:

outputs_for_phassoc (dict)

tiebenn.tools.nicetools.decimate(phasepicks, data, ev_lon, ev_lat, az_bin, dist_bin, max_bin)[source]

Detect regions covered by clusters of stations within specific bins and set a maximum amount of stations within each bin, removing the excess.

Parameters:

  • phasepicks (list) – list of phase picks

  • data (dict) – dictionary that contains—among others—the station coordinates for each station

  • ev_lon (float) – event’s longitude

  • ev_lat (float) – event’s latitude

  • az_bin (float) – azimuthal bins

  • dist_bin (float) – epicentral distance bins

  • max_bin (int) – maximum amount of stations allowed per bin

Returns:

list of stations with picks, where there’s a maximum of stations per bin

Return type:

filtered_phasepicks (list)

tiebenn.tools.nicetools.generate_csv(outputs, data, snr_data, ev_time)[source]

Generates CSV files with pick detections

Parameters:

  • outputs (dict) – The predicted phases/arrival times obtained from SeisBench for each station

  • data (dict) – A dictionary with the nearest stations (ObsPy streams) to the event which contain useful channels for phase-picking

  • snr_data (dict) – Dictionary with the signal-to-noise ratio for each pick at each station

  • ev_time (str) – ev_time (str): Origin time of the event. Format: yyyy-mm-dd hh:mm:ss.ss

Returns:

prediction result files in CSV format for each station

tiebenn.tools.nicetools.get_snr(data, picks, wlen)[source]

Estimates the signal to noise ratio (SNR) of a seismogram. Adapted from the EQTransformer repository (https://github.com/smousavi05/EQTransformer)

Parameters:

  • data (ObsPy Stream) – Stream with waveforms and metadata for a given station

  • picks (dict) – Sample point where a specific phase arrives

  • wlen (int, positive) – The length of the window in seconds for calculating the SNR

Returns:

A dictionary with the estimated SNR in db for each pick

Return type:

snr (dict)

tiebenn.tools.nicetools.normalize(param, mode, lb, ub)[source]

Parameter normalization using robust statistics. The resulting normalized parameter ranges between 0 and 1. Each parameter will be normalized after the modes and bundary values of Ramos et al. (2025, in preparation).

Parameters:

  • param (float) – Parameter to be normalized

  • mode (str) – Choose a normalization mode between ‘simple’ (simple robust normalization using lb and ub) or ‘log’ (logarithmic 10-base, robust normalization)

  • lb (float) – Lower boundary of normalization. If param < lb, then it will be clipped to 0

  • ub (float) – Upper boundary of normalization. If param > ub, then it will be clipped to 1. Note: lb as well as ub for the parameters to be normalized using the log mode, are actually the logarithm of the normalization boundaries

Returns:

The normalized parameter

Return type:

norm_param (float)

tiebenn.tools.nicetools.station_density(epicenter, stations)[source]

Calculates station density within a circular area around the epicenter.

Parameters:

  • epicenter (tuple) – (latitude, longitude) for the event

  • stations (list) – list of tuples [(latitude, longitude), …] for station locations

Returns:

Station density (stations per square km).

Return type:

density (float)

tiebenn.tools.nicetools.str2bool(v)[source]

Tries to interpret an input as a boolean argument. Expected true boolean arguments are: yes, true, t, y, and 1. Expected false boolean arguments: no, false, f, n, 0

Parameters:

v (str) – Argument to be interpreted as True or False

Returns:

The string interpreted as boolean

Return type:

v (bool)

tiebenn.tools.nicetools.strmonth2num(strmonth)[source]

It gets the month number corresponding to the 3-character month (e.g. for the input ‘Jan’ the output is 1)

Parameters:

strmonth (str) – Month in 3-character format (not case-sensitive)

Returns:

Month number

Return type:

nummonth (int)

tiebenn.tools.nicetools.tt_theo_before_assoc(ev_time, teo_p_time, teo_s_time, pick, tol_p, tol_s)[source]

This function decides if a predicted pick is close enough to the theoretical pick (for example, obtained using Taup)

Parameters:

  • ev_time (str) – yyyy-mm-dd hh:mm:ss.ss

  • teo_p_time (float) – Arrival time of the P-wave, in seconds after the event

  • teo_s_time (float) – Arrival time of the S-wave, in seconds after the event

  • pick (SeisBench pick) – The pick as predicted by the models in SeisBench

  • tol_p (int or float) – Seconds (in absolute value) in which a predicted P-pick is allowed to differ from the theoretical P-pick

  • tol_s (int or float) – Seconds (in absolute value) in which a predicted S-pick is allowed to differ from the theoretical S-pick