relmt.core module#

Naming conventions and configuration classes for relMT

class relmt.core.Config(event_file=None, station_file=None, phase_file=None, reference_mt_file=None, harvard_convention=None, lag_times=None, amplitude_suffix='', admit_suffix='', result_suffix='', loglevel=None, reference_mts=None, mt_constraint=None, reference_weight=None, amplitude_filter=None, auto_highpass_periods=None, auto_lowpass_method=None, fixed_lowpass=None, auto_lowpass_stressdrop_range=None, auto_lowpass_vs=None, auto_bandpass_snr_target=None, lowpass_event_phase_quantile=None, amplitude_measure=None, min_dynamic_range=None, min_amplitude_misfit=None, max_amplitude_misfit=None, max_s_amplitude_misfit=None, min_amplitude_weight=None, max_s_sigma1=None, max_magnitude_difference=None, max_event_distance=None, min_shared_path=None, two_s_equations=None, max_p_equations=None, max_s_equations=None, keep_events=None, equation_batches=None, min_equations=None, min_stations=None, max_gap=None, bootstrap_samples=None, ncpu=None)[source]#

Bases: object

Configuration for relMT

Parameters:

event_file (str | None) – Path to the seismic event catalog, e.g. ‘data/events.txt’
station_file (str | None) – Path to the station location file, e.g. ‘data/stations.txt’
phase_file (str | None) – Path to the phase file, e.g. ‘data/phases.txt’
reference_mt_file (str | None) – Path to the reference moment tensor file, e.g. ‘data/reference_mt.txt’
harvard_convention (bool | None) – 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).
loglevel (str | None) – Logging verbosity for relMT modules. One of ‘DEBUG’, ‘INFO’, ‘WARNING’, ‘ERROR’, ‘CRITICAL’, ‘NOTSET’
ncpu (int | None) – Number of threads to use in some parallel computations
lag_times (list[str] | None) –
- ‘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
amplitude_suffix (str) – Suffix appended to files, naming the parameters parsed to ‘amplitude’
amplitude_filter (str | None) –
- ‘manual’: Use ‘highpass’ and ‘lowpass’ of the waveform header files.
- ’auto’: compute filter corners using the “auto” options below
auto_highpass_periods (float | None) – 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).
auto_lowpass_method (str | None) –
- ‘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.
fixed_lowpass (float | None) – Provide a fixed lowpass filter corner for all events. (requires auto_lowpass_method: ‘fixed’ or amplitude_filter: ‘fixed’)
auto_lowpass_stressdrop_range (tuple[float, float] | None) – 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.
auto_lowpass_vs (float | None) – Near source S-wave velocity (m/s) used to constrain corner frequency estimate from spectrum when auto_lowpass_method is ‘corner’. Ignored otherwise.
auto_bandpass_snr_target (float | None) – 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.
lowpass_event_phase_quantile (float | None) – 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.
amplitude_measure (str | None) –
- ‘indirect’: Estimate relative amplitude as the ratio of principal seismogram contributions to each seismogram.
- ’direct’: Compare each event combination separately.
min_dynamic_range (float | None) – 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.
admit_suffix (str) – Suffix appended to the amplitude suffix, naming the admission parameters parsed to ‘admit’
max_amplitude_misfit (float | None) – Discard amplitude measurements with a higher misfit than this. Applies only to P amplitudes if ‘max_s_amplitude_misfit’ is given.
max_s_amplitude_misfit (float | None) – If given, discard S amplitude measurements with a higher misfit. ‘max_amp_misfit’ then only applies to P amplitudes.
max_s_sigma1 (float | None) – 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.
max_magnitude_difference (float | None) – Maximum difference in magnitude between two events to allow an amplitude measurement.
max_event_distance (float | None) – Maximum allowed distance (m) between two events.
min_shared_path (float | None) – Minimum shared path length fraction between events and station to allow an amplitude measurement.
min_equations (int | None) – Minimum number of equations required to constrain one moment tensor
min_stations (int | None) – Minimum number of stations required to constrain one moment tensor
max_gap (float | None) – Maximum azimuthal gap allowed for one moment tensor
two_s_equations (bool | None) – Use two equations per S-amplitude observation triplet (False only includes the one with the highest norm of the polarization vector).
max_p_equations (int | None) – 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
max_s_equations (int | None) – As max_p_equations, but for S equations.
keep_events (list[int] | None) – 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.
equation_batches (int | None) – 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.
result_suffix (str) – Suffix appended to amplitude and admit suffices indicating the parameter set parsed to ‘solve’
reference_mts (list[int] | None) – Event indices of the reference moment tensor(s) to use
reference_weight (float | None) – Weight of the reference moment tensor
mt_constraint (str | None) – Constrain the moment tensor. ‘none’ or ‘deviatoric’
min_amplitude_misfit (float | 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
min_amplitude_weight (float | None) – Lowest weight assigned to the maximum amplitude misfit
bootstrap_samples (int | None) – Number of samples to draw for calculating uncertainties. If not given, do not bootstrap.

Raises:

KeyError: – If unknown keywords are present
TypeError: – If input value is of wrong type

get(value, default)[source]#: Return value of key or a default when unset

items()[source]#: Iterator over key, value pairs where value is set

keys()[source]#: Return non-empty configuration keys

kwargs(function)[source]#

Return only the keyword arguments that are expected by function

Parameters:: function (Callable)

to_file(filename, overwrite=False)[source]#

Save configuration to .yaml file

Parameters:

filename (str | Path) – Name of the file. File ending ‘.yaml’ will be appended if absent.
overwrite (bool) – Overwrite file in case it exists

Raises:

FileExistsError: – When file exists and overwrite is False

update(other)[source]#

Add and, if present, replace configuration keys

Parameters:: other (dict) – Dictionary holding valid key, value pairs

update_from_file(filename, overwrite=True)[source]#

Update configuration from .yaml file

Parameters:

filename (str | Path) – Name of the configuration file
overwrite (bool) – When keyword is already present in config, overwrite its value from file

values()[source]#: List of configuration values that are not None

class relmt.core.Event(north, east, depth, time, mag, name)#

Bases: tuple

Coordinates, time, magnitude and name of one seismic event

north, east, depth

Coordinates (meter)

Type:: float

time#

Origin time (seconds)

Type:: float

mag#

Magnitude

Type:: float

name#

Unique name used for referencing

Type:: str

class relmt.core.Exclude[source]#

Bases: TypedDict

Observations to exclude from processing

event: list[int]#: Events by index

phase_auto_cc: list[str]#: Phase observation to exclude due to correlation coefficient.

phase_auto_ecn: list[str]#: Phase observation to exclude due to low expansion coefficient norm.

phase_auto_nodata: list[str]#: Phase observation to exclude due to absent or corrupt data.

phase_auto_snr: list[str]#: Phase observation to exclude due to low signal-to-noise ratio.

phase_manual: list[str]#: Phase observation given as Phase ID (e.g. 0_STA_P) of one event on one station to exclude from waveform alignment

station: list[str]#: Station names

waveform: list[str]#: Phases (‘P’ or ‘S’) on a station, given as Waveform ID (e.g STA_P)

class relmt.core.Header(station=None, phase=None, components=None, matlab_variable=None, sampling_rate=None, data_window=None, phase_start=None, phase_end=None, taper_length=None, highpass=None, lowpass=None, null_threshold=None, min_signal_noise_ratio=None, min_correlation=None, min_expansion_coefficient_norm=None, combine_neighbors=None, combinations_from_file=None, events_=None)[source]#

Bases: Config

Waveform Header for relMT

Parameters:

station (str | None) – Station code
phase (str | None) – Seismic phase type to consider (‘P’ or ‘S’)
matlab_variable (str | None) – If we are reading a MATLAB .mat file, name of the variable that holds the waveform array
components (str | None) – One-character component names ordered as in the waveform array, as one string (e.g. ‘ZNE’)
sampling_rate (float | None) – Sampling rate of the seismic waveform (Hertz)
data_window (float | None) – Time window symmetric about the phase pick (i.e. pick is near the central sample) (seconds)
phase_start (float | None) – Start of the phase window before the arrival time pick (negative seconds before pick).
phase_end (float | None) – End of the phase window after the arrival time pick (seconds after pick).
taper_length (float | None) – Combined length of taper that is applied at both ends beyond the phase window. (seconds)
highpass (float | None) – Common high-pass filter corner of the waveform (Hertz)
lowpass (float | None) – Common low-pass filter corner of the waveform (Hertz)
null_threshold (float | None) – Regard absolute amplitudes at and below this value as null
min_signal_noise_ratio (float | None) – Minimum allowed signal-to-noise ratio (dB) of signals for event exclusion
min_correlation (float | None) – Minimum allowed absolute averaged correlation coefficient of a waveform for event exclusion
min_expansion_coefficient_norm (float | None) – Minimum allowed norm of the principal component expansion coefficients contributing to the waveform reconstruction for event exclusion
combine_neighbors (int | None) – Combine only this many nearest neigboring events. Ignored when using ‘combinations_from_file’
combinations_from_file (bool | None) – Read combinations from file names STATION_PHASE-combination.txt
events – Event numbers corresponding to the first dimension of the waveform array. Do not edit.
events_ (list[int] | None)

Raises:

KeyError – If unknown keywords are present
TypeError – If input value is of wrong type

validate()[source]#: Check if all arguments are valid

class relmt.core.MT(nn, ee, dd, ne, nd, ed)#

Bases: tuple

A seismic moment tensor

nn, ee, dd, ne, nd, ed: Components in North-East-Down coordinates (Nm)

class relmt.core.P_Amplitude_Ratio(station, phase, event_a, event_b, amp_ab, misfit, correlation, sigma1, sigma2, highpass, lowpass)#

Bases: tuple

P-wave amplitude ratio observation

station#

Unique station name

Type:: str

phase#

Phase identifier starting with P

Type:: str

event_a, event_b

Event indices

Type:: int

amp_ab#

Amplitude ratio

Type:: float

misfit#

Reconstruction misfit

Type:: float

correlation#

Correlation coefficient of the reconstruction

Type:: float

sigma1, sigma2

First and second singular value of the seismogram decomposition

Type:: float

highpass, lowpass

Filter corners at which the amplitude as astimated

Type:: float

class relmt.core.Phase(time, azimuth, plunge)#

Bases: tuple

Arrival time and take-off angle of one seismic phase

time#

Arrival time (seconds)

Type:: float

azimuth#

Take-off angle azimuth (degree east of North)

Type:: float

plunge#

Take-off angle plunge (degree down from horizontal)

Type:: float

class relmt.core.S_Amplitude_Ratios(station, phase, event_a, event_b, event_c, amp_abc, amp_acb, misfit, correlation, sigma1, sigma2, sigma3, highpass, lowpass)#

Bases: tuple

S-wave amplitude ratio observations

station#

Unique station name

Type:: str

phase#

Phase identifier starting with S

Type:: str

event_a, event_b, event_c

Event indices

Type:: int

amp_abc#

Amplitude of event b in a assuming the third event is c

Type:: float

amp_acb#

Amplitude of event c in a assuming the third event is b

Type:: float

misfit#

Reconstruction misfit

Type:: float

correlation#

Correlation coefficient of the reconstruction

Type:: float

sigma1, sigma2, sigma3

First, second and third singular value of the seismogram decomposition

Type:: float

highpass, lowpass

Filter corners at which the amplitude as astimated

Type:: float

class relmt.core.Station(north, east, depth, name)#

Bases: tuple

Coordinates and name of one seismic station

north, east, depth

Coordinates (meter)

Type:: float

name#

Unique name used for referencing

Type:: str

relmt.core.aligndir(iteration)[source]#

Return the name of the alignment directory for a given iteration

Parameters:: iteration (int | None)
Return type:: str

relmt.core.combine_suffixes(*suffixes)[source]#

Combine multiple suffixes into one, with single leading ‘-’ and no trailing ‘-’

Parameters:: suffixes (str)
Return type:: str

relmt.core.file(file_id, station='', phase='', n_align=None, directory='', suffix='')[source]#

Path to a runtime file, following naming conventions

Parameters:

file_id (str) –
The file to be accessed, one of:
- ’config’: Central configuration file
- ’exclude’: Excluded stations, events and phases
- ’event’: Seismic event locations, magnitudes and names
- ’station’: Station codes and locations
- ’phase’: Seismic phase arrival times and take-off angles
- ’reference_mt’: Reference moment tensor elements
- ’relative_mt’: Relative moment tensor elements
- ’mt_summary’: Summary of moment tensor results
- ’bootstrap_mt’: Relative moment tensors from bootstrap sub-sampling
- ’bootstrap_statistics’: Diagnostic values extracted from bootstrap statistics
- ’amplitude_matrix’: Left hand side of the linear system
- ’amplitude_data_vector’: Right hand side of the linear system
- ’amplitude_scale’: Event scaling vector applied to linear system
- ’bandpass’: Optimal filter pass bands per event per station
- ’amplitude_observation’: Amplitude ratios and misfits for event pairs/triplets on a station
- ’amplitude_summary’: Amplitude observation with posterior misfit measures
- ’waveform_array’: Phase waveforms on one station
- ’waveform_header’: Waveform meta data. Without station and phase argument: default-hdr.yaml
- ’combination’: Two column list of allowed event combinations.
- ’mccc_time_shift’: Time shifts from Multi-channel cross correlation
- ’mccc_lag_times’: Pair wise lag times from Multi-channel cross correlation
- ’cc_matrix’: Cross-correlation matrix
- ’cc_vector’: Averaged cross-correlation vector
- ’pca_time_shift’: Time shifts from principal component analysis
- ’pca_objective’: Value of principal component objective function
Alternatively, give a file basename ending in ‘.’extension. The basename will be pre- and suffixed, and sorted into data, align, or amplitude folder, if ‘iteration’ is 0, >0, or None, respectively
station (str) – Station name, required for: waveform_array, waveform_header, combination, mccc_time_shift, mccc_lag_times, cc_matrix, cc_vector, pca_time_shift, pca_objective
phase (str) – Seismic phase, required for: amplitude_observation, amplitude_summary
n_align (int | None) – Alignment iteration, required for: amplitude_observation, amplitude_summary
directory (str) – Name of the root directory
suffix (str) – String to append to the basename, before the file ending. A single leading ‘-’ will prepended (but given leading ‘-’ stripped).

Returns:

fpath (Path) – Path to the file

relmt.core.ijk_ccvec(ns)[source]#

Translate linear index n to cross correlation triplet indices ijk

Yields all three permutations (i, j, k), (k, i, j) and (j, k i)

Parameters:: ns (int)
Return type:: Generator[tuple[int, int, int]]

relmt.core.init(directory=None)[source]#

Initialize a working directory

Parameters:: directory (str | Path | None)

relmt.core.iterate_event_pair(nev, event_list=None)[source]#

Yield event pairs and corresponding indices into event_list

Parameters:

nev (int) – Total number of events (= highest event index)
event_list (list[int] | range | None) – Reduced set of events to iterate (Default: range(nev))

Yields:

a, b (int) – Combinations of a and b
ia, ib (int if event_list is not None) – Indices of a and b in event_list

relmt.core.iterate_event_triplet(nev, event_list=None)[source]#

Yield event triplets and corresponding indices into event_list

Parameters:

nev (int) – Total number of events
event_list (list[int] | range | None) – Reduced set of events to iterate (Default: range(nev))

Yields:

a, b, c (int) – Indices of combinations of a, b, and c
ia, ib, ic (int if event_list is not None) – Indices of a, b and c in event_list

relmt.core.iterate_waveid(directory, iteration, excl={'event': [], 'phase_auto_cc': [], 'phase_auto_ecn': [], 'phase_auto_nodata': [], 'phase_auto_snr': [], 'phase_manual': [], 'station': [], 'waveform': []})[source]#

Get the waveform IDs present in alignment directory.

Excluding those in the exclude file.

Parameters:

directory (Path)
iteration (int)
excl (Exclude)

Return type:

list

relmt.core.join_phaseid(event_index, station, phase)[source]#

Join event, station and phase names to phase identifier

Parameters:

event_index (int)
station (str)
phase (str)

Return type:

str

relmt.core.join_waveid(station, phase)[source]#

Join station and phase names to waveform identifier

Parameters:

station (str)
phase (str)

Return type:

str

relmt.core.register_logger(logger_or_name)[source]#

Attach the relMT handler and current log level to a logger.

..note: Written by gpt-5-codex

Parameters:: logger_or_name (str | Logger)
Return type:: Logger

relmt.core.set_loglevel(level)[source]#

Set the log level for the relMT package loggers.

..note: Written by gpt-5-codex

Parameters:: level (str | int)
Return type:: str

relmt.core.split_phaseid(phase_id)[source]#

Split phase identifier into eventID, station and phase

Parameters:: phase_id (str)
Return type:: tuple[int, str, str]

relmt.core.split_waveid(wave_id)[source]#

Split waveform identifier into station and phase

Parameters:: wave_id (str)
Return type:: tuple[str, str]