relmt.io module

In- and output functions

relmt.io.read_amplitudes(filename, phase, unpack=False)

Load relative amplitudes from file

Parameters:

• filename (str) – Name of the input file

• phase (str) – Seismic phase to consider

• unpack (bool) – Return each variable as separate array

Returns:

• amplitudes (if unpack=False) – Lists of the relmt.core.P_Amplitude_Ratio or relmt.core.S_Amplitude_Ratios

• station, a, b, amplitude, misfit, correlation, sigma1, sigma2, higpass,

• lowpass (if unpack=True and phase=P) – Arrays of the relmt.core.P_Amplitude_Ratio attribute

• station, a, b, c, amp_abc, amb_acb, misfit, correlation, sigma1, sigma2,

• sigma3, higpass, lowpass (if unpack=True and phase=S) – Arrays of the relmt.core.S_Amplitude_Ratios attributes

Raises:

ValueError: – If ‘phase’ is not P or S

relmt.io.read_combinations(filename)

Read a table of event combinations

Each pair will be sorted to allow for

Parameters:

filename (str | Path) – Name of the input file

Returns:

set[tuple[int, int]] – (combinations, 2) array of event combinations

relmt.io.read_config(filename)

Read a configuration from .yaml file

Parameters:

filename (str) – Name of the configuration file

Returns:

config (relmt.core.Config) – Configuration object

relmt.io.read_event_table(filename, unpack=False)

Read a relMT event table into list of events

Parameters:

• filename (str | Path) – Name of the event table file

• unpack – Return each variable as separate array.

Returns:

• event_dict (list, if unpack=False) – Seismic event catalog

• evid, north, east, depth, magnitude, name (numpy.ndarray if unpack=True) – Each parameter of the event catalog as an array

Raises:

IndexError: – If event indices in table are not unique

relmt.io.read_exclude_file(filename)

Read an exclude file

Parameters:

filename (str | Path) – Name of the exclude file

Returns:

Exclude – Dictionary with station, event and phase exclusions

relmt.io.read_ext_event_table(filename, north_index, east_index, depth_index, time_index, magnitude_index, name_index, geoconverter=None, timeconverter=None, nameconverter=None, loadtxt_kwargs={})

Read an external event table into an event dictionary.

Parameters:

• filename (str) – Name of the event table file

• north_index (int) – Column indices of the event northing, easting, depth, time, magnitude, and name

• east_index (int) – Column indices of the event northing, easting, depth, time, magnitude, and name

• depth_index (int) – Column indices of the event northing, easting, depth, time, magnitude, and name

• time_index (int) – Column indices of the event northing, easting, depth, time, magnitude, and name

• magnitude_index (int) – Column indices of the event northing, easting, depth, time, magnitude, and name

• name_index (int) – Column indices of the event northing, easting, depth, time, magnitude, and name

• geoconverter (Callable | None) – Function that takes north, east and depth as arguments and returns local northing and easting and depth coordinates in meters (e.g. interpret north and east as latitude and longitude, and return UTM northing and easting; or convert kilometer depth to meter)

• timeconverter (Callable | None) – Function that takes time string as argument and returns time in seconds as a float (e.g. epoch timestamp. Must be consistent with the reference frame of the waveforms)

• nameconverter (Callable | None) – Function that takes a string as argument and returns a user defined event name string.

• loadtxt_kwargs (dict) – Additional keyword arguments are passed on to numpy.loadtxt()

• note (..) – name_index and time_index can be tuples if they are to be transformed using nameconverter and timeconverter, respecitvely. Create the converters such that they accept the tuples in order as arguments and return a single value.

Returns:

dict[int, Event] – The seismic event catalog

Raises:

KeyError – if ‘usecol’, ‘unpack’, or ‘dtype’ are specified as loadtxt_kwargs:

relmt.io.read_ext_mt_table(filename, nn_ee_dd_ne_nd_ed_indices, name_index=None, event_dict=None, mtconverter=None, exponent_index=None, nameconverter=None, loadtxt_kwargs={})

Read an external moment tensor table into a moment tensor dictionary.

Parameters:

• filename (str) – Name of the event table file

• nn_ee_dd_ne_nd_ed_indices (tuple[int, int, int, int, int, int]) – Column indices of the nn, ee, dd, ne, nd, and ed components of the moment tensor

• name_index (int | None) – Column indices of the event name. If None, do not attempt to match event in ‘event_dict’

• event_dict (dict[int, Event] | None) – Dictionary of core.Event tuples. When given, only moment tensors that have a matching event name are considered

• mtconverter (Callable | None) – Function that takes six moment teonsor components (in the order given in nn_ee_dd_ne_nd_ed_indices) and, if provided, a seventh exponent argument and returns moment tensor components in nn, ee, dd, ne, nd, ed convention

