API documentation

AlignedSpan(sample_rate::Number, first_index::Int, last_index::Int)

Construct an AlignedSpan directly from a sample_rate and indices.

SpanRoundingMode(start::RoundingMode, stop::RoundingMode)

Creates a rounding object for AlignedSpan to indicate how the AlignedSpan's endpoints should be determined from a given spans endpoints'.

RoundInward = SpanRoundingMode(RoundUp, RoundDown)

This is a rounding mode where both ends of the continuous time interval are rounded "inwards" to construct the largest span of indices such that all samples, as instants of time, occur within the span.

Example

Consider a signal with sample rate 1 Hz.

Index       1   2   3   4   5
Time (s)    0   1   2   3   4

Now, consider the time span 1.5s (inclusive) to 2.5s (exclusive). Using brackets to highlight this span:

Index       1   2     3     4   5
Time (s)    0   1  [  2  )  3   4

In code, this span is described by

julia> using AlignedSpans, Dates, TimeSpans

julia> ts = TimeSpan(Millisecond(1500), Millisecond(2500))
TimeSpan(00:00:01.500000000, 00:00:02.500000000)

The only sample within the span is at index 3. And indeed,

julia> aligned = AlignedSpan(1, ts, RoundInward)
AlignedSpan(1.0, 3, 3)

julia> AlignedSpans.indices(aligned)
3:3

gives an AlignedSpan with indices 3:3.

RoundSpanDown = SpanRoundingMode(RoundDown, RoundDown)

This is a rounding mode where both ends of the continuous time interval are rounded downwards.

Example

Consider a signal with sample rate 1 Hz.

Index       1   2   3   4   5
Time (s)    0   1   2   3   4

Now, consider the time span 1.5s (inclusive) to 2.5s (exclusive). Using brackets to highlight this span:

Index       1   2     3     4   5
Time (s)    0   1  [  2  )  3   4

In code, this span is described by

julia> using AlignedSpans, Dates, TimeSpans

julia> ts = TimeSpan(Millisecond(1500), Millisecond(2500))
TimeSpan(00:00:01.500000000, 00:00:02.500000000)

If we round both ends of the interval down to the nearest sample, the start of the interval becomes 1s, and the stop of the interval becomes 2s. Thus, the associated samples are at indices 2:3. And indeed,

julia> aligned = AlignedSpan(1, ts, RoundSpanDown)
AlignedSpan(1.0, 2, 3)

julia> AlignedSpans.indices(aligned)
2:3

gives an AlignedSpan with indices 2:3.

RoundFullyContainedSampleSpans

This is a special rounding mode which differs from the other rounding modes by associating each sample with a span (from the instant the sample occurs until just before the next sample occurs), and rounding inwards to the "sample spans" that are fully contained in the input span.

This is in some sense a stricter form of inward rounding than provided by RoundInward.

Example

Consider a signal with sample rate 1 Hz.

Index       1   2   3   4   5
Time (s)    0   1   2   3   4

Normally, we consider each sample to occur at an instant of time. For RoundFullyContainedSampleSpans, we consider the span between a sample occurring and the next sample. (This usually does not make sense for digital sensors, but can make sense for things like hypnograms in which a sample summarizes some region of time).

Thus, to each index (each sample), we associate a 1s closed-open span of time:

Index        1     2     3     4     5
Span (s)    [0   )[1   )[2   )[3   )[4    )

The span durations are 1/sample_rate, which is 1s in this example.

Now, consider the input time span 1.5s (inclusive) to 3.5s (exclusive). Using brackets to highlight this span:

Index        1     2     3     4     5
Span (s)    [0   )[1   )[2   )[3   )[4    )
Time (s)     0     1  [  2     3  )  4

This input span contains only one sample-span, namely [2s, 3s). The span from [1s, 2) is not fully contained, nor is the span from [3s, 4s).

Thus, in this scenario, RoundFullyContainedSampleSpans would give a single sample, that at index 3, associated to [2s, 3s).

In code, this span is described by

julia> using AlignedSpans, Dates, TimeSpans

julia> ts = TimeSpan(Millisecond(1500), Millisecond(3500))
TimeSpan(00:00:01.500000000, 00:00:03.500000000)

julia> aligned = AlignedSpan(1, ts, RoundFullyContainedSampleSpans)
AlignedSpan(1.0, 3, 3)

julia> AlignedSpans.indices(aligned)
3:3

AlignedSpan(sample_rate, span, mode::SpanRoundingMode)

Creates an AlignedSpan by rounding the left endpoint according to mode.start, and the right endpoint by mode.stop.

If mode.start==RoundUp, then the left index of the resulting span is guaranteed to be inside span. This is accomplished by checking if the left endpoint of the span is exclusive, and if so, incrementing the index after rounding when necessary.

Likewise, if mode.stop==RoundDown, then the right index of the resulting span is guaranteed to be inside span. This is accomplished by checking if the right endpoint of the span is exclusive, and if so, decrementing the index after rounding when necessary.

Note: span may be of any type which which provides methods for AlignedSpans.start_index_from_time and AlignedSpans.stop_index_from_time.

julia> using TimeSpans, AlignedSpans, Dates

