Function index

Types

Seis.Trace — Type

Trace

Evenly-sampled time series recorded at a single seismic station. The start time of the trace, in s, is in the b property, whilst the sampling interval, in s, is delta. The trace itself is accessed using the trace method, like trace(t).

All Traces are relative to the event time evt.time if it is defined, regardless of what the event is. For example, evt.time could be the origin time of an earthquake, or a picked arrival time.

The trace then contains information about an associated Event in evt and the Station in sta. picks holds a dictionary which contains pairs of pick times relative to the origin and names (which can be missing). Access picks with the picks method, and add picks with add_pick!.

The meta Dict holds any other information about the trace.

If the event time is set, then the trace beginning time b is relative to this.

Find the trace start time relative to the origin time using starttime. The absolute start time and date, if an origin time is set, is given by startdate.

Seis.AbstractTrace — Type

AbstractTrace <: AbstractData

Abstract type from which you should subtype if creating new types of traces. AbstractTraces are time-domain recordings (or synthetics) at a single channel.

Interface

Note

The formal interface for AbstractTraces is still a work in progress and may change with a minor version increment.

The following methods should be defined for all AbstractTraces t:

trace(t): Return the data for the trace.
times(t): Return the time at each sample of t.
starttime(t): The time of the first sample.
nsamples(t): The number of samples in t.
Base.eltype(t): The element type of the data samples.
t.evt: Return the Event associated with this trace.
t.sta: Return the Station at which this trace was recorded.
t.meta: Return a SeisDict{Symbol,Any} into which metadata may be placed.

Seis.CartTrace — Type

CartTrace

Alias for Trace where Event and Station coordinates are Seis.Cartesian rather than Seis.Geographic

Seis.Event — Type

Event

Type containing information about a seismic event. Fields lon and lat are epicentral location in °; dep is depth below the reference (e.g., sea level) in km. time is a Dates.DateTime giving the event origin date and time, while id is a string holding the event identifier. meta is a Dict holding any extra information about the event.

Missing information is allowed and stored as missing.

Seis.CartEvent — Type

CartEvent{T}

Alias for Event{T, Cartesian{T}} where T, representing an Event with Cartesian coordinates.

This type is useful for dispatch, allowing one to write methods which are only applicable when a Event has Cartesian coordinates.

Example

julia> using Geodesy

julia> Geodesy.LLA(evt::CartEvent) = LLA(evt.x, evt.y, evt.z)

Seis.FourierTrace — Type

FourierTrace <: AbstractFourierTrace

The Fourier transform of a Trace.

FourierTraces contain all the information contained in their corresponding Trace, but with the addition of information on the original number of samples in the time domain trace, and an element type which much be Complex. Therefore, the fields b, delta, evt, sta, picks, and meta are all part of the public API and can be accessed the same way as for Traces.

The usual way to create FourierTraces is by calling fft on a Trace. To convert back to a Trace, call ifft.

Note

FourierTraces share many fields with the Trace they came from, including the station and event, plus picks and metadata. These fields are not copied across, and are instead references to the same Station, Event, and so on. Therefore, any changes to the FourierTrace will be reflected in the corresponding Trace. To avoid this, do f = fft(deepcopy(t)).

FourierTrace{T,V,P}(b, delta, nsamples, data, evt, sta, picks, meta)

Create a new FourierTrace which corresponds to a Trace with start time b s, sampling interval delta s and nsamples data points. data contains a set of Fourier coefficients, starting at 0 frequency up to the Nyquist frequency. (The coefficient normalisation is defined to be the same as that used by FFTW.) evt, sta, picks and meta should be taken from the original Trace.

Note

One usually creates FourierTraces by calling fft on a Trace. Users are advised to use the keyword constructor (below) if creating new FourierTraces from scratch.

FourierTrace(; b, delta, data, nsamples=(2*length(data) - 1), evt=Event(), sta=Station(), picks=nothing, meta=nothing)

Create a FourierTrace directly from a set of Fourier coefficients. Users will usually construct a FourierTrace by calling fft on a Trace instead of using this constructor.

Keyword arguments

b: The starting time in s of the original recording this frequency domain trace represents.
delta: The original sampling interval in s of the equivalent time domain trace.
data: An AbstractArray{<:Complex} containing the set of Fourier coefficients for this frequency domain trace. Note that this is a 'one-sided' set, where the first index corresponds to 0 Hz and the final index is the Nyquist frequency. This is because Traces represent real quantities.
nsamples: The number of time domain samples in the origin time domain trace which this frequency domain trace represents. This allows the FourierTrace to be converted back to the original Trace with no loss of the number of points.
evt: An Event which defines the source and origin time for the data. Normally this should be taken from the Trace being used to construct the FourierTrace.
sta: A Station which defines the recording station for the data. Normally this should be taken from the Trace being used to construct the FourierTrace.

Accessor functions

Seis.are_orthogonal — Function

are_orthogonal(sta1, sta2[, sta3]; tol) -> ::Bool
are_orthogonal(t1, t2[, t3]; tol) -> ::Bool

Return true if Stations sta1 and sta2 are orthogonal to each other, or if sta1, sta2 and sta3 form a mutually-orthogonal set.

The comparison can also be performed on Traces in the second form.

Directions are considered orthogonal if they differ from 90° by less than tol°, with a default value given by Seis._angle_tol.

Examples

julia> e, n, z = sample_data(:regional)[1:3];

julia> are_orthogonal(e, n)
true

julia> are_orthogonal(e, n, z)
true

julia> are_orthogonal(Station(azi=0, inc=90), Station(azi=91, inc=90))
false

Seis.channel_code — Function

channel_code(t::Trace) -> code
channel_code(s::Station) -> code

Return the channel code for trace t or station s, in the form of "⟨network⟩.⟨name⟩.⟨location⟩.⟨component⟩". Missing fields are left blank. The information is taken respectively from the net, sta, cha and loc fields of the Station.

Seis.dates — Function

dates(t) -> date_range

Return a date_range which contains the dates for each sample of t, so long as t.evt.time is defined. If not, an error is thrown.

N.B. This function assumes that the sampling interval t.delta is representable as an integer number of milliseconds, and rounds it accordingly. Dates.DateTimes have precision of 1 ms. An error is thrown if t.delta < 1e-3 s.