• exponent_index (int | None) – Column indices of possible field holding the base-10 exponent. If present, we pass this on as last argument to mt_converter. Ignored, if mt_converter=None

• nameconverter (Callable | None) – Function that takes a string as argument and returns a user defined event name string. Only event names that match a name in event_list are considered.

• loadtxt_kwargs (dict) – Additional keyword arguments are passed on to numpy.loadtxt()

Returns:

dict[int, MT] – Event dictionary event index -> core.MT

Raises:

KeyError – if ‘usecol’, ‘unpack’, or ‘dtype’ are specified as loadtxt_kwargs:

relmt.io.read_header(filename, default_name=None)

Read a waveform header from .yaml file

Parameters:

• filename (str) – Name of the header file

• default_name (str | None) – Name of a file containg default values

Returns:

Header – Header dictionary

relmt.io.read_mt_table(filename, force_list=False, unpack=False)

Read a relMT moment tensor table into moment tensor dictionary

When only one moment tensor is present per event index, return a dict of moment tensors. When multiple moment tensors a present (e.g. bootstrapping results), return a dict of lists of moment tensors.

Parameters:

• filename (str) – Name of the moment tensor table file

• force_list (bool) – Always return a dict of lists. Ignored if unpack=True

• unpack (bool) – Return each variable as separate array. Superceeds force_list

Returns:

• mt_dict (dict, if unpack=False) – Moment tensor dictionary

  EventIndex -> core.MT

  or

  EventIndex -> list[core.MT]

• event_ids, nn, ee, dd, ne, nd, ed (numpy.ndarray, if unpack=True) – Event IDs and MT components

relmt.io.read_phase_nll_hypfile(filename, event_index, subtract_residual, subtract_stationterm, minimum_ray_quality=0)

Read arrival times and take-off angles from NonLinLoc .hyp file.

Arrival times can be corrected for location residual and station term.

Ray take-off azimuth is output in degree east of North (X-direction)

Ray take-off plunge is output degree down from horizontal (in positive Z-direction)

Parameters:

• filename (str) – Name of the NonLinLoc hypocenter (.hyp) file

• event_index (int) – Event index of this set of phase observations. Must correspond to event index in event dictionary.

• subtract_residual (bool) – Subtract localization residual from the arrival time

• subtract_stationterm (bool) – Subtract station term from the arrival time

• minimum_ray_quality (int) – Minumum ray quality to use for take-off angles (0=unreliable, 10=best)

Returns:

dict[str, Phase] – Lookup table phase ID -> (Arrivaltime, azimuth, plunge)

relmt.io.read_phase_table(filename, unpack=False)

Read a phase table into phase dictionary

Parameters:

• filename (str) – Name of phase file

• unpack (bool) – Return each variable as separate array

Returns:

• phase_dict (dict if unpack=False) – Lookup table phaseID -> relmt.core.Phase

• phase_id, time, azi, plung (numpy.ndarray if unpack=True) – The relmt.core.Phase attributes as numpy.ndarray

relmt.io.read_station_table(filename, unpack=False)

Read a relMT station table into dictionary structure

Parameters:

• filename (str) – Name of the station table file

• unpack (bool) – Return each variable as separate array

Returns:

• station_dict (dict) – Station code -> norting, easting, depth

• code, north, east, depth (numpy.ndarray) – If unpack=True

relmt.io.read_velocity_model(filename, has_kilometer=False)

Read a velocity model from file

The space-seperated file holds three columns: Depth (m), Vp (m/s), Vs (m/s). If the last column is absent, we assume a constant Vp/Vs ratio of 1.73.

Parameters:

• filename (str | Path) – Name of the event table file

• has_kilometer – Input file has depth in km and velocities in km/s.

Returns:

ndarray – (layers, 3) table of Depth (m), Vp (m/s), Vs (m/s)

relmt.io.read_waveform_array_header(station, phase, n_align=0, directory='', matlab=False, defaults=True)

Read a waveform array and corresponding header file.

Defalut values are drawn from default header.

Parameters:

• station (str) – Station name

• phase (str) – Seismic phase, ‘P’ or ‘S’

• n_align (int) – Alignment iterration, 0 for input data

• directory (str) – Root directory to look for the files

• matlab (bool) – Assume MATALB waveform files. Provide the name of the variable holding the waveform array in as header keyword matlab_variable.

• defaults (bool) – Attempt to pull in default vaules from a default-hdr.yaml file in the same directory

Returns:

• waveform_array (numpy.ndarray) – Event waveform gather of one phase type on one station

• header (relmt.core.Header) – Corresponding header dictionary

