Plotting with Plots.jl

Introduction

Seis comes with two kinds of plotting functionality. The first relies on Plots. To create plots with Seis and Plots.jl, 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.

For the other kind of plotting using Makie.jl, see the separate documentation.

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)

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)

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)

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

`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)

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

section(r .|> normalise)

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

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")

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

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).

`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])

Full docstring

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.

`plot_spectrogram`: Spectrogram plots

Spectrograms show the variation of frequency content with time for a trace. Spectrograms can be calculated with spectrogram, then plotted using plot_spectrogram.

Example

t = sample_data()
spec = spectrogram(t)
plot_spectrogram(spec)

Full docstring

Seis.Plot.plot_spectrogram — Function

plot_spectrogram(trace; powscale=:linear, normalize=true, normalise=normalize, kwargs...) -> ::Plots.Plot

Plot a spectrogram calculated with spectrogram.

powscale determines how power is scaled before plotting. It may take one of the following values:

:linear: No scaling is performed
:log10: Base-10 logarithm is taken
dB: Decibels relative to the maximum power

In addition, if powscale is a subtype of Function, then that function is applied elementwise on the matrix of power values before plotting.

If normalize or normalise are true (the default), power is scaled such that the maximum power is 1 before any further scaling is performed.

Other keyword arguments are passed to Plots.