Example

julia> t = sample_data();

julia> dates(t)
1981-03-29T10:39:06.66:10 milliseconds:1981-03-29T10:39:16.65

Setter functions

Seis.add_pick! — Function

add_pick!(t, time [, name=missing]) -> ::Seis.Pick

Add an arrival time pick to the Trace t, ensuring existing picks are not overwritten, and return the Seis.Pick object added to the trace

If name is not missing, then the key of this pick will be Symbol(name), unless another pick with the same key already exists. In that case, the name will be appended with a number which increases until an available key is found.

If name is missing, then the pick is added to a numbered set of picks.

(Direct manipulation of picks is easy: just do t.picks.PKP = (1001, "PKP") to set a picks with name "PKP", time 1001 s and key :PKP.)

Example

julia> t = Trace(0, 1, 2);

julia> add_pick!.(t, [1, 2], ["A", missing]);

julia> t.picks
Seis.SeisDict{Union{Int64, Symbol},Seis.Pick{Float64}} with 2 entries:
  :A => Seis.Pick{Float64}(time=1.0, name="A")
  1  => Seis.Pick{Float64}(time=2.0, name=missing)

julia> add_pick!(t, 4)
Seis.Pick{Float64}(time=4.0, name=missing)

julia> t.picks
Seis.SeisDict{Union{Int64, Symbol},Seis.Pick{Float64}} with 3 entries:
  :A => Seis.Pick{Float64}(time=1.0, name="A")
  2  => Seis.Pick{Float64}(time=4.0, name=missing)
  1  => Seis.Pick{Float64}(time=2.0, name=missing)

julia> t.picks.A
Seis.Pick{Float64}(time=1.0, name="A")

julia> t.picks[1]
Seis.Pick{Float64}(time=2.0, name=missing)

Geometry functions

Seis.azimuth — Function

azimuth(trace; sphere=false, flattening=Geodesics.F_WGS84) -> az
azimuth(event, station; sphere=false, flattening=Geodesics.F_WGS84) -> az

Return the azimuth az from the event to the station (a seismic station) in degrees east from local north at the event for a trace. Alternatively specify the event and station individually.

Optionally specify the flattening of the ellipsoid of rotation on which this is computed, which defaults to that of the WGS84 ellipsoid. If sphere is true, then flattening is set to zero and the calculation is performed on a sphere.

Seis.backazimuth — Function

backazimuth(trace; flattening=0.0033528106718309896) -> baz
backazimuth(station, event; flattening=0.0033528106718309896) -> baz

Return the backazimuth baz from the station (a seismic station) to an event in degrees east from local north at the station for a trace. Alternatively specify the station and event individually.

Seis.distance_deg — Function

distance_deg(trace; sphere=false, flattening=0.0033528106718309896) -> Δ
distance_deg(station, event; sphere=false, flattening=0.0033528106718309896) -> Δ
distance_deg(event, station; sphere=false, flattening=0.0033528106718309896) -> Δ

For a trace or an event-station pair, return the epicentral angular distance Δ in degrees.

Seis.distance_direct — Function

distance_direct(trace)
distance_direct(event, station)
distance_direct(station, event)

For a cartesian trace or event-station pair, return the straight-line distance between them in m.

Seis.distance_km — Function

distance_km(event, station; sphere=false, a=6378.137, flattening=0.0033528106718309896) -> d

For a geographic trace or event–station pair, return the epicentral surface distance d in km between them.

Optionally specify the semimajor radius a in km and flattening of the ellipsoid of rotation on which this is computed, which defaults to that of the WGS84 ellipsoid. If sphere is true, then flattening is set to zero and the calculation is performed on a sphere.

distance_km(event, station) -> d

For a cartesian trace or event-station pair, return the epicentral distance in km between them.

Seis.incidence — Function

incidence(event, station) -> i
incidence(trace) -> i

Return the angle of incidence i° between a cartesian event and station, or a cartesian trace. The angle of incidence is defined downwards from the positive z (upward) direction.

Trace operations

Seis.cut! — Function

cut!(t, start, end; allowempty=false, warn=true) -> t

Cut a Trace t in place between start and end. An error is thrown if either start or end are missing.

An error is thrown if the trace would be empty because either the end cut time is before the start of the trace, or the start cut is after the end, unless allowempty is true.

By default, a warning is shown if cut times lie outside the trace; set warn to false to turn this off.

Example

julia> t = Trace(0, 1, [0, 1, 2, 3, 4, 5]);

julia> trace(cut!(t, 2, 4))
3-element Array{Float64,1}:
 2.0
 3.0
 4.0

cut!(t, start_date, end_date; kwargs...) -> t

Cut a Trace t in place between dates start_date and end_date.

Example

Create a trace starting at midnight on 1 January 3000, and cut to between 10 s and 1 minute after midnight:

julia> using Dates: DateTime

julia> t = Trace(0, 1, 100); # 1 Hz sampling for 100 s;

julia> t.evt.time = DateTime(3000, 1, 1); # The year 3000;

julia> cut!(t, DateTime(3000, 1, 1, 0, 0, 10), DateTime(3000, 1, 1, 0, 1, 0))
Seis.Trace{Float64,Vector{Float64},Seis.Geographic{Float64}}:
            b: 10.0
        delta: 1.0
 GeogStation{Float64}:
     sta.meta: Seis.SeisDict{Symbol, Any}()
 GeogEvent{Float64}:
     evt.time: 3000-01-01T00:00:00
     evt.meta: Seis.SeisDict{Symbol, Any}()
 Trace:
        picks: 0
         meta: 

julia> startdate(t), enddate(t)
(DateTime("3000-01-01T00:00:10"), DateTime("3000-01-01T00:01:00"))

cut!(t, pick1, offset1, pick2, offset; kwargs...) -> t
cut!(t, pick, offset1, offset2; kwargs...) ->

Cut a trace t in place between offset1 s after the first pick pick1 and offset2 s after pick2.

In the second form, both offsets are relative to pick.

The values of pick1, pick2 and pick are passed to picks and so may be a Symbol (giving the key of the pick), a String (giving the pick name) or a Regex (which matches the pick name).

Example

julia> t = sample_data();

julia> starttime(t), endtime(t)
(52.66f0, 62.65f0)

