API Reference

absdiff(a, b)

Return the absolute difference |a - b|. Uses branch-free subtraction for unsigned integers to avoid overflow.

allsame(a::AbstractArray)
allsame(first, second, others...)
allsame(f::Function, first, second, others...)

Return true if all arguments (or elements of a) are equal. The f form compares f(x) values.

anyeq(el, iter)

Return true if any element of iter equals el.

bin_bounds(binno, binsize)
bin_bounds(binno, binsize, max_ndx)

Return the (start_idx, stop_idx) 1-based index bounds for bin number binno with binsize elements per bin. The three-argument form clamps the result to max_ndx.

See also bin_center.

bin_center(idxs::NTuple{2})
bin_center(binno, binsize, ...)

Return the center index of a bin, either from a (start, stop) tuple or by computing bin_bounds first.

See also bin_bounds.

centered_basis(n_point)

Return a range of n_point values centered around zero (e.g., [-1.0, 0.0, 1.0] for n_point=3).

clip_ndx(ndx, l)

Clamp index ndx to the valid range 1:l for an array of length l.

See also clip_ndx_deviance.

clip_ndx_deviance(ndx, l)

Like clip_ndx, but also returns the deviance (clipped - original) as a second value.

clipsize!(a::AbstractVector, n)

Resize vector a to length n and release excess memory via sizehint!.

copy_length_check(n_dest, n_source, d_off=1, s_off=1, n=n_ndx(s_off, n_source))
copy_length_check(dest::AbstractArray, source::AbstractArray, ...)
copy_length_check(dest::AbstractArray, d_off, source::AbstractArray, s_off, ...)

Return true if dest has enough room to accept n elements copied from source at the given offsets. The three-argument array form interleaves each offset with its array: (dest, d_off, source, s_off, ...).

copy_length_dest_check(n_dest, d_off, n)

Return true if a destination of length n_dest can accept n elements starting at offset d_off.

div_type(::Type{N})
div_type(::Type{N}, ::Type{D})
div_type(num, den)

Return the result type of dividing values of the given numeric or array type(s). Float types are preserved; integer types promote to Float64.

duration(npoints, fs)

Return the duration of a regularly sampled time series with npoints samples at sample rate fs. Assumes 1-based indexing, so duration is (npoints - 1) / fs.

expand_selection(ib, ie, imax, expansion)

Expand the index range [ib, ie] by expansion in both directions, clamping to [1, imax]. Returns a tuple (ib_expanded, ie_expanded).

filter_no_collisions(as, bs, coll_rad)

Filter elements of as to keep elements that are not within coll_rad of any element in bs. Assumes both are sorted.

filtermap(p::Function, f::Function, xs)

Filters the input vector, then maps the remaining values. For each element of xs which predicate function p returns true for, use mapping function f to transform the result.

find_all_edge_triggers(arr, thr, comp = >=)

Return all indices where arr triggers an edge crossing of threshold thr. An edge occurs at index i when comp(arr[i], thr) is true and comp(arr[i-1], thr) is false.

See also find_first_edge_trigger.

find_closest(a, target, ...)

Find the index of the element in a that minimizes the absolute difference from the target.

find_first_edge_trigger(arr, thr, comp = >=)

Return the index of the first edge trigger in arr crossing thr, or nothing if none is found.

See also find_all_edge_triggers.

find_local_extrema(sig, start_ndx=div(length(sig), 2); findmax=true, right_on_ties=true)

Starting from start_ndx, hill-climb through sig to find a local maximum (or minimum if findmax=false). When tied, moves right if right_on_ties=true. Skips missing and NaN values. Returns the index of the found extremum.

find_not_unique(a::AbstractArray)

Returns the indices of all redundant elements in a. The time a value is seen, it is not considered redundant

find_subseq(subseq, seq)

Return a vector of starting indices where subseq occurs in seq. Uses isequal for element comparison.

imap_product(f, as, bs)

Return a lazy iterator that applies f(a, b) to every element of the Cartesian product of as and bs.

indices_above_thresh(arr, thr)

Return a vector of UnitRange{Int} spans where arr[i] >= thr. Consecutive above-threshold indices are merged into a single range.

