RecSec: record sections#

RecordSection (abbreviated RecSec) is a record section tool used to plot a number of waveforms on a single figure. Waveforms can be processed, and sorted by various attributes, such as epicentral distance or azimuth. Data can be further modified, for example amplitudes can be scaled by expected geometrical spreading factor to visualize site amplification effects.

Note

See RecordSection class API documentation for a list of available input parameters

What it does:

  • Plot waveform data and synthetic seismograms (by themselves or together)

  • Sort source-receiver pairs by absolute or relative distance or (back)azimuth

  • Apply time shifts, zero padding, move out and amplitude scaling

  • Scale amplitudes by global maximum, trace maximum or empirical geometric spreading factor

  • Preprocess data with filters and detrends prior to plotting

Record Section via the Command Line#

To see available record section plotting commands

recsec -h  # RECordSECtion

To plot the waveform data in a record section with default parameters

recsec --pysep_path ./SAC

To plot a record section with a 7km/s move out, high-pass filtered at 1s

recsec --pysep_path ./SAC --move_out 7 --min_period_s 1

To sort your record section by azimuth and not distance (default sorting)

recsec --pysep_path ./SAC --sort_by azimuth

Have a look at the -h/–help message and the RecordSection class API documentation for more options.

Scripting RecSec#

The RECord SECtion tool can also be scripted. You can feed it the same pysep_path as in the command line usage, or directly inject ObsPy Streams.

The plotw_rs function can be used to call RecSec with some logic that allows for multi-page record sections.

Note

If using ObsPy Streams, all traces must have SAC headers with appropriate event and station locations. It is recommended that data fed into RecSec is gathered directly via PySEP to ensure appropriate SAC header values.

from obspy import read, read_inventory, read_events
from pysep import plotw_rs
from pysep.utils.cap_sac import append_sac_headers

st = read()
inv = read_inventory()
event = read_events()[0]
st = append_sac_headers(st, event, inv)  # RecordSection requires SAC header

plotw_rs(st=st, sort_by="distance", scale_by="normalize")

Have a look at the RecordSection class API documentation for available options.

Subsetting Stations#

When plotting Streams, it may be useful to subset data, e.g., by network. This can be achieved directly using ObsPy’s Stream object

st_new = st.select(network="II")
plotw_rs(st=st)

Note

This can be combined with source receiver map plotting to get a station map of the subsetted traces in the record section. See the map plotting documentation for an example of how to do this.

Customizing RecSec figures#

Much of the aesthetic look of RecSec figures is hardcoded, however there are some keyword arguments that you can provide as flags which may help to achieve publication-ready figures. Some of these parameters include:

  • ytick_fontsize: Fontsize of the Y-axis tick labels

  • xtick_fontsize: Fontsize of the X-axis tick labels

  • tick_linewidth: Linewidth of axes tick marks

  • tick_length: Length of axes tick marks

  • label_fontsize: Fontsize of X and Y axis labels

  • axis_linewidth: Linewidth of border around figure

  • title_fontsize: Fontsize of the title

  • xtick_minor: Frequency of minor ticks on the X axis

  • xtick_major: Frequency of major ticks on the X axis

To set one of these parameters, just set as a flag, e.g.,

recsec --pysep_path ./SAC --xtick_minor 100 --xtick_major 500

Or when scripting RecSec

plotw_rs(pysep_path="./SAC", xtick_minor=100, xtick_major=500)

See set_plot_aesthetic function for the entire list of available tuning options for Record Sections.

Plotting SPECFEM synthetics#

RecSec can plot SPECFEM-generated synthetic seismograms in ASCII format. Here the domain should be defined by geographic coordinates (latitude/longitude). If your domain is defined in Cartesian, see the next section.

Note

Record sections can be plotted standalone, or alongside observed seismograms to look at data-synthetic misfit.

To access metadata, RecSec requires the CMTSOLUTION and STATIONS file that are used by SPECFEM to generate the synthetics. Based on a standard SPECFEM working directory, plotting synthetics only would have the following call structure:

recsec --syn_path OUTPUT_FILES/ --cmtsolution DATA/CMTSOLUTION --stations DATA/STATIONS

Or when scripting,

plotw_rs(syn_path="OUTPUT_FILES", cmtsolution="DATA/CMTSOLUTION",
         stations="DATA/STATIONS")

You can also directly feed in an ObsPy stream containing your synthetic data with appropriate SAC headers

from glob import glob
from obspy import Stream
from pysep.utils.io import read_sem

st_syn = Stream()
for fid in glob("OUTPUT_FILES/*.semd"):
    st_syn += read_sem(fid=fid, source="DATA/CMTSOLUTION",
                       stations="DATA/STATIONS")

plotw_rs(st_syn=st_syn)

To compare observed and synthetic data, you would have name the –pysep_path and tell RecSec to preprocess both data streams identically

recsec --pysep_path ./SAC --syn_path OUTPUT_FILES/ --cmtsolution DATA/CMTSOLUTION --stations DATA/STATIONS --preprocess both

Preprocessing flags can be applied to the observed data only (st), synthetic data only (st_syn) or both (both). See the preprocess parameter in the RecordSection class API documentation

While scripting, Streams for both observed and synthetic data can be injected together:

plotw_rs(st=st, st_syn=st_syn, preprocess="both")

Plotting SPECFEM synthetics in Cartesian#

Under the hood, RecSec uses some of ObsPy’s geodetic functions to calculate distances and azimuths. Because of this, RecSec will fail if coordinates are defined in a Cartesian coordinate system (XYZ), which may often be the case when working in SPECFEM2D or in a local domain of SPECFEM3D_Cartesian.

To circumvent this, RecSec has a flag –cartesian, which will swap out the read functions to work with a Cartesian coordinate system. The call is very similar to the above:

For SPECFEM3D_Cartesian this would look like

recsec --syn_path OUTPUT_FILES --cmtsolution DATA/CMTSOLUTION --stations DATA/STATIONS --cartesian

For SPECFEM2D, the source file may not be a CMTSOLUTION. Additionally, the default seismogram components may not be defined in ZNE

recsec --syn_path OUTPUT_FILES --cmtsolution DATA/SOURCE --stations DATA/STATIONS --components Y --cartesian

While scripting, the input parameter cartesian can be used:

plotw_rs(..., cartesian=True)

Plotting two sets of synthetics (synsyn)#

It is often useful to compare two sets of synthetic seismograms, where one set represents ‘data’, while the other represents synthetics. For example, during a tomographic inversion, a Target model may be used to generate data.

RecSec can plot two sets of synthetics in a similar vein as plotting data and synthetics together. The User only needs to add the –synsyn flag and provide paths to both –pysep_path and –syn_path.

Note

RecSec makes the assumption that both sets of synthetics share the same metadata provided in the –cmtsolution and –stations flags.

Let’s say you’ve stored your ‘data’ in a directory called ‘observed/’ and your synthetics in a directory called ‘synthetic/’

recsec --pysep_path observed/ --syn_path synthetic/ --cmtsolution DATA/CMTSOLUTION --stations DATA/STATIONS --synsyn