julia> cut!(t, :A, 0, :F, 1);

julia> starttime(t), endtime(t)
(53.67f0, 61.979996f0)

Seis.cut — Function

cut(t, start, end; kwargs...) -> t′
cut(t, start_date, end_date; kwargs...) -> t′
cut(t, pick1, offset1, pick2, offset2; kwargs...) -> t′
cut(t, pick, offset1, offset2; kwargs...) -> t′

Return a copy of the trace t cut between start and end s relative to the event origin. You may also specify a start_date and end_date, or choose times offset1 and offset2 s relative to pick1 and pick2 respectively. Both offset times may also be specified relative to one pick.

See also: fft.

Seis.integrate! — Function

integrate!(t::Trace, method=:trapezium) -> t
integrate(t::Trace, method=:trapezium) -> t′

Replace t with its time-integral. This is done by default using the trapezium rule. Use method=:rectangle to use the rectangle rule.

In the first form, update the trace in place and return the trace. In the second form, return an updated copy.

If method==:trapezium (the default), then the number of samples is reduced by one and the begin time is increased by half the sampling interval.

Example

julia> t = Trace(0, 0.1, [0, 1, 1, 0]);

julia> trace(integrate(t))
3-element Array{Float64,1}:
 0.05
 0.15000000000000002
 0.2

julia> trace(integrate(t, :rectangle))
4-element Array{Float64,1}:
 0.0
 0.1
 0.2
 0.2

integrate!(t::AbstractFourierTrace) -> t

Integrate the frequency-domain trace t in the Fourier domain by dividing the cofficients $Y_k$ by $2\pi f_k i k$, where $k <= N/2$ and $N$ is the number of samples in the time-domain trace ifft(t) and $f_k$ is the frequency corresponding to that coefficient. The operation is performed in-place.

Note that in this implementation, the zero-frequency (DC) term is set to zero, such that differentiating the result of this function may produce a different trace to that which was originally integrated.

To return an updated copy, use the out-of-place form integrate(::AbstractFourierTrace).

Seis.integrate — Function

integrate!(t::Trace, method=:trapezium) -> t
integrate(t::Trace, method=:trapezium) -> t′

Replace t with its time-integral. This is done by default using the trapezium rule. Use method=:rectangle to use the rectangle rule.

In the first form, update the trace in place and return the trace. In the second form, return an updated copy.

If method==:trapezium (the default), then the number of samples is reduced by one and the begin time is increased by half the sampling interval.

Example

julia> t = Trace(0, 0.1, [0, 1, 1, 0]);

julia> trace(integrate(t))
3-element Array{Float64,1}:
 0.05
 0.15000000000000002
 0.2

julia> trace(integrate(t, :rectangle))
4-element Array{Float64,1}:
 0.0
 0.1
 0.2
 0.2

Base.merge! — Method

merge!(t1::AbstractTrace, ts::AbstractArray{<:AbstractTrace}; gaps=:zero, overlaps=:mean, sample_tol=0.1, check=true) -> t1
merge!(t1, ts...; kwargs...) -> t1
merge!([t1, ts...]; kwargs...) -> t1

merge(t1::AbstractTrace, ts::AbstractArray{<:AbstractTrace}; gaps=:zero, overlaps=:mean, sample_tol=0.1, check=true) -> t1
merge(t1, ts...; kwargs...) -> t1
merge([t1, ts...]; kwargs...) -> t1

Merge two or more traces together into the first trace, retaining only station and event information from the first trace.

In the first form, update the trace in place and return the trace. In the second form, return an updated copy.

All traces must have the same sampling interval. They must also have the same channel code (see channel_code), unless check is false. The traces do not need to have the same element type or geometry.

Where gaps between traces occur, these may be filled in a number of different ways, or an error may be thrown. Tapering may be applied to the data either side of gaps. See 'Keyword arguments' below for details.

Likewise, where overlaps occur, either data from the first or last trace in each overlap may be used, or the mean of the traces used. Other options are also possible.

If the start times of traces (and hence each sample itself) are not quantised in time in the same way, then an error is thrown, unless the difference in quantisation is less than a fraction of sample_tol of the sampling interval. Hence sample_tol should be between 0 and 0.5.

If all traces have an event time set, then merging is done in absolute time. If not all have an event time set, then all times are assumed to be relative to the same origin and only the traces' b fields are used. To perform merging in relative time regardless of whether the origin time is set, pass relative = true.

Empty traces are checked for matching channel codes, but are not otherwise merged into the final trace. If all traces are empty, the first is returned unaltered.

Keyword arguments

gaps

gaps controls how gaps between continuous segments of data are treated, and may take one of the following values:

:zero (default): Fill any gaps with zero
:error: Throw an error if any gaps are present
:linear: Linearly interpolate between the last sample before the gap and the first sample after the gap. Cannot be used with tapering.
value: Fill with value, which must be convertable to the element type of t1.

overlaps

overlaps controls how the new merged trace uses traces which overlap in time, and may take one of the following values:

:mean (default): Take the mean of the values at each overlapping sample
:first: Use the data from the first (in time) trace in the overlap
:last: Use the data from the last (in time) trace
:zero: Zero out any overlapping periods
:error: Throw an error if any overlaps are present and the data are not identical. (Note that the error type is not at present defined but may be in a future version.)
value: Fill with value, which must be convertable to the element type of t1.

sample_tol

Any trace which does not have its samples quantised to the same as t1 to within a fraction of a sampling interval sample_tol will cause an error to be thrown. Set this to a value between 0 and 0.5 to control this. A value of 0.5 will mean any quantisation differences are ignored.

taper

If taper is set to a fractional width, a taper is performed on the ends of traces adjoining gaps, with taper defining the proportional length of the taper relative to the gap length. Values are tapered to 0.

Note that if taper is used with a number for gaps, then sharp jumps will occur at the first and last sample of each gap to whatever value is supplied to the gaps argument

taper_form

Determines the type of taper applied around gaps if taper is set. This can be one of :hanning (the default), :hamming or :cosine. See taper! for details.

relative

If relative is true, then ignore any origin times in traces and merge them all only with regard to their starttime. By default merging is done in absolute time if all traces have .evt.time set.

metadata