invert_perm(p)

Return the inverse of permutation vector p, such that invert_perm(p)[p[i]] == i.

local_extrema(s, comp = >)

Return indices of local extrema in vector s. An index i is a local extremum when comp(s[i], s[i+1]) is true and comp(s[i-1], s[i]) is false (i.e., a direction change). Use > for maxima (default), < for minima.

Note: plateau-to-descent transitions are reported as extrema. For example, local_extrema([1, 2, 2, 1]) returns [3] because 2 > 1 but !(2 > 2).

make_expand_idx(ndims, dimno)

Construct an index tuple that selects : along dimension dimno and 1 along all other dimensions. Useful for broadcasting a vector along one dimension of an N-dimensional array.

make_slice_idx(ndims, dimno, idx)

Construct a tuple of indices that selects idx along dimension dimno and : along all other dimensions. Useful for programmatic slicing of N-dimensional arrays.

map_pairwise(f, a, R=eltype(a))
map_pairwise(f, as, bs, R=eltype(as))

Apply f to all unique pairs from vector a (single-argument form) or to the Cartesian product of as and bs (two-argument form). The single-argument form returns a vector ordered consistently with pairwise_idxs; the two-argument form returns a matrix.

See also pairwise_idxs, pairwise_idx.

moving_sum!(out, s, nav)

Sum s in a sliding window of nav points, placing the result into out. The length of out should be max(length(s) - nav + 1, 0) if nav > 0, or length(s) otherwise. When nav is 0 or 1 the result is a copy of s.

Does not zero-pad.

moving_sum(s, nav)

Same as moving_sum!, but returns a new array. When nav is 0 or 1 the result is a copy of s.

n_ndx(start_idx::T, stop_idx::T) where {T<:Integer}

Find the number of indices between start_idx and stop_idx.

ndx_offset(start_ndx, npt)

Finds the index that will select npt number of elements starting at start_ndx.

If npt is negative, then start_ndx is treated like the end of a range of elements, and the index required to return npt number of elements is returned.

ndx_to_t(i, fs, start_t=0)

Convert a 1-based index (or array of indices) to its time in a regularly sampled time series with sample rate fs and optional start_t.

See also t_to_ndx, t_to_last_ndx, t_sup_to_ndx.

ndx_wrap(i, max_ndx)

Wrap a 1-based index i into the range 1:max_ndx using modular arithmetic.

Examples

julia> SignalIndices.ndx_wrap(5, 3)
2

julia> SignalIndices.ndx_wrap(3, 3)
3

pairwise_idx(i, j, n)

Return the linear index into the output of pairwise_idxs for the pair (i, j) where n is the number of input elements. Throws ArgumentError if i == j.

See also pairwise_idxs, map_pairwise.

pairwise_idxs(n::Integer) -> Vector{NTuple{2, Int}}

Returns the possible combinations of 1:n indices excluding self-pairs. The first index is always greater than the second, allowing for easy subtraction of ordered lists.

Examples

julia> pairwise_idxs(3)
3-element Vector{Tuple{Int64,Int64}}:
 (2, 1)
 (3, 1)
 (3, 2)

rev_view(a::AbstractVector)

Return a reversed view of vector a without copying.

simple_summary_stats(a)

Return (mean, std, sem) for array a, where sem is the standard error of the mean.

skipnothing(itr)

Return an iterator that skips nothing values in itr. Equivalent to skipoftype(Nothing, itr).

See also skipoftype.

skipoftype(::Type{T}, itr)

Return an iterator over the elements in itr skipping values of type T. Use collect to obtain an Array containing the non-T values in itr. Note that even if itr is a multidimensional array, the result will always be a Vector since it is not possible to remove nothings while preserving dimensions of the input.

Examples

julia> sum(SignalIndices.skipoftype(nothing, [1, nothing, 2]))
3
julia> collect(SignalIndices.skipoftype(nothing, [1, nothing, 2]))
2-element Vector{Int64}:
 1
 2
julia> collect(SignalIndices.skipoftype(nothing, [1 nothing; 2 nothing]))
2-element Vector{Int64}:
 1
 2

stepsize(r)