julia> sample_rate = 1/30
0.03333333333333333

julia> input = TimeSpan(0, Second(30) + Nanosecond(1))
TimeSpan(00:00:00.000000000, 00:00:30.000000001)

julia> aligned = AlignedSpan(sample_rate, input, RoundInward) # or RoundSpanDown
AlignedSpan(0.03333333333333333, 1, 2)

julia> TimeSpan(aligned)
TimeSpan(00:00:00.000000000, 00:01:00.000000000)

See also AlignedSpan(sample_rate, span, mode::RoundingModeFullyContainedSampleSpans).

ConstantSamplesRoundingMode(start::RoundingMode)

Creates a rounding object for AlignedSpan to indicate the AlignedSpan should be constructed by the start and duration of the span, without regard to its stop.

If two spans have the same duration, then the resulting AlignedSpan's will have the same number of samples when constructed with this rounding mode.

See also AlignedSpan(sample_rate, span, mode::ConstantSamplesRoundingMode).

AlignedSpan(sample_rate, span, mode::ConstantSamplesRoundingMode)

Creates an AlignedSpan whose left endpoint is rounded according to mode.start, and whose right endpoint is determined so by the left endpoint and the number of samples, given by AlignedSpans.n_samples(sample_rate, duration(span)).

Interface: span may be of any type which which provides a method for AlignedSpans.start_index_from_time and TimeSpans.duration.

More detailed information

This is designed so that if AlignedSpan(sample_rate, span, mode::ConstantSamplesRoundingMode) is applied to multiple spans, with the same sample_rate, and the same durations, then the resulting AlignedSpan's will have the same number of samples.

For this reason, we ask for TimeSpans.duration(span) to be defined, rather than a n_samples(span) function: the idea is that we want to only using the duration and the starting time, rather than the actual number of samples in this particular span.

In contrast, RoundInward provides an AlignedSpan which includes only (and exactly) the samples which occur within span (as instants in time), while AlignedSpan(sample_rate, span, ::RoundingModeFullyContainedSampleSpans) provides an AlignedSpan consisting of the full spans from each sample until the next sample occurs that are contained in the input span.

If one wants to create a collection of consecutive, non-overlapping, AlignedSpans each with the same number of samples, then use consecutive_subspans instead.

consecutive_subspans(span::AlignedSpan, duration::Period; keep_last=true)
consecutive_subspans(span::AlignedSpan, n_window_samples::Int; keep_last=true)

Creates an iterator of AlignedSpan such that each AlignedSpan has consecutive indices which cover the original span's indices (when keep_last=true).

If keep_last=true (the default behavior), then the last span may have fewer samples than the others, and

• Each span has n_window_samples samples (which is calculated as n_samples(span.sample_rate, duration) if duration::Period is supplied), except possibly

the last one, which may have fewer.

• The number of subspans is given by cld(n_samples(span), n_window_samples),
• The number of samples in the last subspan is r = rem(n_samples(span), n_window_samples) unless r=0, in which

case the the last subspan has the same number of samples as the rest, namely n_window_samples.

• All of the indices of span are guaranteed to be covered by exactly one subspan

If keep_last=false, then all spans will have the same number of samples:

• Each span has n_window_samples samples (which is calculated as n_samples(span.sample_rate, duration) if duration::Period is supplied)
• The number of subspans is given by fld(n_samples(span), n_window_samples)
• The last part of the span's indices may not be covered (when we can't fit in another subspan of length n_window_samples)

consecutive_overlapping_subspans(span::AlignedSpan, duration::Period,
                                 hop_duration::Period)
consecutive_overlapping_subspans(span::AlignedSpan, n_window_samples::Int, n_hop_samples::Int)

Create an iterator of AlignedSpan such that each AlignedSpan has n_window_samples (calculated as n_samples(span.sample_rate, duration) if duration::Period is supplied) samples, shifted by n_hop_samples (calculated as n_samples(span.sample_rate, hop_duration) if hop_duration::Period is supplied) samples between consecutive spans.

Note: If hop_duration cannot be represented as an integer number of samples, rounding will occur to ensure that all output AlignedSpans will have the same number of samples. When rounding occurs, the output hop_duration will be: Nanosecond(n_samples(samp_rate, hop_duration) / samp_rate * 1e9)

n_samples(sample_rate, duration::Union{Period, Dates.CompoundPeriod})

Returns the minimal number of samples that can occur in a span of duration.

n_samples(aligned::AlignedSpan)

Returns the number of samples present in the span aligned.

AlignedSpans.indices(span::AlignedSpan) -> UnitRange{Int64}

Returns the sample indices associated to an AlignedSpan.

AlignedSpans.start_index_from_time(sample_rate, span, rounding_mode)

Returns the index of a sample object obtained by rounding the start of span according to rounding_mode.

See also AlignedSpan(sample_rate, span, mode::SpanRoundingMode) and AlignedSpan(sample_rate, span, mode::ConstantSamplesRoundingMode).

AlignedSpans.stop_index_from_time(sample_rate, span, rounding_mode)

Returns the index of a sample object obtained by rounding the stop of span according to rounding_mode.

See also AlignedSpan(sample_rate, span, mode::SpanRoundingMode).