set-ops: Set Operations on Time Intervals and Time Indices

In tind: A Common Representation of Time Indices of Different Types

Set Operations on Time Intervals and Time Indices

Description

Time intervals can be thought of as subsets of time line (set of integers or real line, depending on index type). The following functions perform operations on these sets.

unique method for objects of tinterval class returns unique representation as ordered sum of disjoint, non-adjacent intervals.

! (negation) operator for objects of tinterval class returns set-theoretical complement of the argument.

intersect_t, union_t, setdiff_t return intersection, union and (asymmetric) set difference. These three functions accept both time intervals and time indices.

Behaviour of !, intersect_t, union_t, and setdiff_t is consistent with behaviour of %in_t% operator. Consistency is also assured under type conversions.

For time indices, intersect_t, union_t, setdiff_t behave just like intersect, union, setdiff from base (see sets) but preserve class attribute.

Usage

## S3 method for class 'tinterval'
unique(x, ...)

## S3 method for class 'tinterval'
!x

intersect_t(x, y)

union_t(x, y)

setdiff_t(x, y)

Arguments

x	an object of tinterval class for unique method and ! operator, tinterval or tind for intersect_t, union_t, or setdiff_t.
...	(ignored) further arguments passed to or from other methods.
y	an object of tinterval or tind class.

Details

For discrete time indices (represented as integers, i.e. years, quarters, months, weeks, dates, arbitrary integer indices) time intervals represent the following sets (ignoring empty, i.e. with a_i > b_i):

\bigcup_{i = 1}^n A_i = \bigcup_{i = 1}^n \{x: a_i \le x \le b_i\} = \bigcup_{i = 1}^n \{a_i, a_i + 1, \dots, b_i - 1, b_i\}.

unique returns the unique (canonical) representation of the set above:

\bigcup_{i = 1}^{n'} A'_i = \bigcup_{i = 1}^{n'} \{a'_i, a'_i + 1, \dots, b'_i - 1, b'_i\}

with a'_i \le b'_i < a'_{i + 1} - 1, i.e. as a sum of ordered, non-empty, non-adjacent intervals.

For continuous time indices (representing point in time, i.e. date-time, time of day, arbitrary numeric indices) time intervals represent the following sets (ignoring empty, i.e. with a_i \ge b_i):

\bigcup_{i = 1}^n A_i = \bigcup_{i = 1}^n [a_i, b_i).

unique returns unique representation of the set above:

\bigcup_{i = 1}^{n'} A'_i = \bigcup_{i = 1}^{n'} [a'_i, b'_i)

with a'_i < b'_i < a'_{i + 1}, i.e. as a sum of ordered, non-empty, non-adjacent intervals.

Complement of a single interval for integer indices

\{x: a \le x \le b\} = \{a, a + 1, \dots, b - 1, b\}

is:

\{x: x < a\} \cup \{x: x > b\} = \{x: x \le a - 1\} \cup \{x: x \ge b + 1\} = \{\dots, a - 2, a - 1\} \cup \{b + 1, b + 2, \dots\}.

Complement of a single interval for continuous indices

[a, b)

is:

(-\infty, a) \cup [b, \infty).

Complement of a sum of intervals is the intersection of complements.

Set operations always return results in the canonical representation.

Value

An object of tinterval or tind class representing result of the set operation.

See Also

tinterval for an overview of time interval class, match_t for matching time indices

Examples

(x <- tinterval("2025-03-15", "2025-03-20") + c(0, 4, 14))
# unique representation (non-overlapping intervals)
unique(x)
# complement
!x
# binary set operations
(y <- tinterval("2025-03-01", "2025-03-31"))
intersect_t(x, y)
union_t(x, y)
setdiff_t(x, y)
setdiff_t(y, x)
# different types of indices
(y <- tinterval("2025-W10", "2025-W11"))
intersect_t(x, y)
union_t(x, y)
setdiff_t(x, y)
setdiff_t(y, x)
# check
(y <- as.tinterval(y, type = "d"))
intersect_t(x, y)
union_t(x, y)
setdiff_t(x, y)
setdiff_t(y, x)

tind documentation built on Dec. 28, 2025, 1:06 a.m.