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, lag_times=None, amplitude_suffix='', admit_suffix='', result_suffix='', loglevel=None, reference_mts=None, mt_constraint=None, reference_weight=None, amplitude_filter=None, auto_lowpass_method=None, auto_lowpass_stressdrop_range=None, auto_bandpass_snr_target=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, two_s_equations=None, max_s_equations=None, keep_events=None, equation_batches=None, min_equations=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’

  • 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_lowpass_method (str | None) –

    • ‘fixed’: Use the value ‘fixed_lowpass’ (not implemented)

    • ’corner’: Estimate from apparent corner frequency in event spectrum. Requires ‘auto_lowpass_stressdrop_range’

    • ’duration’: Filter by 1/source duration of event magnitude.

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

  • 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_equations (int | None) – Minimum number of equations 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_s_equations (int | None) – Maximum number of S-wave equation in the linear system. If more are available, iteratively discard those with redundant pair-wise observations, on stations with many observations, and with a higher misfit

  • keep_events (list[int] | None) – When reducing number of S-wave equations, increase importance of these events by not counting them in the redundancy score. Use to keep many 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, 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

  • 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, 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

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

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.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(stations)[source]#

Yield P and S waveform identifiers for all stations

Parameters:

stations (list[str])

Return type:

Iterator[str]

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:
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]