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:

# List of files to read exluded events and phases, e.g. ['exclude.yaml']
# (list)
exclude_files: ['exclude.yaml']

# Read and write moment tensors in Harvard Up-South-East rather convention.
# False assumes the components to be nn, ee, dd, ne, nd, ed.
# True assumes rr, tt, ff, rt, rf, tf
# (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
#    - 'constrained': As 'auto', but read constraints on high- and lowpass from
#      header variables 'min_amp_highpass' and 'max_amp_lowpass'.
# (str)
amplitude_filter:

# The 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, narrower bandpass:
# 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')
# (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 the first value as the fixed
# stress drop
# ([float, float])
auto_lowpass_stressdrop_range:

# When estimating the low-pass frequency of an event as the corner frequency
# (auto_lowpass_method: 'corner'), use this near source S-wave velocity (m/s) to
# constrain the corner frequency estimate from spectrum
# (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 the lowpass filter that is common to one phase of one event accross all
# 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

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

# Maximum first normalized singular value allowed for 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 to allow an amplitude
# measurement.
# (float)
max_event_distance:

# Minimum shared path length fraction between events and station to allow an
# amplitude measurement. `1` indicates co-located events, `0` indicates
# inter-event distance equals event-station distance
# (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 equations 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:

exclude.yaml#
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:

  1. Station name (must not contain _)

  2. Northing (meter)

  3. Easting (meter)

  4. Depth (meter)

A station file can be created with:

from relmt import core, io
io.write_station_table(
    {"STA": core.Station(0.0, 0.0, 0.0, "STA")}, "stations.txt"
)

which yields the file:

stations.txt#
#Station     Northing      Easting       Depth
# (code)      (meter)      (meter)     (meter)
     STA        0.000        0.000       0.000

Event file#

The event files holds the seismic event catalog. It is located in the data/ subdirectory. It has seven columns:

  1. Event index (arbitrary integer)

  2. Northing (meter)

  3. Easting (meter)

  4. Depth (meter)

  5. Origin time (arbitrary float in seconds, e.g. epoch seconds)

  6. Magnitude

  7. Event name (arbitrary string)

We use the arbitrary 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 arbitrary event reference (e.g. event ID within a larger catalog), which may be used for data import and export.

An event file can be created with:

from relmt import core, io
io.write_event_table(
    {0: core.Event(0.0, 0.0, 0.0, 0.0, 0.0, "SomeName")}, "events.txt"
)

which yields the file:

events.txt#
#Number     Northing      Easting       Depth         Origintime Magnitude                 Name
# (int)      (meter)      (meter)     (meter)          (seconds)       (-)                (str)
      0        0.000        0.000       0.000           0.000000    0.0000             SomeName

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:

  1. Event index (as in the event file)

  2. Station name (as in the station file)

  3. Phase type (P or S)

  4. Arrival time (float)

  5. Azimuth (east of north)

  6. 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.

A phase file can be created with:

from relmt import core, io
io.write_phase_table(
    {core.join_phaseid(0, "STA", "P"): core.Phase(0.0, 0.0, 0.0)}, "phases.txt"
)

which yields the file:

phases.txt#
#     EventIndex Station Phase        Arrivaltime  Azimuth      Plunge
#          (int)   (str) (P/S)          (seconds) (degree)    (degree)
               0     STA     P           0.000000     0.00        0.00

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:

  1. Event index (as in the event file)

  2. nn -

  3. ee -

  4. dd -

  5. ne -

  6. nd -

  7. 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.

from relmt import core, io
io.write_mt_table(
    {0: core.MT(0.0, 0.0, 0.0, 0.0, 0.0, 0.0)}, "reference_mts.txt"
)

which yields the file:

reference_mts.txt#
#Number            nn            ee            dd            ne            nd            ed
# (int)          (Nm)          (Nm)          (Nm)          (Nm)           (Nm)         (Nm)
      0  0.000000e+00  0.000000e+00  0.000000e+00  0.000000e+00  0.000000e+00  0.000000e+00

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 (ex. 'P', 'S', 'Pn', 'Pg')
# (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 center
# 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 for event exclusion
# (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 expansion coefficient norm of a waveform for event exclusion
# (float)
min_expansion_coefficient_norm:

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

# Combine event pairs stored in file 'STATION_PHASE-combination.txt'
# (bool)
combinations_from_file:

# Minimum highpass filter corner (Hertz) used by `relmt amplitude` when
# 'amplitude_filter' is 'constrained'
# (float)
min_amp_highpass:

# Maximum lowpass filter corner (Hertz) used by `relmt amplitude` when
# 'amplitude_filter' is 'constrained'
# (float)
max_amp_lowpass:

# Event numbers corresponding to the first dimension of the waveform array. Only
# edit when constructing the waveform array.
# (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.