relmt.io.read_yaml(filename)

Read data from .yaml file

Parameters:

filename (str)

Return type:

dict

relmt.io.save_amplitudes(filename, table, more_data=[], more_names=[''], more_formats=None)

Save relative amplitudes to file

Parameters:

• filename (str) – Name of the output file

• table (list[P_Amplitude_Ratio] | list[S_Amplitude_Ratios]) – List of P- or S-amplitude ratios

• more_data (list[ndarray]) – (len(table),) arrays holding additional data columns

• more_names (list[str]) – Corresponding variable names

• more_formats (list[str] | None) – Corresponding format specifiers

relmt.io.save_mt_result_summary(filename, event_dict, mt_dict, gaps={}, links={}, misfits={}, correlations={}, moment_rms={}, amplitude_rms={}, bootstrap_rms={}, bootstrap_kagan={})

Combine moment tensor dictionary and event table and write out resut table

Parameters:

• filename (str | Path)

• event_dict (dict[int, Event])

• mt_dict (dict[int, MT])

• gaps (dict[int, ndarray])

• links (dict[int, tuple[int, int]])

• misfits (dict[int, float])

• correlations (dict[int, float])

• moment_rms (dict[int, float])

• amplitude_rms (dict[int, float])

• bootstrap_rms (dict[int, float])

• bootstrap_kagan (dict[int, float])

relmt.io.save_results(filename, arr)

Save array to filename using numpy.savetxt()

Parameters:

• filename (str | Path)

• arr (ndarray)

relmt.io.save_yaml(filename, data, format_bandpass=False)

Save data to .yaml file

Parameters:

• filename (str)

• data (dict)

relmt.io.write_event_table(event_dict, filename=None)

Convert event dictionary to relMT compliant event table.

Number Northing Easting Depth Time Magnitude Name

(int) (meter) (meter) (meter) (seconds) (-) (str)

Parameters:

• event_dict (dict[int, Event]) – Seismic event catalog

• filename (Path | str | None) – Write table to this file

Returns:

str – Tabled event data

relmt.io.write_formatted_table(arrays, formatters, headers, outfile, delim=' ')

Write a mixed-type table to a text file.

Parameters:

• arrays (list[ndarray]) – Each array is one column; all must have the same length and be of dtype int, float or str-like

• formatters (list[str]) – A printf-style format specifier for each column, e.g. [‘%s’,’%.2f’,’%04d’].

• headers (list[str]) – Column names, same length as arrays. Will be joined with delim

• outfile (str) – Path to write, or an already-open file handle.

• delim – Field delimiter.

relmt.io.write_gmt_meca_table(moment_tensors, event_dict=None, geoconverter=None, filename=None, **savetxt_kwargs)

Return input compatible with Generic Mapping Tools meca() function

Parameters:

• moment_tensors (list[MT] | dict[int, MT]) – relMT moment tensors

• event_dict (dict[int, Event] | None) – The seismic event catalog from which to source location

• geoconverter (Callable | None) – Function that accepts event north, east, depth coordinates and converts into desired output coordianted (e.g. longitude, latitude, depth)

• filename (str | Path | None) – Save output table to file

• savetxt_kwargs (dict) – When saving to file, keyword arguments are passed on to numpy.savetxt()

Returns:

ndarray – Data input for GMT or PyGMT

relmt.io.write_mt_table(mt_dict, filename=None)

Convert moment tensor dictionary to relMT compliant moment tensor table.

Number nn ee dd ne nd ed

(int) (Nm) (Nm) (Nm) (Nm) (Nm) (Nm)

Parameters:

• mt_dict (dict[int, MT] | dict[int, list[MT]]) –

  Moment Tensor dictionary

  EventIndex -> core.MT

  or

  EventIndex -> list[core.MT]

• filename (Path | str | None) – If Write table to this file

Returns:

str – Tabled moment tensor data

relmt.io.write_phase_table(phase_dict, filename=None)

Convert phase dictionary to relMT compliant phase table.

EventIndex Station Phase Arrivaltime Azimuth Plunge

(int) (code) (P/S) (seconds) (degree) (degree)

Parameters:

• phase_dict (dict[str, Phase]) – Phase dictionary PhaseID -> core.Phase

• filename (Path | str | None) – If not None, write table to this file

Returns:

str – Tabled phase data

relmt.io.write_station_table(station_dict, filename=None)

Convert station dictionary to relMT compliant station table

The resulting table has one line per station. Columns are:

Station, Northing, Easting, Depth (code), (meter), (meter),(meter)

Parameters:

• station_dict (dict) – Station dictionary: Code -> core.Station

• filename (Path | str | None) – Write table to this file

Returns:

out (str) – Tabeled station data