TimeseriesBase

Welcome to the documentation for TimeseriesBase, a Julia package for working with time series data.

The TimeseriesBase package provides a standardized collection of types designed for handling various types of time-series data. Defining consistent types for time series provides three key benefits:

  1. It simplifies the workspace and method signatures by aggregating much of the data that defines a time series into a single variable; thanks to the DimensionalData.jl package, one variable can hold the values of a time series, its time points, spatial coordinates, units, metadata, and more.
  2. It facilitates generic functions that dispatch on the various types of time series; for instance, more efficient algorithms can be written for RegularTimeseries types than for IrregularTimeseries types, but the same high-level functionality can be provided by the same generic function that dispatches these methods given the type of the input time series.
  3. Most importantly, this intuitively aligns the structure of time-series data in code to mathematical conventions, which can vastly simplify the process of developing and interpreting programs. Many small complexities (Was this time series regularly sampled? What are the output frequencies of my Fourier transform? The units of my power spectrum?) are handled effortlessly, leaving room to focus on higher-level problems.

To achieve this, TimeseriesBase.jl defines a custom version of the DimensionalData.DimArray and custom DimensionalData.Dimensions:

x = Timeseries(1:10, rand(10))
x isa AbstractToolsArray # In most cases, an AbstractToolsArray behaves like a DimArray; see DimensionalData
x isa AbstractTimeseries # An AbstractTimeseries is an AbstractToolsArray...
lookup(x, 1) isa 𝑡 # ...where the first dimension is a custom TimeDim 𝑡

If a ToolsArray or DimArray has a 𝑡 as its first dimension, it will be rebuilt as a ToolsArray (i.e. when using functions like eachcol). There are a small number of other custom dimensions, all exported, that share this property and are subtypes of ToolsDimension: e.g. 𝑥, 𝑦, 𝑧, 𝑓,Var, Obs. To define more of these ToolsDimensions, use:

DimensionalData.@dim NewDim ToolsDim "NameOfNewDim"

Please note that functions operating on a ToolsArray without a ToolsDimension as the first or last dimension may NOT return a ToolsArray, especially if they perform slicing and rebuilding. Be careful using the DimensionalData.Dim{:name} syntax.

TimeseriesBase.ToolsArrays.ToolsArray — Method
ToolsArray(f::Function, dim::Dimension; [name])

Apply function f across the values of the dimension dim (using broadcast), and return the result as a dimensional array with the given dimension. Optionally provide a name for the result.

source
TimeseriesBase.ToolsArrays.ToolsDim — Type
ToolsDim{T}

An abstract type for custom macro-defined dimensions in TimeseriesBase. Analogous to DimensionalData.Dimension for the purposes of DimensionalData.@dim.

Examples

DimensionalData.@dim MyDim ToolsDim "My dimension" # Defines a new `ToolsDim <: ToolsDimension`

See also

source
TimeseriesBase.TimeSeries.SpikeTrain — Type
SpikeTrain

A type alias for a spike-train time series, which contains spike times in the time dimension and true for all values corresponding to a spike. The spike times can be retrieved with times(x).

source
TimeseriesBase.TimeSeries.Timeseries — Method
Timeseries(x, t, v)

Constructs a multivariate time series with time t, variable v, and data x.

Examples

julia> t = 1:100;
julia> v = [:a, :b, :c];
julia> x = rand(100, 3);
julia> mts = Timeseries(x, t, v)
julia> mts isa typeintersect(MultivariateTimeseries, RegularTimeseries)
source
TimeseriesBase.TimeSeries.Timeseries — Method
Timeseries(x, t)

Constructs a univariate time series with time t and data x.

Examples

julia> using TimeseriesBase, Unitful;
julia> t = 1:100
julia> x = rand(100)
julia> ts = Timeseries(x, t)
julia> ts isa typeintersect(UnivariateTimeseries, RegularTimeseries)
source
IntervalSets.Interval — Method
IntervalSets.Interval(x::AbstractTimeseries)

Returns an interval representing the range of the AbstractTimeseries x.

Examples

julia> using IntervalSets;
julia> t = 1:100;
julia> x = rand(100);
julia> ts = Timeseries(x, t);
julia> IntervalSets.Interval(ts) == (1..100)
source
Base.step — Method
step(x::RegularTimeseries)

Returns the step size (time increment) of a regularly sampled RegularTimeseries.

Examples

julia> t = 1:100;
julia> x = rand(100);
julia> rts = Timeseries(x, t);
julia> step(rts) == 1
source
TimeseriesBase.Utils.align — Method
align(x::AbstractDimArray, ts, dt; dims = 1)

