vector-detect {ivs}

Detect relationships between a vector and an iv

Description

This family of functions detects different types of relationships between a vector and an iv. It works similar to base::%in%, where needles[i] checks for a match in all of haystack.

• iv_between() detects when needles, a vector, falls between the bounds in haystack, an iv.

• iv_includes() detects when needles, an iv, includes the values of haystack, a vector.

This function returns a logical vector the same size as needles containing TRUE if the value in needles matches any value in haystack and FALSE otherwise.

Usage

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

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

Arguments

needles, haystack

⁠[vector, iv]⁠

For ⁠iv_*_between()⁠, needles should be a vector and haystack should be an iv.

For ⁠iv_*_includes()⁠, needles should be an iv and haystack should be a vector.

• Each element of needles represents the value / interval to match.

• haystack represents the values / intervals to match against.

...

These dots are for future extensions and must be empty.

missing

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

Handling of missing values in needles.

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

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

• If a single logical value is provided, this represents the value returned in the result for values in needles that are missing. You can force missing values 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

Locating relationships between a vector and an iv

Pairwise detect relationships between a vector and an iv

Examples

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

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

# Detect if the i-th location in `x` is between any intervals in `y`
iv_between(x, y)

# Detect if the i-th location in `y` includes any value in `x`
iv_includes(y, x)

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

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

# By default, missing values in `needles` are treated as being exactly
# equal to missing values in `haystack`, so the missing value in `a` is
# considered between the missing interval in `b`.
iv_between(a, b)
iv_includes(b, a)

# If you'd like to propagate missing values, set `missing = NA`
iv_between(a, b, missing = NA)
iv_includes(b, a, missing = NA)

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