If true (the default), then entries in the .meta field of each trace are merged into the .meta field of the first trace. Entries of the first trace are preserved, while entries not in the first trace are added in turn from the last trace to the first. This means duplicate entries are not overwritten in the first trace, and entries present in more than one of the other traces are taken from the second, third, etc., trace in preference to any later traces.

Base.merge — Method

merge(t1::AbstractTrace, t2::AbstractTrace...) -> t_merged
merge(t1::AbstractTrace, ::Vararg{AbstractTrace}) -> t_merged
merge(ts::AbstractArray{<:AbstractTrace}) -> t_merged

For details of out-of-place trace merging, see merge!.

Seis.normalise! — Function

normalise!(t::Trace, val=1) -> t
normalise(t::Trace, val=1) -> t′

Normalise the trace t so that its maximum absolute amplitude is val. In the first form, update the trace in place and return the trace. In the second form, return an updated copy.

This function can also be spelled normalize[!].

Example

julia> t = Trace(0, 0.1, [0, -1, 2]);

julia> trace(normalise(t))
3-element Array{Float64,1}:
  0.0
 -0.5
  1.0

julia> trace(normalise(t, 2))
3-element Array{Float64,1}:
  0.0
 -1.0
  2.0

Seis.normalise — Function

normalise!(t::Trace, val=1) -> t
normalise(t::Trace, val=1) -> t′

Normalise the trace t so that its maximum absolute amplitude is val. In the first form, update the trace in place and return the trace. In the second form, return an updated copy.

This function can also be spelled normalize[!].

Example

julia> t = Trace(0, 0.1, [0, -1, 2]);

julia> trace(normalise(t))
3-element Array{Float64,1}:
  0.0
 -0.5
  1.0

julia> trace(normalise(t, 2))
3-element Array{Float64,1}:
  0.0
 -1.0
  2.0

LinearAlgebra.normalize! — Function

normalise!(t::Trace, val=1) -> t
normalise(t::Trace, val=1) -> t′

Normalise the trace t so that its maximum absolute amplitude is val. In the first form, update the trace in place and return the trace. In the second form, return an updated copy.

This function can also be spelled normalize[!].

Example

julia> t = Trace(0, 0.1, [0, -1, 2]);

julia> trace(normalise(t))
3-element Array{Float64,1}:
  0.0
 -0.5
  1.0

julia> trace(normalise(t, 2))
3-element Array{Float64,1}:
  0.0
 -1.0
  2.0

LinearAlgebra.normalize — Function

normalise!(t::Trace, val=1) -> t
normalise(t::Trace, val=1) -> t′

Normalise the trace t so that its maximum absolute amplitude is val. In the first form, update the trace in place and return the trace. In the second form, return an updated copy.

This function can also be spelled normalize[!].

Example

julia> t = Trace(0, 0.1, [0, -1, 2]);

julia> trace(normalise(t))
3-element Array{Float64,1}:
  0.0
 -0.5
  1.0

julia> trace(normalise(t, 2))
3-element Array{Float64,1}:
  0.0
 -1.0
  2.0

Seis.remove_mean! — Function

remove_mean!(t::Trace) -> t
remove_mean(t::Trace) -> t′

Remove the mean of trace t. In the first form, update the trace in place and return it. In the second form, return an updated copy.

Example

julia> t = Trace(0, 0.01, [1, 1, 3, -1]);

julia> trace(remove_mean(t))
4-element Array{Float64,1}:
  0.0
  0.0
  2.0
 -2.0

Seis.remove_mean — Function

remove_mean!(t::Trace) -> t
remove_mean(t::Trace) -> t′

Remove the mean of trace t. In the first form, update the trace in place and return it. In the second form, return an updated copy.

Example

julia> t = Trace(0, 0.01, [1, 1, 3, -1]);

julia> trace(remove_mean(t))
4-element Array{Float64,1}:
  0.0
  0.0
  2.0
 -2.0

Seis.remove_trend! — Function

remove_trend!(t::Trace) -> t
remove_trend(t::Trace) -> t′

Remove the trend from t. In the first form, update the trace in place and return it. In the second form, return an updated copy.

Example

julia> t = Trace(0, 0.2, [1, 2, 3, 4]);

julia> trace(remove_trend(t))
4-element Array{Float64,1}:
 -2.220446049250313e-16
  0.0
  0.0
  4.440892098500626e-16

Seis.remove_trend — Function

remove_trend!(t::Trace) -> t
remove_trend(t::Trace) -> t′

Remove the trend from t. In the first form, update the trace in place and return it. In the second form, return an updated copy.

Example

julia> t = Trace(0, 0.2, [1, 2, 3, 4]);

julia> trace(remove_trend(t))
4-element Array{Float64,1}:
 -2.220446049250313e-16
  0.0
  0.0
  4.440892098500626e-16

Seis.resample! — Function

resample!(t::AbstractTrace; delta, n) -> t
resample(t::AbstractTrace; delta, n) -> t′

Resample the trace t so that either the sampling interval becomes delta s, or its sampling rate is increased n times. One of delta or n must be given.

In the first form, update the trace in place and return it. In the second form, return an updated copy (t′).

The functions uses DSP.resample to perform the operation, which applies an antialias filter and 'additional operations' to prevent aliasing and minimise other artifacts.

To perform decimation without antialiasing, use decimate or decimate! with antialias=false.

Example

julia> t = Trace(0, 0.5, 1:4);

julia> trace(resample(t, 3))

DSP.Filters.resample — Function

resample!(t::AbstractTrace; delta, n) -> t
resample(t::AbstractTrace; delta, n) -> t′

Resample the trace t so that either the sampling interval becomes delta s, or its sampling rate is increased n times. One of delta or n must be given.

In the first form, update the trace in place and return it. In the second form, return an updated copy (t′).

The functions uses DSP.resample to perform the operation, which applies an antialias filter and 'additional operations' to prevent aliasing and minimise other artifacts.

To perform decimation without antialiasing, use decimate or decimate! with antialias=false.

Example

julia> t = Trace(0, 0.5, 1:4);

julia> trace(resample(t, 3))

DSP.Periodograms.spectrogram — Method

spectrogram(trace::AbstractTrace; length=(endtime(t) - starttime(t))/20, overlap=0.5, window=nothing, pad=nothing) -> spec

