iv: Create an interval vector

In DavisVaughan/ivs: Interval Vectors

Create an interval vector

Description

• iv() creates an interval vector from start and end vectors. This is how you will typically create interval vectors, and is often used with columns in a data frame.

• iv_pairs() creates an interval vector from pairs. This is often useful for interactive testing, as it provides a more intuitive interface for creating small interval vectors. It should generally not be used on a large scale because it can be slow.

Intervals

Interval vectors are right-open, i.e. [start, end). This means that start < end is a requirement to generate an interval vector. In particular, empty intervals with start == end are not allowed.

Right-open intervals tend to be the most practically useful. For example, [2019-01-01 00:00:00, 2019-01-02 00:00:00) nicely encapsulates all times on 2019-01-01. With closed intervals, you'd have to attempt to specify this as 2019-01-01 23:59:59, which is inconvenient and inaccurate, as it doesn't capture fractional seconds.

Right-open intervals also have the extremely nice technical property that they create a closed algebra. Concretely, the complement of a vector of right-open intervals and the union, intersection, or difference of two vectors of right-open intervals will always result in another vector of right-open intervals.

Missing intervals

When creating interval vectors with iv(), if either bound is incomplete, then both bounds are set to their missing value.

Usage

iv(start, end, ..., ptype = NULL, size = NULL)

iv_pairs(..., ptype = NULL)

Arguments

start, end	[vector] A pair of vectors to represent the bounds of the intervals. To be a valid interval vector, start must be strictly less than end. If either start or end are incomplete / missing, then both bounds will be coerced to missing values. start and end are recycled against each other and are cast to the same type.
...	For iv_pairs(): [vector pairs] Vectors of size 2 representing intervals to include in the result. All inputs will be cast to the same type. For iv(): These dots are for future extensions and must be empty.
ptype	[vector(0) / NULL] A prototype to force for the inner type of the resulting iv. If NULL, this defaults to the common type of the inputs.
size	[integer(1) / NULL] A size to force for the resulting iv. If NULL, this defaults to the common size of the inputs.

Value

An iv.

Examples

library(dplyr, warn.conflicts = FALSE)

set.seed(123)

x <- tibble(
  start = as.Date("2019-01-01") + 1:5,
  end = start + sample(1:10, length(start), replace = TRUE)
)

# Typically you'll use `iv()` with columns of a data frame
mutate(x, iv = iv(start, end), .keep = "unused")

# `iv_pairs()` is useful for generating interval vectors interactively
iv_pairs(c(1, 5), c(2, 3), c(6, 10))

DavisVaughan/ivs documentation built on March 18, 2023, 3:20 p.m.