ordered-regular: Working with Ordered and Regularly Spaced Time Indices

Description

is.ordered_t method checks if time indices form a strictly increasing sequence without NA values.

is.regular method checks if time indices form a strictly increasing, regularly spaced sequence without NA values.

as.regular returns regularly spaced sequence of time indices based on strictly increasing time indices provided.

extend_regular extends strictly increasing sequence of time indices by n points after the last taking into account the resolution of the sequence provided.

Usage

is.ordered_t(x)
# S3 method for tind
is.ordered_t(x)
is.regular(x)
# S3 method for tind
is.regular(x)
as.regular(x, ...)
# S3 method for tind
as.regular(x, ...)
extend_regular(x, n)

Value

A logical value for is.ordered_t and is.regular. An object of tind class for as.regular and extend_regular.

Arguments

x: an object of tind class or of other time index class supported by tind package.
...: further arguments passed to or from other methods.
n: an integer value, number of time stamps to be added, see Details.

Details

n argument of extend_regular can be negative. In that case -n points are added before the first index. The function may fail in corner cases (if the result would be out of range).

Creating regular date-time sequences in front of DST/UTC offset changes can be impossible. If the algorithm fails, an error is issued. In general, this should not be a problem when DST change is by 1 hour and the resolution of the indices is 1 hour or higher.

Examples

Run this code

# months, resulution 2m
(ms <- tind(y = 2023, m = 1 + 2 * (0:5)))
is.regular(ms)
extend_regular(ms, 3)
(ms <- tind(y = 2023, m = c(1, 3, 5, 9)))
is.regular(ms)
as.regular(ms)
# date, resulution 15d
(ds <- tind(y = 2024, m = rep(1:3, each = 2), d = c(1, 16)))
is.regular(ds)
extend_regular(ds, -4)
(ds <- ds[-2L])
is.regular(ds)
as.regular(ds)

# corner cases
tz <- "Europe/Warsaw"
if (tz %in% OlsonNames()) {
    # switch to DST
    print(hours_in_day("2025-03-30", tz = tz))
    # this will work with step from 1am to 3am
    tt <- date_time("2025-03-30", H = c(0, 4:8), tz = tz)
    print(resolution_t(tt))
    as.regular(tt)
}
if (tz %in% OlsonNames()) {
    # this will fail due to missing 2am
    tt <- date_time("2025-03-30", H = c(0, 4, 6, 8), tz = tz)
    print(resolution_t(tt))
    try(as.regular(tt))
}
if (tz %in% OlsonNames()) {
    # this will work again (step by 4h)
    tt <- date_time("2025-03-30", H = c(0, 4, 12), tz = tz)
    print(resolution_t(tt))
    as.regular(tt)
}