Calculate the spectrogram for the data in trace. Each segment is length s long, and overlaps with the next by a fraction of overlap (i.e., overlap must be 0 s or greater, and less than 1). Note that these values are rounded to an integer number of samples in both cases.

Windows are by default padded to the next length which allows for fast FFT computation. Setting pad to a number larger than 1 pads the trace with zeroes to the nearest integer length which is pad times the trace length. This allows for finer sampling in frequency space.

By default, no windowing of each segment (of length s) is performed; pass a windowing function or vector of amplitudes to window to window each segment before the periodogram is computed. See DSP.periodogram for more details of the kind of windowing which is possible. (The spectrogram calculation is performed by DSP.spectrogram and returns a DSP.Periodograms.Spectrogram object.)

Examples

julia> t = sample_data();

julia> spec = spectrogram(t);

julia> spec.time
52.90999984741211:0.25:62.40999984741211

Seis.taper! — Function

taper!(t::AbstractTrace, width=0.05; left=true, right=true, form=:hanning, time=nothing) -> t
taper(t::AbstractTrace, width=0.05; left=true, right=true, form=:hamming, time=nothing) -> t′

Apply a taper to the ends of the data in trace t. form may be one of :hanning, :hamming or :cosine. width represents the fraction (at both ends) of the trace tapered, up to 0.5.

Optionally, specify time as an absolute length in time for the tapering period (at both ends), in which case width is ignored.

By default, tapering is applied to both ends. If left is false, then only the 'right' end (later in time part) of the trace is tapered; and vice versa.

In the first form, update the trace in place and return it. In the second form, return an updated copy.

Example

julia> t = Trace(0, 1, [-1, 1, -1, 1, -1, 1]);

julia> trace(taper(t))
6-element Array{Float64,1}:
 -0.0
  0.49999999999999994
 -1.0
  1.0
 -0.49999999999999994
  0.0

julia> trace(taper(t; time=0.25))
6-element Vector{Float64}:
 -0.0
  0.49999999999999994
 -1.0
  1.0
 -0.49999999999999994
  0.0

julia> trace(taper(t; right=false))
6-element Vector{Float64}:
 -0.0
  0.49999999999999994
 -1.0
  1.0
 -1.0
  1.0

Seis.taper — Function

taper!(t::AbstractTrace, width=0.05; left=true, right=true, form=:hanning, time=nothing) -> t
taper(t::AbstractTrace, width=0.05; left=true, right=true, form=:hamming, time=nothing) -> t′

Apply a taper to the ends of the data in trace t. form may be one of :hanning, :hamming or :cosine. width represents the fraction (at both ends) of the trace tapered, up to 0.5.

Optionally, specify time as an absolute length in time for the tapering period (at both ends), in which case width is ignored.

By default, tapering is applied to both ends. If left is false, then only the 'right' end (later in time part) of the trace is tapered; and vice versa.

In the first form, update the trace in place and return it. In the second form, return an updated copy.

Example

julia> t = Trace(0, 1, [-1, 1, -1, 1, -1, 1]);

julia> trace(taper(t))
6-element Array{Float64,1}:
 -0.0
  0.49999999999999994
 -1.0
  1.0
 -0.49999999999999994
  0.0

julia> trace(taper(t; time=0.25))
6-element Vector{Float64}:
 -0.0
  0.49999999999999994
 -1.0
  1.0
 -0.49999999999999994
  0.0

julia> trace(taper(t; right=false))
6-element Vector{Float64}:
 -0.0
  0.49999999999999994
 -1.0
  1.0
 -1.0
  1.0

Filtering

Seis.bandstop! — Function

bandstop!(t::Trace, f1, f2; poles=2, twopass=false, kind=DSP.Butterworth(poles)) -> t
bandstop(t::Trace, f1, f2; poles=2, twopass=false, kind=DSP.Butterworth(poles)) -> t′

Apply a bandreject filter to the trace t with stop band between frequencies f1 and f2 in Hz. In the first form, update the trace in place and return it. In the second form, return an updated copy.

Optionally specify the number of poles of the filter, and whether a two-pass filter should be applied. This doubles the effective number of poles, because both a forward and reverse pass occur. This has the advantage of preserving the phase.

Specify the kind of filter by providing a kind from the DSP.Filters module. If doing so, the poles keyword argument is not used and the number of poles, ripple power, etc., should be specified when providing the filter kind.

Seis.bandstop — Function

bandstop!(t::Trace, f1, f2; poles=2, twopass=false, kind=DSP.Butterworth(poles)) -> t
bandstop(t::Trace, f1, f2; poles=2, twopass=false, kind=DSP.Butterworth(poles)) -> t′

Seis.bandpass! — Function

bandpass!(t::Trace, f1, f2; poles=2, twopass=false) -> t
bandpass(t::Trace, f1, f2; poles=2, twopass=false) -> t′

Apply a bandpass filter to the trace t between frequencies f1 and f2 in Hz. In the first form, update the trace in place and return it. In the second form, return an updated copy.

Seis.bandpass — Function

bandpass!(t::Trace, f1, f2; poles=2, twopass=false) -> t
bandpass(t::Trace, f1, f2; poles=2, twopass=false) -> t′

Apply a bandpass filter to the trace t between frequencies f1 and f2 in Hz. In the first form, update the trace in place and return it. In the second form, return an updated copy.

Seis.highpass! — Function

highpass!(t::Trace, f; poles=2, twopass=false, kind=DSP.Butterworth(poles)) -> t
highpass(t::Trace, f; poles=2, twopass=false, kind=DSP.Butterworth(poles)) -> t′

Apply a highpass filter to the trace t with corner frequency f in Hz. In the first form, update the trace in place and return it. In the second form, return an updated copy.

Seis.highpass — Function

highpass!(t::Trace, f; poles=2, twopass=false, kind=DSP.Butterworth(poles)) -> t
highpass(t::Trace, f; poles=2, twopass=false, kind=DSP.Butterworth(poles)) -> t′

Apply a highpass filter to the trace t with corner frequency f in Hz. In the first form, update the trace in place and return it. In the second form, return an updated copy.

Seis.lowpass! — Function

lowpass!(t::Trace, f; poles=2, twopass=false, kind=DSP.Butterworth(poles)) -> t
lowpass(t::Trace, f; poles=2, twopass=false, kind=DSP.Butterworth(poles)) -> t′