Return the step size of a range or regularly sampled vector. For a UnitRange, returns 1. For a generic vector, returns a[2] - a[1] (assumes regular spacing).

subselect(base_vec, idx_tup_vec, outtype=...)

Extract sub-vectors from base_vec using a vector of (start, stop) index tuples. Returns a Vector{outtype} where each element is the slice base_vec[start:stop].

t_sup_to_ndx(x, fs, start_t=0, T=Int)

Convert a time to the index of the last sample strictly before the specified time in a regularly sampled time series. Equivalent to t_to_ndx(...) - 1.

See also t_to_ndx, t_to_last_ndx, ndx_to_t.

t_to_last_ndx(x, fs, start_t=0, T=Int)

Like t_to_ndx, but returns the index of the last sample at or before the specified time.

See also ndx_to_t, t_sup_to_ndx.

t_to_ndx(x, fs, start_t=0, T=Int)

Convert a time to its 1-based index in a regularly sampled time series. Returns the index of the first sample at or after the specified time.

See also ndx_to_t, t_to_last_ndx, t_sup_to_ndx.

thresh_cross(arr, thresh, comp = <)

Return indices where arr crosses upward through thresh according to comp. An index i+1 is returned when comp(arr[i], thresh) is true and comp(arr[i+1], thresh) is false (i.e., the signal leaves the comp region).

time_interval(npoints, fs, start_t=0)
time_interval(a::AbstractVector, fs, start_t=0)

Return the (start_t, end_t) time interval of a regularly sampled time series with npoints samples (or a vector a) at sample rate fs.

trailing_zeros_idx(arr)

return last index that is not zero

uniformhist!(cnts, xs, r)

Compute a histogram of xs into pre-allocated count vector cnts, using the bin edges defined by range r. Bins are left-inclusive: a value x falls into bin i when r[i] <= x < r[i+1].

r must have uniform step size (e.g. a StepRangeLen or UnitRange) and at least 2 elements. The length of cnts must equal length(r) - 1. Values outside the range are silently ignored.

cnts is not zeroed before accumulation, so it must be initialized (e.g. with zeros). This also means uniformhist! can be called repeatedly to accumulate counts from multiple datasets.

Uses multiplication by the reciprocal of the step size instead of division for a ~20x speedup over naive binning.

See also uniformhist.

Examples

julia> cnts = zeros(Int, 3);

julia> uniformhist!(cnts, [0.1, 0.5, 1.2, 2.9], 0.0:1.0:3.0)
3-element Vector{Int64}:
 2
 1
 1

uniformhist([::Type{T} = Int,] xs, r) where T

Compute a histogram of xs using the bin edges defined by range r, returning a new vector of counts with element type T (default Int). Bins are left-inclusive: a value x falls into bin i when r[i] <= x < r[i+1].

r must have uniform step size (e.g. a StepRangeLen or UnitRange). The returned vector has length length(r) - 1. Values outside the range are silently ignored.

See also uniformhist!.

Examples

julia> uniformhist([0.1, 0.5, 1.2, 2.9], 0.0:1.0:3.0)
3-element Vector{Int64}:
 2
 1
 1

julia> uniformhist(Float64, [1, 1, 2, 3, 3, 3], 1:4)
3-element Vector{Float64}:
 2.0
 1.0
 3.0

view_trailing_slice(a::AbstractArray{<:Any,N}, idx)

Return a view of a sliced along its last dimension at idx, with all leading dimensions selected via :. For a 3D array, this is equivalent to view(a, :, :, idx).

weighted_mean(summand, weights, total_weight=sum(weights))

Compute the weighted mean of summand using element-wise weights. Both arrays must have the same size. Returns a scalar.

See also weighted_mean_dim.

weighted_mean_dim(summand, weights, dim=N, total_weight=sum(weights))

Compute the weighted mean of summand along dimension dim using weights (a vector whose length matches size(summand, dim)). Returns an array with dimension dim reduced to size 1.

See also weighted_mean.

window_counts in a certain range`

window_counts(ts, window_dur)

For each event in ts, count the number of events in ts that are in the range of ts[i] and ts[i] + window_dur. Assumes ts is sorted, and that elements of ts are unique.