Utilities

Helpers for sampling metadata, windowing, embedding, regularisation, derivatives, and circular statistics. All operate on the core types from Time series.

Sampling metadata

TimeseriesBase.Utils.times Function

times(x::AbstractTimeseries)

Returns the time indices of the AbstractTimeseries x.

Examples

julia> t = 1:100;
julia> x = rand(100);
julia> ts = Timeseries(x, t);
julia> times(ts) == t

source

Base.step Function

step(x::RegularTimeseries; dims=𝑡)

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.samplingrate Function

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.samplingperiod Function

samplingperiod(x::RegularTimeseries)

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

Examples

julia> t = 1:100;
julia> x = rand(100);
julia> rts = Timeseries(x, t);
julia> samplingperiod(rts) == 1

source

TimeseriesBase.Utils.duration Function

duration(x::AbstractTimeseries)

Returns the duration of the AbstractTimeseries x.

Examples

julia> t = 1:100;
julia> x = rand(100);
julia> ts = Timeseries(x, t);
julia> TimeseriesBase.duration(ts) == 99

source

Windowing and reshaping

coarsegrain downsamples by averaging within blocks; buffer returns non-overlapping windows as columns; window returns sliding windows; delayembed builds a delay-coordinate embedding.

using TimeseriesTools
x = Timeseries(sin.(0.0:0.01:9.99), 0.0:0.01:9.99)
b = buffer(x, 100)               # 100-sample non-overlapping windows
size(b)

(10,)

TimeseriesBase.Utils.coarsegrain Function

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.buffer Function

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

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.interlace Function

interlace(x::UnivariateTimeseries, y::UnivariateTimeseries)

Interleave two univariate time series into a single series whose time index is the sorted union of times(x) and times(y), with the values reordered to match.

source

TimeseriesBase.Utils.Dropdims Type

Dropdims(f)

Wrap a reducing function f so that the reduced dimensions are dropped from the result: Dropdims(f)(args...; dims, kwargs...) is dropdims(f(args...; dims, kwargs...); dims).

Examples

julia> Dropdims(sum)(x; dims = 1)   # sum over dimension 1 and drop it

source

Regularising time axes

rectify and regularize repair float jitter in nominally regular lookups; matchdim and align bring multiple series onto a common axis.

TimeseriesBase.Utils.rectify Function

rectify(ts::Dimension; tol=4, zero=false)
rectify(X::AbstractDimArray; dims, tol=4, zero=false)
rectify(X1, X2, ...; dims=𝑡, tol=4, zero=false)

Replace a near-regular lookup with a regular range, rounding the step to tol significant figures. The array forms operate along dims; the vararg form additionally aligns several arrays onto a shared grid. With zero=true the lookup starts at zero and the original is stored in metadata.

Note

Superseded by regularize, which fits the grid by least squares, checks regularity by maximum deviation, and throws (rather than warns) on failure by default. Prefer regularize for new code.

source

TimeseriesBase.Utils.rectifytime Function

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.regularize Function

regularize(d::DimensionalData.Dimension; atol=nothing, sigdigits=nothing,
           strict=true)

Return (new_lookup, original_lookup) where new_lookup is a regular range that best fits the values of d and original_lookup is the input lookup collected to a vector.

Use this method when you want to inspect the rectified grid yourself; most callers should use regularize on an AbstractDimArray instead.

Keyword arguments

• atol: maximum allowed absolute deviation of any lookup point from the best-fit regular grid. Carries units if the lookup does. If nothing, a permissive ~1e3 * eps floor is used.

• sigdigits: override the number of digits used to round the step and start. Defaults to a value derived from atol so rounding error stays within tolerance.

• strict=true: throw if regularity fails. Set false to warn and return the best-fit grid anyway.

source

regularize(X::AbstractDimArray; dims=𝑡, atol=nothing, sigdigits=nothing,
           zero=false, strict=true)

Replace the lookup of X along each of dims with a regular range that best fits the existing values, repairing accumulated float jitter. If a lookup deviates from regular by more than atol an ArgumentError is thrown (strict=false downgrades this to a warning).

If zero=true, the new lookup starts at zero and the genuine original lookup is stored in metadata(X) under the dimension name.

This replaces the older rectify and rectifytime methods.

source

regularize(Xs::AbstractVector{<:AbstractDimArray}; dims=𝑡, atol=nothing,
           sigdigits=nothing, zero=false, strict=true)