Apply a lowpass filter to the trace t with corner frequency f in Hz. In the first form, update the trace in place and return it. In the second form, return an updated copy.

Seis.lowpass — Function

lowpass!(t::Trace, f; poles=2, twopass=false, kind=DSP.Butterworth(poles)) -> t
lowpass(t::Trace, f; poles=2, twopass=false, kind=DSP.Butterworth(poles)) -> t′

Apply a lowpass filter to the trace t with corner frequency f in Hz. In the first form, update the trace in place and return it. In the second form, return an updated copy.

Trace rotation

Seis.rotate_through! — Function

rotate_through!(t1::Trace, t2::Trace, phi[; tol]) -> t1, t2

For two traces t1 an t2 which are orthgonal, rotate them by phi° from t1 towards t2. Note therefore that the order of the arguments matters and opposite rotations can be achieved by swapping t1 and t2. Neither of the traces need to be horizontal.

This is a reference frame transformation (passive rotation) and hence particle motion will appear to rotate from t2 to t1.

Trace channel names are updated to contain the azimuth if both channels are horizontals.

The optional keyword argument tol specifies the angle in ° by which the traces must be orthogonal; see are_orthogonal.

Example

julia> e, n = sample_data(:local)[1:2];

julia> rotate_through!(n, e, 20); # Rotate 20° clockwise looking down

julia> n.sta.azi, e.sta.azi
(20.0f0, 110.0f0)

julia> rotate_through!(e, n, 20); # Rotate in opposite direction

julia> n.sta.azi, e.sta.azi
(6.5939315f-7, 90.0f0)

Seis.rotate_through — Function

rotate_through!(t1::Trace, t2::Trace, phi[; tol]) -> t1, t2

This is a reference frame transformation (passive rotation) and hence particle motion will appear to rotate from t2 to t1.

Trace channel names are updated to contain the azimuth if both channels are horizontals.

The optional keyword argument tol specifies the angle in ° by which the traces must be orthogonal; see are_orthogonal.

Example

julia> e, n = sample_data(:local)[1:2];

julia> rotate_through!(n, e, 20); # Rotate 20° clockwise looking down

julia> n.sta.azi, e.sta.azi
(20.0f0, 110.0f0)

julia> rotate_through!(e, n, 20); # Rotate in opposite direction

julia> n.sta.azi, e.sta.azi
(6.5939315f-7, 90.0f0)

Seis.rotate_to_enz! — Function

rotate_to_enz!(t1, t2, t3[; tol]) -> e, n, z

Rotate three orthogonal traces t1, t2 and t3 in place so that they point east (e), north (n) and vertically (z).

e, n and z are bindings to the same data as t1, t2 and t3, but they may not be returned in the same order as passed in if the original set of traces are not given as a right-handed set.

Seis.rotate_to_enz — Function

rotate_to_enz(t1, t2, t3[; tol]) -> e, n, z

Copying version of rotate_to_enz!.

Seis.rotate_to_gcp! — Function

rotate_to_gcp!(t1, t2; reverse=false, tol) -> t1, t2

Rotate the pair of traces t1 and t2 in place so that t1 points along the radial direction (the backazimuth plus 180°), and t2 is 90° clockwise from that.

If reverse is true, then t2 is rotated to be 90° anticlockwise from t1, so that the polarity is reversed.

The component names of the radial and transverse traces are updated to be 'R', and either 'T' or '-T' respectively for normal and reverse polarity, unless the component code is a valid SEED identifier which seems rotatable and matches for the traces; then the correct component name is used. (E.g., "BHE" and "BHN" become "BHR" and "BHT".)

Traces must be orthogonal and horizontal. The optional keyword argument tol specifies the angle in ° by which the traces must be orthogonal; see are_orthogonal.

rotate_to_gcp!(t::AbstractArray{T}; kwargs...) -> t

Rotate pairs of traces in the array t so they are in the order [R1, T1, R2, T2, ...].

Seis.rotate_to_gcp — Function

rotate_to_gcp(t1, t2; reverse=false[, tol]) -> R, T
rotate_to_gcp(t::AbstractArray{<:AbstractTrace}; reverse=false[, tol]) -> t′

Copying version of rotate_to_gcp! which returns the radial R and transverse T traces in the first form, or pairs of radial and transverse traces in the modified array t′

Seis.rotate_to_lqt! — Function

rotate_to_lqt!(t1, t2, t3; [tol]) -> L, Q, T
rotate_to_lqt!(t1, t2, t3, incidence; [tol]) -> L, Q, T
rotate_to_lqt!(t1, t2, t3, azimuth, incidence; [tol]) -> L, Q, T

Rotate the three traces t1, t2 and t3 in place, and return them in the order L, Q and T, forming a right-handed set.

The L trace records positive motion along the event-receiver direction, defined by the local azimuth at the receiver (i.e., backazimuth + 180°) and incidence angle (measured downwards away from the positive upwards direction).

The T direction is transverse to L, such that when looking along the direction towards the station, T is on the right and lies in the horizontal plane.

The Q direction is perpendicular to both, lying in the saggital plane, with some component in the vertical direction.

If azimuth and inclination are not passed in explicitly, then they are determined using the event-station geometry. This is only possible for both for Traces in Cartesian geometry, since inclination is not well-determined in a geographic system. Geographic-system traces (the default) must pass at least the inclination. For the Cartesian case, we assume straight-line paths between event and receiver.

tol specifies the angle in ° by which the traces must be orthogonal; see are_orthogonal

Note

If incidence is 0° or 90° (the direction is vertical), then the choice of Q and T is arbitrary and simply chosen such that Q points along the local azimuth.

Diagram

Plan view

 ⋆ (event)       North
  `                ↑
    `              |
      `            |
        `
          ∇ (station)
         ⊙ `
      -  Q   `
    ↙          ↘
   T            L

Side view

                 Q
                 ↑
 Up               |
 ↑                 |
 |                  |      __ → L
 |      (station)  ∇ ⊙__---
             .__--   T
        .__--
    __--
  ⋆ (event)

Examples

julia> e, n, z = sample_data(:regional)[1:3];

julia> azi = azimuth(e) + 180
216.85858118935954

julia> inc = 30; # Determined from other calculation

