relation-detect {ivs}

Detect a relationship between two ivs

Description

This family of functions detects different types of relationships between two ivs. It works similar to base::%in%, where needles[i] checks for a relationship in all of haystack.

• iv_overlaps() detects a specific type of overlap between the two ivs.

• iv_precedes() detects if needles[i] precedes (i.e. comes before) any interval in haystack.

• iv_follows() detects if needles[i] follows (i.e. comes after) any interval in haystack.

These functions return a logical vector the same size as needles containing TRUE if the interval in needles has a matching relationship in haystack and FALSE otherwise.

Usage

iv_overlaps(needles, haystack, ..., type = "any", missing = "equals")

iv_precedes(needles, haystack, ..., missing = "equals")

iv_follows(needles, haystack, ..., missing = "equals")

Arguments

needles, haystack

⁠[iv]⁠

Interval vectors used for relation matching.

• Each element of needles represents the interval to search for.

• haystack represents the intervals to search in.

Prior to comparison, needles and haystack are coerced to the same type.

...

These dots are for future extensions and must be empty.

type

⁠[character(1)]⁠

The type of relationship to find. One of:

• "any": Finds any overlap whatsoever between an interval in needles and an interval in haystack.

• "within": Finds when an interval in needles is completely within (or equal to) an interval in haystack.

• "contains": Finds when an interval in needles completely contains (or equals) an interval in haystack.

• "equals": Finds when an interval in needles is exactly equal to an interval in haystack.

• "starts": Finds when the start of an interval in needles matches the start of an interval in haystack.

• "ends": Finds when the end of an interval in needles matches the end of an interval in haystack.

missing

⁠[logical(1) / "equals" / "error"]⁠

Handling of missing intervals in needles.

• "equals" considers missing intervals in needles as exactly equal to missing intervals in haystack when determining if there is a matching relationship between them. Matched missing intervals in needles result in a TRUE value in the result, and unmatched missing intervals result in a FALSE value.

• "error" throws an error if any intervals in needles are missing.

• If a single logical value is provided, this represents the value returned in the result for intervals in needles that are missing. You can force missing intervals to be unmatched by setting this to FALSE, and you can force them to be propagated by setting this to NA.

Value

A logical vector the same size as needles.

See Also

Locating relationships

Detecting relationships pairwise

Locating relations from Allen's Interval Algebra

Examples

library(vctrs)

x <- iv_pairs(
  as.Date(c("2019-01-05", "2019-01-10")),
  as.Date(c("2019-01-07", "2019-01-15")),
  as.Date(c("2019-01-20", "2019-01-31"))
)

y <- iv_pairs(
  as.Date(c("2019-01-01", "2019-01-03")),
  as.Date(c("2019-01-04", "2019-01-08")),
  as.Date(c("2019-01-07", "2019-01-09")),
  as.Date(c("2019-01-10", "2019-01-20")),
  as.Date(c("2019-01-15", "2019-01-20"))
)

x
y

# Does each interval of `x` overlap `y` at all?
iv_overlaps(x, y)

# Which intervals of `y` are within an interval in `x`?
iv_overlaps(y, x, type = "within")

# ---------------------------------------------------------------------------

a <- iv(c(1, NA), c(2, NA))
b <- iv(c(NA, NA), c(NA, NA))

# Missing intervals are seen as exactly equal by default, so they are
# considered to overlap
iv_overlaps(a, b)

# If you'd like missing intervals to be treated as unmatched, set
# `missing = FALSE`
iv_overlaps(a, b, missing = FALSE)

# If you'd like to propagate missing intervals, set `missing = NA`
iv_overlaps(a, b, missing = NA)