regularize(X1, X2, ...; dims=𝑡, kwargs...)

Align a collection of arrays to a common regular grid along each of dims.

The shared grid is computed from the element-wise mean of the lookups after each array has been cropped to the maximal common range and trimmed to the minimum common length. The same regularity check that the single-array method uses then applies to every input array — if any one of them deviates from the common grid by more than atol, an ArgumentError is thrown (or a warning, under strict=false) naming the offending array and index.

This replaces the older matchdim and the vararg form of rectify.

source

TimeseriesBase.Utils.matchdim Function

matchdim(X::AbstractVector{<:AbstractDimArray}; dims=1, tol=4, zero=false)

Align a collection of dimensional arrays onto a common rectified grid along dims, so that every element of X shares an identical lookup.

Note

Superseded by regularize, which fits the grid by least squares and applies a stricter regularity check; prefer regularize for new code.

source

TimeseriesBase.Utils.align Function

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

Derivatives

Three finite-difference flavours: left, right, and centred. In-place (!) and allocating forms.

TimeseriesBase.Utils.centraldiff Function

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.centraldiff! Function

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.centralderiv Function

centralderiv(x::AbstractTimeseries)

Compute the central derivative of a time series x. See centraldiff for available keyword arguments. Also c.f. centralderiv!.

source

TimeseriesBase.Utils.centralderiv! Function

centralderiv!(x::RegularTimeseries; kwargs...)

Compute the central derivative of a regular time series x, in-place. See centraldiff! for available keyword arguments.

source

Missing docstring.

Missing docstring for leftdiff. Check Documenter's build log for details.

Missing docstring.

Missing docstring for leftdiff!. Check Documenter's build log for details.

Missing docstring.

Missing docstring for leftderiv. Check Documenter's build log for details.

Missing docstring.

Missing docstring for leftderiv!. Check Documenter's build log for details.

Missing docstring.

Missing docstring for rightdiff. Check Documenter's build log for details.

Missing docstring.

Missing docstring for rightdiff!. Check Documenter's build log for details.

Missing docstring.

Missing docstring for rightderiv. Check Documenter's build log for details.

Missing docstring.

Missing docstring for rightderiv!. Check Documenter's build log for details.

Circular statistics

For phase series and other angular data.

TimeseriesBase.Utils.resultant Function

resultant(θ; dims...)

The mean resultant vector of a sample of angles θ (in radians), mean(exp.(im .* θ)). Its length and argument summarise the concentration and mean direction of a circular distribution. dims is passed through to mean.

See also resultantlength, circularmean.

source

TimeseriesBase.Utils.resultantlength Function

resultantlength(θ; dims...)

The length of the mean resultant vector of angles θ, in [0, 1]: near 0 for uniformly spread angles, near 1 for tightly concentrated angles.

source

TimeseriesBase.Utils.circularmean Function

circularmean(θ; dims...)

The circular mean of angles θ (radians): the argument of the mean resultant vector, in (-π, π].

source

TimeseriesBase.Utils.circularvar Function

circularvar(θ; dims...)

The circular variance of angles θ, 1 - resultantlength(θ), in [0, 1].

source

TimeseriesBase.Utils.circularstd Function

circularstd(θ; dims...)

The circular standard deviation of angles θ, sqrt(-2 log(resultantlength(θ))).

source

TimeseriesBase.Utils.phasegrad Function

phasegrad(x, y)

The signed circular difference between angles x and y (in radians), wrapped to (-π, π]: the shortest signed rotation from y to x. For example phasegrad(0.1, 2π - 0.1) ≈ 0.2, not ≈ -2π. Broadcasts over arrays, and uses angle for Complex inputs.

source

Metadata helpers

TimeseriesBase.Utils.addrefdim Function

addrefdim(X::AbstractDimArray, dim::DimensionalData.Dimension)

Return X with dim appended to its reference dimensions (refdims).

source

TimeseriesBase.Utils.addmetadata Function

addmetadata(X::AbstractDimArray; kwargs...)

Return X with the keyword arguments merged into its metadata. Existing entries are kept; any key that collides with a keyword argument is overwritten (with a warning).

source

Spike-train helpers

Missing docstring.

Missing docstring for spiketrain. Check Documenter's build log for details.

Missing docstring.

Missing docstring for spiketimes. Check Documenter's build log for details.