julia> l, q, t = rotate_to_lqt!(e, n, z, azi, inc)
(Seis.Trace(.ELK..1: delta=0.025, b=-5.000015, nsamples=12000), Seis.Trace(.ELK..2: delta=0.025, b=-5.000015, nsamples=12000), Seis.Trace(.ELK..T: delta=0.025, b=-5.000015, nsamples=12000))

julia> l.sta.azi, l.sta.inc, l.sta.cha
(216.85858f0, 30.0f0, "1")

julia> t.sta.cha
"T"

julia> l == e, q == n, t == z # Original traces are modified and returned in a possibly different order
(true, true, true)

Seis.rotate_to_lqt — Function

rotate_to_lqt(t1, t2, t3[, azimuth[, incidence]; tol) -> l, q, t

Copying version of rotate_to_lqt!.

Seis.rotate_to_azimuth_incidence! — Function

rotate_to_azimuth_incidence!(t1, t2, t3, azimuth, incidence[; tol]) -> x, y, z

Rotate a mutually-orthogonal set of traces t1, t2 and t3 such that the trace x points along the direction defined by azimuth, y points perpendicular to x and has components only in the direction along azimuth and the vertical; z is perpendicular to both and lies in the horizontal plane. x, y and z form a right-handed set and are commonly known as L, Q and T respectively. (See rotate_to_lqt!.)

Note that in this form, the underlying data and metadata in the input traces is altered, and the returned traces point to the same data as the input traces, but possibly in a different order. Use rotate_to_azimuth_incidence to return copies of the traces and leave the original traces unmodified.

Seis.rotate_to_azimuth_incidence — Function

rotate_to_azimuth_incidence(t1, t2, t3, azimuth, incidence[; tol]) -> x, y, z

Copying version of rotate_to_azimuth_incidence.

Seis.sort_traces_right_handed — Function

sort_traces_right_handed(t1, t2, t3) -> x, y, z, perm

Sort the traces t1, t2 and t3 such that they form a right-handed set; requiring the traces to be mutually orthogonal. The direction of x, y and z are arbitrary. perm is a length-three tuple containing the indices (from 1 to 3) of the new order of traces, such that x is (t1, t2, t3)[perm[1]] and so on.

Example

julia> e, n, z = sample_data(:regional)[1:3];

julia> e.sta.cha, n.sta.cha, z.sta.cha # Confirm the order
("e", "n", "z")

julia> u, v, w, perm = Seis.sort_traces_right_handed(n, e, z); # A left-handed arrangement

julia> [u, v, w].sta.cha
3-element Vector{String}:
 "n"
 "z"
 "e"

julia> [n, e, z][[perm...]] # Indexing by perm gives us the new order
3-element Vector{Trace{Float32, Vector{Float32}, Seis.Geographic{Float32}}}:
 Seis.Trace(.ELK..n: delta=0.025, b=-5.000015, nsamples=12000)
 Seis.Trace(.ELK..z: delta=0.025, b=-5.000015, nsamples=12000)
 Seis.Trace(.ELK..e: delta=0.025, b=-5.000015, nsamples=12000)

IO

Seis.read_mseed — Function

read_mseed(file; kwargs...) -> traces
read_mseed(file, T; kwargs...) -> traces::Vector{T}

Read a single miniseed file from disk and return a set of Traces.

The meta.mseed_file field of each trace contains the file name.

Optionally specify the type of trace T <: AbstractTrace to read. By default, T is Trace{Float64, Vector{Float32}, Seis.Geographic{Float64}}, since almost all seismic data stored in Miniseed format is single-precision, and because the sampling rate is stored at a 64-bit float in miniSEED files.

Example

Read a single file:

julia> read_mseed("data.mseed")

Read a single file assuming a Cartesian geometry:

julia> read_mseed(CartTrace{Float64, Vector{Float32}}, "data.mseed")

Handling gapped/overlapped data

When channels containing gaps or overlaps are encountered, they are split into multiple Traces as each Trace must be continuous and evenly sampled. However, data quite often contain single-sample offsets which are later corrected, and so these are ignored by default.

Use the keyword argument maximum_gap to control whether or not gaps cause new traces to be created. See below for more details.

Keyword arguments

The following keyword arguments can be passed to read_mseed:

headers_only = false: If true, only read trace header information, leaving the returned traces empty. In this case, the following additional fields in .meta are set:
- mseed_nsamples: Number of samples in the trace
- mseed_enddate: DateTime of the final sample
- mseed_endtime: Time of the final sample
maximum_gap: The maximum absolute gap length in s beyond which gaps are no longer tolerated in a single trace. By default this is the sampling interval of the trace being read.
Note
Set maximum_gap to 0 to always split miniseed files into separate traces at all gaps.
verbose = 0: An integer starting from 0 upwards indicating how much information about the reding process should be printed to the screen. The default (0) only produces output for errors and warnings.

read_mseed(data::Vector{UInt8}[, T]; kwargs...) -> traces

Read Miniseed data from memory, held as a set of bytes, optionally specifying the type T of traces to return. Keyword arguments are the same as for reading from a file on disk.

read_mseed(pattern, dir) -> ::Vector{<:Trace}
read_mseed(pattern, dir, T) -> Vector{T}

Read all files matching pattern in directory dir.

See Glob.glob for details of pattern matching.

Optionally specify the type of trace T <: AbstractTrace to read.

Example

Read all files matching "TA.*.BHZ.mseed" in all directories within DATA which themselves match "Event_??":

julia> read_mseed("Event_??/TA.*.BHZ.mseed", "DATA")

Seis.read_sac — Function

read_sac(file; terse=false, header_only=true) → ::Trace

Read a single evenly-sampled SAC file and return a Trace. If terse is true, then warn when auto-byteswapping files.

Example

julia> file = joinpath(dirname(pathof(Seis)), "..", "data", "seis.sac");

julia> t = read_sac(file)
Seis.Trace{Float32,Vector{Float32},Seis.Geographic{Float32}}:
            b: 52.66
        delta: 0.01
 GeogStation{Float32}:
      sta.lon: -120.0
      sta.lat: 48.0
      sta.sta: CDV
      sta.azi: 0.0
      sta.inc: 0.0
     sta.meta: Seis.SeisDict{Symbol, Any}()
 GeogEvent{Float32}:
      evt.lon: -125.0
      evt.lat: 48.0
      evt.dep: 0.0
     evt.time: 1981-03-29T10:38:14
       evt.id: K8108838
     evt.meta: Seis.SeisDict{Symbol, Any}()
 Trace:
        picks: 2
         meta: SAC_lpspol => true
               SAC_nevid => 0
               SAC_iftype => 1
               file => "src/../data/seis.sac"
               SAC_idep => 50
               SAC_iztype => 9
               SAC_lcalda => true
               SAC_unused18 => false
               SAC_lovrok => true
               SAC_norid => 0
               SAC_ievtyp => 42

Reading only headers

To read only the headers from a SAC file, returning an empty trace, set header_only to true. In this case, the trace's meta dictionary contains a pair :SAC_npts => npts, where npts is the number of data points as held in the SAC file's header. Traces read from SAC files with header_only can used to overwrite the headers of files on disk, so long as npts is consistent.

read_sac(glob, dir; echo=false, header_only=false) → ::Vector{Trace}

Read SAC files which match the patern glob in directory dir and return a set of Traces. Add the file names to t.meta.file. These are relative paths.

File names matching the pattern are shown if echo is true.

Example

julia> dir = joinpath(dirname(pathof(Seis)), "..", "data", "local");

julia> t = read_sac("*.z", dir)
9-element Vector{Trace{Float32, Vector{Float32}, Seis.Geographic{Float32}}}:
 Seis.Trace(.CALZ..: delta=0.01017683, b=-7.690632, nsamples=3933)
 Seis.Trace(.CAOZ..: delta=0.01017683, b=-7.690632, nsamples=3933)
 Seis.Trace(.CDAZ..: delta=0.01017683, b=-7.690632, nsamples=3933)
 Seis.Trace(.CDVZ..: delta=0.01017683, b=-7.690632, nsamples=3933)
 Seis.Trace(.CMNZ..: delta=0.01017683, b=-7.690632, nsamples=3933)
 Seis.Trace(.CPSZ..: delta=0.01017683, b=-7.690632, nsamples=3933)
 Seis.Trace(.CVAZ..: delta=0.01017683, b=-7.690632, nsamples=3933)
 Seis.Trace(.CVLZ..: delta=0.01017683, b=-7.690632, nsamples=3933)
 Seis.Trace(.CVYZ..: delta=0.01017683, b=-7.690632, nsamples=3933)

SAC header conventions

When reading SAC files, the following conventions are observed:

The event id is held in header KEVNM
Channel ID is held in KCMPNM
Location ID is held in KHOLE
If O and the file origin time parameters are set, O is shifted to 0 time, and all time picks are adjusted. This is similar to using the commands ch o gmt [date]; ch allt (0 - &1,o&) to set the origin in SAC.
Time picks are added to the Trace picks.

SAC headers which don't directly translate to Trace attributes are placed in the .meta field and have names prefixed by "SAC_".

Seis.write_mseed — Function

write_mseed(file, t; append=false, verbose=0, pubversion=1, record_length=nothing, version=2)

Write the data contained in the trace(s) t to file on disk in miniSEED format.

t may be either a single AbstractTrace, or an array of AbstractTraces.

miniSEED files can contain data in (amongst others) in Float32, Float64 and Int32 format. This function will use whatever precision or type the data in t have and attempt to write. If for example you want to write a trace with a Float64 element type to a miniSEED file with element type Float32, you should first convert the trace using convert. (Note that since Seis does not support integer-valued trace data, it will not write 32-bit integer miniSEED files.)

If the trace does not have an origin time set, an error is thrown.

Keyword arguments

append::Bool: If true, add the data in t to the end of any data already existing in file. miniSEED files can contain multiples traces.
verbose::Integer: Controls the verbosity of the miniSEED conversion and writing process. Larger values of verbose cause more output to be produced.
pubversion::Integer: The publication version of data describes whether a set of data has been updated since being initially published. Higher numbers correspond to records which supercede lower versions, which start at 1 (the default).
record_length::Integer: The number of bytes used to write each miniSEED record.
version: The miniSEED file version to write. Can be 2 (the default) or 3.

Seis.write_sac — Function

write_sac(t, file; littleendian=false)
write_sac(t, io::IO; littleendian=false)

Write the Trace t to a file on disk or an IO object in SAC format.

Keys in the t.meta field which begin with SAC_ have their values written to the corresponding SAC field (e.g., t.meta.SAC_kuser0 is written to the KUSER0 header). The user is responsible for ensuring that the values corresponding to these keys can be converted to the correct header type. Note also that SAC_ meta fields override the equivalent Trace headers (e.g., t.sta.sta is equivalent to SAC_kstnm) and so one way to override the values in Trace headers is to set the SAC_ fields. Note that the header is lowercase (i.e., SAC_kstnm not SAC_KSTNM).

Time picks with keys corresponding to SAC picks headers (A, F, and T0 to T9) are transferred, but other picks are not.

If t is in a Cartesian reference frame (i.e., its positions are given by CartEvent and CartStation), then the Cartesian station coordinates x, y and z are saved respectively to headers USER0, USER1 and USER2. Likewise, the event coordinates are saved respectively to USER3, USER4 and USER5. Any information in meta fields SAC_user0 to SAC_user5 will overwrite this data.

Note

The convention on how non-geographic coordinates are written in SAC headers is not part of the API and may change at any time. Saving non-standard information in SAC headers should be done explicitly by the user if this information is important.

By default, files are written to disk in bigendian format (MacSAC or SAC/BRIS convention). Use littleendian=true to write in littleendian byte order (SAC/IRIS or SAC2000 convention).

Example data sets

Seis.sample_data — Function

sample_data() -> ::Trace
sample_data(kind::Symbol) -> ::Array{Trace}

Return some sample data.

With no arguments, sample gives one trace from a local earthquake recorded in California.

In the second form, a set of traces is returned according to the table below:

`kind`	Description
`:local`	Livermore Valley, CA. 9 3-component stations
`:regional`	Nevada. 4 3-component stations
`:teleseism`	Mid-period recording of Eureka, CA event. 4 3-c stations
`:teleseisl`	Long-period recording of Eureka, CA event. 4 3-c stations
`:array`	Deep Fiji event. 60 vertical stations in the UK