File Formats#

Any lines stating with # are ignored.

Trailing columns are ignored.

For each cluster of seismic events we assume the following directory structure:

root/
+-- config.yaml
+-- exclude.yaml
+-- data/
    +-- stations.txt
    +-- events.txt
    +-- phases.txt
    +-- reference_mt.txt
    +-- default-hdr.yaml
    +-- STATION_PHASE-hdr.yaml
    +-- STATION_PHASE-wvarr.npy

The name of the root/ directory is arbitrary.

Configuration file `config.yaml`#

The configuration file holds the options that control the runtime behavior of relMT. It is located in the root/ directory.

An empty configuration file can be created with:

from relmt import core
core.Config().to_file("config.yaml")

which yields the file config.yaml:

config.yaml#

# relMT configuration

# Input files
# -----------
#
# Path to the seismic event catalog, e.g. 'data/events.txt'
# (str)
event_file:

# Path to the station location file, e.g. 'data/stations.txt'
# (str)
station_file:

# Path to the phase file, e.g. 'data/phases.txt'
# (str)
phase_file:

# Path to the reference moment tensor file, e.g. 'data/reference_mt.txt'
# (str)
reference_mt_file:

# Read and write moment tensors in Harvard Up-South-East rather than
# North-East-Down convention.
# False, the default, assumes (Mnn, Mee, Mdd, Mne, Mnd, Med).
# True assumes (Mrr, Mtt, Mff, Mrt, Mrf, Mtf).
#
# (bool)
harvard_convention: False

# Runtime options
# ---------------
#
# Logging verbosity for relMT modules. One of 'DEBUG', 'INFO', 'WARNING', 'ERROR',
# 'CRITICAL', 'NOTSET'
# (str)
loglevel: INFO

# Number of threads to use in some parallel computations
# (int)
ncpu: 1

# Align parameters
# --------------------
#
# Which MCCC lag times to write out. List any of:
#
#    - 'P': P lag times
#    - 'S-median': median of S lag time triplets
#    - 'S-residual': S lag times with lowest residuals
#    - 'S-cc': S lag times with highest cross-correlation values
# (list[str])
lag_times: []

# Amplitude parameters
# --------------------
#
# Suffix appended to files, naming the parameters parsed to 'amplitude'
# (str)
amplitude_suffix:

# Filter method to apply for amplitude measure. One of:
#
#    - 'manual': Use 'highpass' and 'lowpass' of the waveform header files.
#    - 'auto': compute filter corners using the "auto" options below
# (str)
amplitude_filter:

# Highpass filter corner allows not fewer than this  many signal periods within a phase
# window. Heuristic approach to eliminate low-frequency noise. A larger number means
# a higher highpass:
# highpass = `auto_highpass_periods` / (`phase_end` - `phase_start`).
#
# (float)
auto_highpass_periods: 1.0

# Method to estimate low-pass filter that eliminates the source time function. One
# of:
#
#    - 'fixed': Use the value 'fixed_lowpass'
#    - 'corner': Estimate from apparent corner frequency in event spectrum.
#      Requires 'auto_lowpass_stressdrop_range'
#    - 'duration': Filter by 1/source duration of event magnitude.
# (str)
auto_lowpass_method:

# Provide a fixed lowpass filter corner for all events.
# (requires auto_lowpass_method: 'fixed' or amplitude_filter: 'fixed')
# (float)
fixed_lowpass:

# When estimating the low-pass frequency of an event as the corner frequency
# (auto_lowpass_method: 'corner'), assume a stress drop within this range (Pa).
# When second value is less or equal first value, use a fixed stress drop of first
# value.
# ([float, float])
auto_lowpass_stressdrop_range:

# Near source S-wave velocity (m/s) used to constrain corner frequency estimate
# from spectrum when `auto_lowpass_method` is 'corner'. Ignored otherwise.
# (float)
auto_lowpass_vs:

# Include frequencies with this signal-to-noise ratio to optimal bandpass filter.
# Respects low-pass constraint. If not supplied, do not attempt to optimize
# passband.
# (float)
auto_bandpass_snr_target:

# Find a lowpass filter corner common to event phase observations accross
# stations. Use the given quantile of the previously assigned lowpasses (0
# indicates minimum value, 0.5 median, 1 maximum value). The criterion is applied
# after the the individual waveform bandpasses are calculated or loaded from
# file.
# (float)
lowpass_event_phase_quantile:

