R: Locate relationships between two ivs

relation-locate {ivs}

R Documentation

Locate relationships between two ivs

Description

This family of functions locates different types of relationships between two ivs. It works similar to base::match(), where needles[i] checks for a relationship in all of haystack. Unlike match(), all matching relationships are returned, rather than just the first.

iv_locate_overlaps() locates a specific type of overlap between the two ivs.
iv_locate_precedes() locates where needles[i] precedes (i.e. comes before) any interval in haystack.
iv_locate_follows() locates where needles[i] follows (i.e. comes after) any interval in haystack.

These functions return a two column data frame. The needles column is an integer vector pointing to locations in needles. The haystack column is an integer vector pointing to locations in haystack with a matching relationship.

Usage

iv_locate_overlaps(
  needles,
  haystack,
  ...,
  type = "any",
  missing = "equals",
  no_match = NA_integer_,
  remaining = "drop",
  multiple = "all",
  relationship = "none"
)

iv_locate_precedes(
  needles,
  haystack,
  ...,
  closest = FALSE,
  missing = "equals",
  no_match = NA_integer_,
  remaining = "drop",
  multiple = "all",
  relationship = "none"
)

iv_locate_follows(
  needles,
  haystack,
  ...,
  closest = FALSE,
  missing = "equals",
  no_match = NA_integer_,
  remaining = "drop",
  multiple = "all",
  relationship = "none"
)

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`	`⁠[integer(1) / "equals" / "drop" / "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. `"drop"` drops missing intervals in `needles` from the result. `"error"` throws an error if any intervals in `needles` are missing. If a single integer is provided, this represents the value returned in the `haystack` column for intervals in `needles` that are missing.
`no_match`	Handling of `needles` without a match. `"drop"` drops `needles` with zero matches from the result. `"error"` throws an error if any `needles` have zero matches. If a single integer is provided, this represents the value returned in the `haystack` column for values of `needles` that have zero matches. The default represents an unmatched needle with `NA`.
`remaining`	Handling of `haystack` values that `needles` never matched. `"drop"` drops remaining `haystack` values from the result. Typically, this is the desired behavior if you only care when `needles` has a match. `"error"` throws an error if there are any remaining `haystack` values. If a single integer is provided (often `NA`), this represents the value returned in the `needles` column for the remaining `haystack` values that `needles` never matched. Remaining `haystack` values are always returned at the end of the result.
`multiple`	Handling of `needles` with multiple matches. For each needle: `"all"` returns all matches detected in `haystack`. `"any"` returns any match detected in `haystack` with no guarantees on which match will be returned. It is often faster than `"first"` and `"last"` if you just need to detect if there is at least one match. `"first"` returns the first match detected in `haystack`. `"last"` returns the last match detected in `haystack`.
`relationship`	Handling of the expected relationship between `needles` and `haystack`. If the expectations chosen from the list below are invalidated, an error is thrown. `"none"` doesn't perform any relationship checks. `"one-to-one"` expects: Each value in `needles` matches at most 1 value in `haystack`. Each value in `haystack` matches at most 1 value in `needles`. `"one-to-many"` expects: Each value in `needles` matches any number of values in `haystack`. Each value in `haystack` matches at most 1 value in `needles`. `"many-to-one"` expects: Each value in `needles` matches at most 1 value in `haystack`. Each value in `haystack` matches any number of values in `needles`. `"many-to-many"` expects: Each value in `needles` matches any number of values in `haystack`. Each value in `haystack` matches any number of values in `needles`. This performs no checks, and is identical to `"none"`, but is provided to allow you to be explicit about this relationship if you know it exists. `"warn-many-to-many"` doesn't assume there is any known relationship, but will warn if `needles` and `haystack` have a many-to-many relationship (which is typically unexpected), encouraging you to either take a closer look at your inputs or make this relationship explicit by specifying `"many-to-many"`. `relationship` is applied after `filter` and `multiple` to allow potential multiple matches to be filtered out first. `relationship` doesn't handle cases where there are zero matches. For that, see `no_match` and `remaining`.
`closest`	`⁠[TRUE / FALSE]⁠` Should only the closest relationship be returned? If `TRUE`, will only return the closest interval(s) in `haystack` that the current value of `needles` either precedes or follows. Note that multiple intervals can still be returned if there are ties, which can be resolved using `multiple`.

Value

A data frame containing two integer columns named needles and haystack.

Examples

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

# Find any overlap between `x` and `y`
loc <- iv_locate_overlaps(x, y)
loc

iv_align(x, y, locations = loc)

# Find where `x` contains `y` and drop results when there isn't a match
loc <- iv_locate_overlaps(x, y, type = "contains", no_match = "drop")
loc

iv_align(x, y, locations = loc)

# Find where `x` precedes `y`
loc <- iv_locate_precedes(x, y)
loc

iv_align(x, y, locations = loc)

# Filter down to find only the closest interval in `y` of all the intervals
# where `x` preceded it
loc <- iv_locate_precedes(x, y, closest = TRUE)

iv_align(x, y, locations = loc)

# Note that `closest` can result in duplicates if there is a tie.
# `2019-01-20` appears as an end date twice in `haystack`.
loc <- iv_locate_follows(x, y, closest = TRUE)
loc

iv_align(x, y, locations = loc)

# Force just one of the ties to be returned by using `multiple`.
# Here we just request any of the ties, with no guarantee on which one.
loc <- iv_locate_follows(x, y, closest = TRUE, multiple = "any")
loc

iv_align(x, y, locations = loc)

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

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

# By default, missing intervals in `needles` are seen as exactly equal to
# missing intervals in `haystack`, which means that they overlap
iv_locate_overlaps(a, b)

# If you'd like missing intervals in `needles` to always be considered
# unmatched, set `missing = NA`
iv_locate_overlaps(a, b, missing = NA)