Edit on GitHub

Plotting

Introduction

Seis comes with plotting functionality which relies on Plots. To create plots with Seis, first install Plots:

import Pkg
Pkg.add("Plots")

Then whenever you wish to create plots for Trace objects, do

julia> using Seis.Plot, Plots

This will bring the recipes into scope.

'Recipes'

Seis.jl implements plotting via so-called 'recipes', based on the Plots plotting package. Recipes allow us to define plots for Traces without requiring the user to install Plots. However, if Plots is installed and a using Plots command has been issued, then plots for Seis's objects can be easily created.

Plotting functions

plot: Single-trace plots

plot creates a set of single-trace plots where the independent (x) axis is time, and the dependent (y) axis is the value of the trace, similar to simply plotting trace(t) against times(t).

However, plot when applied to a single Trace or an AbstractArray{<:Trace} offers options to scale plots relatively, show pick times, and so on.

Examples

1: A simple plot for a single trace, showing the picks.

using Seis, Seis.Plot, Plots
t = sample_data()
plot(t)
54 56 58 60 62 Time / s −1.5 −1.0 −0.5 0.0 0.5 1.0 1.5 F A .CDV..

2: Plot the vertical components for an earthquake with the distance in km and station code labelled.

t = sample_data(:regional)
z = filter(x -> endswith(x.sta.cha, "z"), t)
labels = z.sta.sta .* ", ∆ = " .* string.(round.(distance_km.(z), digits=1)) .* "km"
plot(z, label=labels, sort=:dist)
−4.0×10 5 −2.0×10 5 0 2.0×10 5 4.0×10 5 ELK, ∆ = 406.2km −4.0×10 4 −2.0×10 4 0 2.0×10 4 KNB, ∆ = 478.1km −4.0×10 4 −2.0×10 4 0 2.0×10 4 LAC, ∆ = 413.9km 0 50 100 150 200 250 Time / s −3.0×10 4 −2.0×10 4 −1.0×10 4 0 1.0×10 4 2.0×10 4 3.0×10 4 MNV, ∆ = 64.5km

3: Same again, but showing the falloff in amplitude with distance by setting all plots to have the same scale with the ylims option:

plot(z, label=labels, sort=:dist, ylims=:all)
−4.0×10 5 −2.0×10 5 0 2.0×10 5 4.0×10 5 ELK, ∆ = 406.2km −4.0×10 5 −2.0×10 5 0 2.0×10 5 4.0×10 5 KNB, ∆ = 478.1km −4.0×10 5 −2.0×10 5 0 2.0×10 5 4.0×10 5 LAC, ∆ = 413.9km 0 50 100 150 200 250 Time / s −4.0×10 5 −2.0×10 5 0 2.0×10 5 4.0×10 5 MNV, ∆ = 64.5km

Full docstring

Seis.Plot.plot — Function
plot(traces::AbstractArray{<:Seis.Trace}; kwargs...) -> ::Plots.Plot
plot(trace::AbstractTrace; kwargs...) -> ::Plots.Plot

Plot a set of traces as a set of separate wiggles, each with its own axes.

Additional options provided:

  • decimate: If false, do not decimate traces when plotting for speed.
  • fill_down: Set the fill colour of the negative parts of traces.
  • fill_up: Set the fill colour of the positive parts of traces. (Use line=nothing to turn off drawing of lines with the fill options.)
  • label: Set to label for each trace. This is placed in the top right corner.
  • show_picks: If false, do not plot picks.
  • sort: Sort the traces according to one of the following:
    • :dist: Epicentral distance
    • :alpha: Alphanumerically by channel code
    • ::AbstractVector: According to the indices in a vector passed in, e.g. from a call to sortperm.
  • ylims: Control y-axis limits of traces:
    • :all: All traces have same amplitude limits
source

section: Record sections

section plots a 'record section', or a set of traces where a trace's position on the y-axis is determined by some other information.

Typically record sections show traces against distance, but section supports arbitrary values or functions to place the traces.