# Method to measure relative amplitudes. One of:
#
#    - 'indirect': Estimate relative amplitude as the ratio of principal seismogram
#      contributions to each seismogram.
#    - 'direct': Compare each event combination separately.
# (str)
amplitude_measure:

# Minimum ratio (dB) of low- / high-pass filter bandwidth in an amplitude ratio
# measurement. When positive, discard observation outside dynamic range. When
# negative, lower the high-pass until the (positive) dynamic range is reached.
# (float)
min_dynamic_range: 1.0

# Admission parameters
# -------------------------
#
# Suffix appended to the amplitude suffix, naming the admission parameters
# parsed to 'admit'
# (str)
admit_suffix:

# Discard amplitude measurements with a higher misfit than this. Applies only to P
# amplitudes if 'max_s_amplitude_misfit' is given.
# (float)
max_amplitude_misfit: inf

# If given, discard S amplitude measurements with a higher misfit.
# 'max_amp_misfit' then only applies to P amplitudes.
# (float)
max_s_amplitude_misfit:

# Maximum first normalized singular value to allow for an S-wave reconstruction. A
# value of 1 indicates that S-waveform adheres to rank 1 rather than rank 2 model.
# The relative amplitudes Babc and Bacb are then not linearly independent.
# (float)
max_s_sigma1: 1.0

# Maximum difference in magnitude between two events to allow an amplitude
# measurement.
# (float)
max_magnitude_difference:

# Maximum allowed distance (m) between two events.
# (float)
max_event_distance:

# Minimum shared path length fraction between events and station to allow an
# amplitude measurement.
# (float)
min_shared_path:

# Minimum number of equations required to constrain one moment tensor
# (int)
min_equations: 1

# Minimum number of stations required to constrain one moment tensor
# (int)
min_stations: 1

# Maximum azimuthal gap allowed for one moment tensor
# (float)
max_gap: 360.0

# Use two equations per S-amplitude observation triplet (`False` only includes the
# one with the highest norm of the polarization vector).
# (bool)
two_s_equations: True

# Maximum number of P-wave equation in the linear system. If more are available,
# iteratively discard those with redundant observations, on stations with many
# observations, and with a higher misfit
# (int)
max_p_equations:

# As `max_p_equations`, but for S equations.
# (int)
max_s_equations:

# When reducing number of equations, increase importance of these events by not
# counting them in the redundancy score. Use to keep more equations e.g. for the
# reference event or specific events of interest.
# (list)
keep_events:

# When reducing the number of S-wave equations, rank observations iteratively this
# many times by redundancy and remove the most redundant ones. A lower number is
# faster, but may result in discarding less-redundant observations.
# (int)
equation_batches: 1

# Solve parameters
# ----------------
#
# Suffix appended to amplitude and admit suffices indicating the parameter set parsed
# to 'solve'
# (str)
result_suffix:

# Event indices of the reference moment tensor(s) to use
# (list)
reference_mts:

# Weight of the reference moment tensor
# (float)
reference_weight:

# Constrain the moment tensor. 'none' or 'deviatoric'
# (str)
mt_constraint: none

# Minimum misfit to assign a full weight of 1. Weights are scaled linearly from
# `min_amplitude misfit` = 1 to `max_amplitude_misfit` = `min_amplitude_weight`
# (float)
min_amplitude_misfit: 0.0

# Lowest weight assigned to the maximum amplitude misfit
# (float)
min_amplitude_weight: 0.0

# Number of samples to draw for calculating uncertainties. If not given, do not
# bootstrap.
# (int)
bootstrap_samples: 0

Exclude file `exclude.yaml`#

The exclude file lists the events, stations, phases and waveforms to exclude from processing. It is located in the root/ directory. An empty exclude file can be created with:

from relmt import core, io
io.save_yaml("exclude.yaml", core.exclude)

which yields the file:

station: []
event: []
waveform: []
phase_manual: []
phase_auto_nodata: []
phase_auto_snr: []
phase_auto_cc: []
phase_auto_ecn: []

Station file#

The station file holds the station names and locations. It is located in the data/ subdirectory and has four columns:

Station name (must not contain _)
Northing (meter)
Easting (meter)
Depth (meter)

Event file#

The event files holds the seismic event catalog. It is located in the data/ subdirectory.

events.txt has seven columns:

Event index
Northing (meter)
Easting (meter)
Depth (meter)
Origin time (arbitrary float in seconds, e.g. epoch seconds)
Magnitude
Event name (arbitrary string)

