Usage

This section shows an example which should make TieBeNN’s usage clear.

Input file

Input file syntax: YYYY-MM-DDTHH:MM:SS  latitude  longitude

Example: 2024-12-24T01:55:04 51.337  12.548

Syntax

With the created virtual environment activated, TieBeNN follows this syntax:

tiebenn --event_file <EventFile> --max_epic_dist <MaxEpDist> --picker <Picker> --client <Client> --sds_dir <SDSDir> --min_detections <MinDetections> --plots <Plots> --vel_mode <VelMode> --velmod <VelMod> --ph_assoc <PhaseAssoc> --denoise <Denoise> --mult_windows <MultiWindows> --secs_before <SecsBef>

Parameter

Description

--event_file

Full path to input file with preliminary epicenter (latitude, longitude) and UTC datetime.

--max_epic_dist

Maximum epicentral distance (in km) for stations on which phase picks will be detected.

--picker

Select model for phase picking. EQTransformer: sb_eqt, seisbench_eqt, seisbench_eqtransformer, sb_eqtransformer PhaseNet: sb_pn, seisbench_pn, sb_phasenet, seisbench_phasenet (Not case sensitive).

--client

If set to SDS, it accesses a SeisComp3 directory and fetches waveforms for stations within --max_epic_dist km. Then attempts FDSN query. If set to FDSN, it skips SDS lookup.

--sds_dir

Full path to SeisComp3 directory. Required if --client is set to SDS.

--min_detections

Minimum number of stations with P- or S- picks required to complete the detection loop.

--plots

If True, it plots waveforms with detections, phase picks sorted by distance, station maps, and the confidence ellipsoid of the located event.

--vel_mode

Velocity model selection mode: automatic (or auto, a): Picks model based on epicenter if available, or uses default manual (or man, m): You must also define --velmod.

--velmod

Number corresponding to the velocity model used in NonLinLoc. See the current velocity model list here. Note: 3D models are supported, but not yet optimal for real-time use.

--ph_assoc

Phase associator: PyOcto (pyocto, p) or GaMMA (gamma, g). (Not case sensitive)

--denoise

If True, applies DeepDenoiser to waveforms within 100 km of the epicenter.

--mult_windows

If True, the phase picker searches in multiple time windows to improve ML stability.

--secs_before

If --mult_windows is False, this sets how many seconds before the event the waveform starts. Default is 0 seconds.

Note

Commands related to the use of 3D NonLinLoc velocity models is deactivated, but they are still present in the code in case someone wants to pick its development up.

To locate the event with example UTC datetime and coordinates specified above, we type in the terminal (remember to activate the virtual environment created above):

tiebenn --event_file <full_path_to_example_event> --max_epic_dist 150 --picker SeisBench_PhaseNet --client FDSN --min_detections 3 --plots True --vel_mode auto --ph_assoc PyOcto --denoise True --mult_windows True

Output

If the location was successful, you’ll see something like:

##############################################################
NonLinLoc: Location completed.
Origin time: 24-12-2024_01:55:4.517789
             Lat:51.328045 Long:12.543796 Depth: 22.685547 km
--------------------------------------------------------------
Location quality:
RMS:0.285177 Number of phases: 130 Gap: 35.032 Distance from hypocenter to nearest station: 12.077 km
Ellipsoid semi-major axis: 1.030196e+00
##############################################################

With --plots True, the following figures are also generated:

  • Phase picks on waveforms:

    Phase picks

  • Associated phases:

    Phase association

  • Map: epicenter and stations:

    Epicenter map

  • Location confidence ellipsoid:

    Confidence ellipsoid

  • Location Quality Score:

    LQS