To align traces, pass a set of values to the align keyword argument.

Examples

1: Simple distance record section for the radial components of a regional earthquake.

t = sample_data(:regional)
e, n, z = t[1:3:end], t[2:3:end], t[3:3:end]
rotate_to_gcp!.(e, n)
r, t = e, n
section(r)
0 50 100 150 200 250 Time / s 1 2 3 4 Distance / °

2: Same again, but with traces normalised so that the amplitudes are more similar.

section(r .|> normalise)
0 50 100 150 200 250 Time / s 1 2 3 4 Distance / °

3: Record section aligned on a set of picks stored with the key :A.

t = sample_data(:array)
section(t, align=:A, xlim=(-10, 20))
−10 0 10 20 Time / s 144 146 148 150 152 Distance / °

4: Section, sorted by distance but equally spaced, where traces are normalized to show how well the peaks are aligned, with the trace amplitudes scaled down by half (using the zoom keyword), and defining other Plots keywords to set the y-axis label.

section(t .|> normalize, sortperm(t, by=distance_deg), align=:A,
    xlim=(-10, 10), zoom=0.5, ylabel="Trace index, increasing distance")
−10 −5 0 5 10 Time / s 0 10 20 30 40 50 60 Trace index, increasing distance

If you have installed SeisTau.jl, then adding predicted travel times and aligning on these becomes easy.

5: Record section aligned on the predicted PKIKP arrival time, with predicted times calculated using SeisTau, called via add_picks!.

using SeisTau
add_picks!.(t, "PKIKP")
section(t, align=:PKIKP, xlim=(-10, 10))
−10 −5 0 5 10 Time / s 144 146 148 150 152 Distance / °

Full docstring

Seis.Plot.section — Function
section(traces, y_values=distance_deg.(traces); kwargs...) -> ::Plots.plot

Plot a record section for a collection of Traces. By default, the y-axis is epicentral distance in degrees, but specify one of the following for y_values to change this:

  • A Function which will be applied to the traces, e.g., distance_km.
  • A Symbol which corresponds to a field of the Traces' meta dictionary.
  • A set of values (i.e., AbstractArray)
  • One of the following strings:
    • "index" for trace index (i:length(traces))

Additional options provided via keyword arguments:

  • absscale: Set to a value to plot traces at some absolute scale. This is useful if one wants two or more sections to have the same scale.
  • align: Set to a String to align on the first pick with this name. Set to an array of values to align on the value for each trace. Set to a Symbol to use the pick of each trace with that key.
  • decimate: If false, do not perform downsampling of traces for plotting. Defaults to true.
  • fill_down: Set the fill colour of the negative parts of traces.
  • fill_up: Set the fill colour of the positive parts of traces. (Use line=nothing to turn off drawing of lines with the fill options.)
  • max_samples: Control the maximum number of samples to display at one time in order to make plotting quicker. Set decimate to false to turn this off.
  • show_picks: If true, add marks on the record section for each pick in the trace headers.
  • zoom: Set magnification scale for traces (default 1).
source

hodogram: Particle motion plots

Hododgrams, or particle motion plots, are parametric plots of two components of motion through time. These can be plotted in Seis using hodogram.

Examples

1: Hodogram of the horizontal components of an earthquake, windowed around the P-wave arrival, showing the backazimuth to the event location, and the particle motion and backazimuth label set to have different colours using the linecolor option from Plots.

t = e, n = sample_data(:regional)[1:2]
cut!.(t, 50, 70)
hodogram(e, n, backazimuth=true, linecolor=[:red :black])
−3.0×10 4 0 3.0×10 4 e −3.0×10 4 0 3.0×10 4 n Backazimuth
Seis.Plot.hodogram — Function
hodogram(t1::Trace, t2::Trace; backazimuth=false) -> ::Plots.Plot

Plot the particle motion for a pair of traces t1 and t2.

The two traces must have the same start time, length and sampling interval.

If backazimuth is true, plot the direction of the minor arc towards the event. Requires event and station coordinates to be present in headers.

source