Align a DimArray x to each of a set of dimension values ts, selecting a window given by dt centered at each element of ts. dt can be a two-element vector/tuple, or an interval. The dims argument specifies the dimension along which the alignment is performed. Each element of the resulting DimArray is an aligned portion of the original x.

source
TimeseriesBase.Utils.buffer — Method
buffer(x::RegularTimeseries, n::Integer, p::Integer; kwargs...)

Buffer a time series x with a given window length and overlap between successive buffers.

Arguments

  • x: The regular time series to be buffered.
  • n: The number of samples in each buffer.
  • p: The number of samples of overlap betweeen the buffers.
    • 0 indicates no overlap
    • +2 indicates 2 samples of overlap between successive buffers
    • -2 indicates 2 samples of gap between buffers

See also: window, delayembed, coarsegrain

source
TimeseriesBase.Utils.centraldiff! — Method
centraldiff!(x::RegularTimeseries; dims=𝑡, grad=-)

Compute the central difference of a regular time series x, in-place. The first and last elements are set to the forward and backward difference, respectively. The dimension to perform differencing over can be specified as dims, and the differencing function can be specified as grad (defaulting to the euclidean distance, -)

source
TimeseriesBase.Utils.centraldiff — Method
centraldiff(x::RegularTimeseries; dims=𝑡, grad=-)

Compute the central difference of a regular time series x. The first and last elements are set to the forward and backward difference, respectively. The dimension to perform differencing over can be specified as dims, and the differencing function can be specified as grad (defaulting to the euclidean distance, -) See centraldiff!.

source
TimeseriesBase.Utils.coarsegrain — Method
coarsegrain(X::AbstractArray; dims = nothing, newdim=ndims(X)+1)

Coarse-grain an array by taking every second element over the given dimensions dims and concatenating them in the dimension newdim. dims are coarse-grained in sequence, from last to first. If dims is not specified, we iterate over all dimensions that are not newdim. If the array has an odd number of slices in any dims, the last slice is discarded. This is more flexibile than the conventional, mean-based definition of coarse graining: it can be used to generate coarse-grained distributions from an array. To recover this conventional mean-based coarse-graining:

    C = coarsegrain(X)
    mean(C, dims=ndims(C))
source
TimeseriesBase.Utils.delayembed — Function
delayembed(x::UnivariateRegular, n::Integer, τ::Integer, p::Integer=1; kwargs...)

Delay embed a univariate time series x with a given dimension n, delay τ, and skip length of p

Arguments

  • x: The regular time series to be delay embedded.
  • n: The embedding dimension, i.e., the number of samples in each embedded vector.
  • τ: The number of original sampling periods between each sample in the embedded vectors.
  • p: The number of samples to skip between each successive embedded vector.

See also: buffer, window

source
TimeseriesBase.Utils.rectifytime — Method
rectifytime(X::AbstractTimeseries; tol = 6, zero = false)

Rectifies the time values of an IrregularTimeseries. Checks if the time step of the input time series is approximately constant. If it is, the function rounds the time step and constructs a RegularTimeseries with range time indices. If the time step is not approximately constant, a warning is issued and the rectification is skipped.

Arguments

  • X::IrregularTimeseries: The input time series.
  • tol::Int: The number of significant figures for rounding the time step. Default is 6.
  • zero::Bool: If true, the rectified time values will start from zero. Default is false.
source
TimeseriesBase.Utils.samplingrate — Method
samplingrate(x::RegularTimeseries)

Returns the sampling rate (inverse of the step size) of a regularly sampled RegularTimeseries.

Examples

julia> t = 1:100;
julia> x = rand(100);
julia> rts = Timeseries(x, t);
julia> samplingrate(rts) == 1
source
TimeseriesBase.Utils.stitch — Method
stitch(x, args...)

Stitch multiple time series together by concatenating along the time dimension generating new contiguous time indices. The time series must be of the same type (UnivariateRegular, MultivariateRegular, or AbstractArray), and the sampling period and dimensions of the data arrays must match. If the arguments are `MultivariateRegular, they must have the same dimensions (except for the time dimension).

Arguments

  • X: The first time series.
  • args...: Additional time series.

Returns

  • A new time series containing the concatenated data.
source
TimeseriesBase.Utils.window — Function
window(x::RegularTimeseries, n::Integer, p::Integer; kwargs...)

Window a time series x with a given window length and step between successive windows.

Arguments

  • x: The regular time series to be windows.
  • n: The number of samples in each window.
  • p: The number of samples to slide each successive window.

See also: buffer, delayembed, coarsegrain

source