Set up a project

1. Initialize directory

In the folder where the files of your new project should reside, call from a terminal

relmt init

Alternatively, to create a new, empty project folder, e.g. myproject/, call

relmt init myproject

This creates the following structure of directories and template files:

myproject/
+-- config.yaml
+-- exclude.yaml
+-- data/
|   +-- default-hdr.yaml
+-- align1/
+-- align2/
+-- amplitude/
+-- result/

2. Create the additional text files

relMT needs to know, where the seismic stations and events are located, at what angle the seismic rays take off and which are the values of the reference moment tensors. This information is stored in the station, event, phase and reference MT files in the data/ subfolder:

data/
+-- stations.txt
+-- events.txt
+-- phases.txt
+-- reference_mt.txt

The file names are arbitrary and must correspond to the respective entries in config.yaml:

config.yaml

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

The files obey a simple, whitespace-separated text file format. For details, see:

• Station file

• Event file

• Phase file

• Reference MT file

Tip

The following functions may be useful when creating the text files from external resources.

• To create a station file from an ObsPy Inventory object

  • relmt.extra.read_obspy_inventory_files

  • relmt.extra.read_station_inventory

  • relmt.io.write_station_table

• To create an event file from an external table

  • relmt.io.read_ext_event_table

  • relmt.io.write_event_table

• To create a phase file from a NonLinLoc .hyp file

  • relmt.io.read_phase_nll_hypfile

  • relmt.io.write_phase_table

• To create a phase file from a station file, event file and a velocity model using the SKHASH ray tracer

  • relmt.utils.phase_dict_azimuth

  • relmt.utils.phase_dict_hash_plunge

  • relmt.io.write_phase_table

• To create a reference moment tensor file from an external moment tensor table

  • relmt.io.read_ext_mt_table

  • relmt.io.write_mt_table

3. Create the waveform files

For each station and both (P, S) phases, gather all event waveforms and store them as a 3-dimensional NumPy array as waveform files. Note that the approximate wave arrival (“pick”) is assumed at the center sample.

For each waveform file, populate a corresponding header file with at least the following attributes

STATION_PHASE-hdr.yaml

# Station code
station:

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

# Event numbers corresponding to the first dimension of the waveform array.
events_:

The events_ parameter is a list of integer numbers. The position in the list corresponds to the position of the waveform along the first dimentsion of the waveform array, while the value corresponds to the event number (first row) in the event file.

Default parameters that are equal for multiple stations and phases may be declared only once in default-hdr.yaml. Any values found in a specific STATION_PHASE-hdr.yaml will overwrite the values defined here:

default-hdr.yaml

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

Example

A waveform array containing P wavetrains recorded at station “BSTA” of events 1, 3, 7, 11 and 4 (in that order), recorded on three chanels with the names “Z”, “N”, “E” (in that order) with 500 samples (e.g. 5 seconds length with 100 samples per seconds) would have a shape of (5, 3, 500). The header file would have the fields:

BSTA_P-hdr.yaml

station: BSTA
phase: P
components: "ZNE"
sampling_rate: 100
data_window: 5
events_: [1, 3, 7, 11, 4]

Tip

To create waveform arrays from an ObsPy Stream, have a look at:

• relmt.extra.make_waveform_array

4. Example data structure

For the case of three stations ‘ASTA’, ‘BSTA’, and ‘CSTA’, all of which have P- and S-wave observations, the resulting file structure would look like this:

data/
+-- stations.txt
+-- events.txt
+-- phases.txt
+-- reference_mt.txt
+-- default-hdr.yaml
+-- ASTA_P-hdr.yaml
+-- ASTA_P-wvarr.npy
+-- ASTA_S-hdr.yaml
+-- ASTA_S-wvarr.npy
+-- BSTA_P-hdr.yaml
+-- BSTA_P-wvarr.npy
+-- BSTA_S-hdr.yaml
+-- BSTA_S-wvarr.npy
+-- CSTA_P-hdr.yaml
+-- CSTA_P-wvarr.npy
+-- CSTA_S-hdr.yaml
+-- CSTA_S-wvarr.npy

Congratulations

You are now ready to align the waveforms!