We use the event index (1.) to internally refer to events. We use origin time (5.) for external reference and magnitude (6.) for quality assurance. Time and magnitude can be nan if unknown. The event name (7.) is an external event reference (e.g. event ID within a larger catalog), which may be used for data import and export.

Phase file#

The phase file holds the arrival times and take-off angles of the seismic phases at the stations. It is located in the data/ subdirectory.

phases.txt has six columns:

Event index (as in the event file)
Station name (as in the station file)
Phase type (P or S)
Arrival time (float)
Azimuth (east of north)
Plunge (down from horizontal)

Arrival time (4.) is required to tie time shifts of seismic traces to an absolute reference frame and can be useful when importing and exporting seismic traces. We recommend to use absolute time in epoch seconds or seconds after origin time.

Reference moment tensor file#

The reference moment tensor file holds the components of the reference moment tensor(s). It is located in the data/ subdirectory.

reference_mt.txt has seven columns:

Event index (as in the event file)
nn -
ee -
dd -
ne -
nd -
ed - component of the moment tensor (Nm)

The components of the moment tensor are given in units of Newton meter. Scientific notation (e.g. 1.2e19) is encouraged for the large floats.

Waveform header files `STATION_PHASE-hdr.yaml`#

The waveform header files hold the meta information about the seismic waveforms. Default values are read from default-hdr.yaml located in the data/ subdirectory. Values for a specific waveform are overwritten by the values from files named STATION_PHASE-hdr.yaml located in the data/ subdirectory, where STATION is the station name as in the station and phase files, and PHASE is the phase type as in the phase file (P or S).

A template header file can be created with:

from relmt import core
core.Header().to_file("default-hdr.yaml")

which yields the file default-hdr.yaml:

default-hdr.yaml#

# relMT waveform header

# Station code
# (str)
station:

# Seismic phase type to consider ('P' or 'S')
# (str)
phase:

# If we are reading a MATLAB .mat file, name of the variable that holds the
# waveform array
# (str)
matlab_variable:

# One-character component names ordered as in the waveform array, as one string
# (e.g. 'ZNE')
# (str)
components:

# Sampling rate of the seismic waveform (Hertz)
# (float)
sampling_rate:

# Time window symmetric about the phase pick (i.e. pick is near the central
# sample) (seconds)
# (float)
data_window:

# Start of the phase window before the arrival time pick (negative seconds before
# pick).
# (float)
phase_start:

# End of the phase window after the arrival time pick (seconds after pick).
# (float)
phase_end:

# Combined length of taper that is applied at both ends beyond the phase window.
# (seconds)
# (float)
taper_length:

# Common high-pass filter corner of the waveform (Hertz)
# (float)
highpass:

# Common low-pass filter corner of the waveform (Hertz)
# (float)
lowpass:

# Regard absolute amplitudes at and below this value as null
# (float)
null_threshold:

# Minimum allowed signal-to-noise ratio (dB) of signals for event exclusion
# (float)
min_signal_noise_ratio:

# Minimum allowed absolute averaged correlation coefficient of a waveform for
# event exclusion
# (float)
min_correlation:

# Minimum allowed norm of the principal component expansion coefficients
# contributing to the waveform reconstruction for event exclusion
# (float)
min_expansion_coefficient_norm:

# Combine only this many nearest neigboring events. Ignored when using
# 'combinations_from_file'
# (int)
combine_neighbors:

# Read combinations from file names STATION_PHASE-combination.txt
# (bool)
combinations_from_file:

# Event numbers corresponding to the first dimension of the waveform array. Do not
# edit.
# (list)
events_:

Waveform array files `STATION_PHASE-wvarr.npy`#

The waveform array files hold the event waveforms of one phase at one station. They are NumPy array files that obey the naming convention STATION_PHASE-wvarr.npy, where STATION is the station name and PHASE is the phase type (P or S). The files are located in the data/ subdirectory.

Arrays are three dimensional, with events sorted along the first dimension, components along the second dimension and seismogram samples along the third dimension. The resulting shape is (n_events, n_channels, n_samples), where n_events and n_channels are the length of events_ and channels values in the header file, and n_samples is data_window multiplied by sampling_rate.

Event indices stored in the events_: keyword of the waveform header must correspond to the seismic traces stored in the first array dimension. Component names stored in the components: keyword of the waveform header must correspond to the seismogram components in the second dimension of the waveform array.

File Formats#

Configuration file config.yaml#

Exclude file exclude.yaml#