nearest {IRanges} | R Documentation

## Nearest neighbor finding

### Description

The `nearest`, `precede` and `follow` methods find nearest neighbors between `Ranges` instances.

### Usage

      nearest(x, subject, ...)
      precede(x, subject = x, ...)
      follow(x, subject = x, ...)

### Arguments

`x` | The query `Ranges` instance.
`subject` | The subject `Ranges` instance, within which the nearest neighbors are found. Can be missing, in which case the query, `x`, is also the subject.
`...` | Additional arguments for methods

### Details

`nearest` is the conventional nearest neighbor finder and returns a integer vector containing the index of the nearest neighbor range in `subject` for each range in `x`. If there is no nearest neighbor (if `subject` is empty), NA's are returned.

The algorithm is roughly as follows, for a range `xi` in `x`:

1. Find the ranges in `subject` that overlap `xi`. If a single range `si` in `subject` overlaps `xi`, `si` is returned as the nearest neighbor of `xi`. If there are multiple overlaps, one of the overlapping ranges is chosen arbitrarily.
2. If no ranges in `subject` overlap with `xi`, then the range in `subject` with the shortest distance from its end to the start `xi` or its start to the end of `xi` is returned.

`precede` returns an integer vector of the index of range in `subject` that ends before and closest to the start of each range in `x`. Note that any overlapping ranges are excluded. `NA` is returned when there are no qualifying ranges in `subject`.

`follow` is the opposite of `precede`: it returns the index of the range in `subject` that starts after and closest to the end of each range in `x`.

### Author(s)

M. Lawrence

### See Also

`overlap` for finding just the overlapping ranges.

### Examples

      query <- IRanges(c(1, 3, 9), c(2, 7, 10))
      subject <- IRanges(c(3, 5, 12), c(3, 6, 12))

      nearest(query, subject) # c(1L, 1L, 3L)
      nearest(query) # c(2L, 1L, 2L)

      query <- IRanges(c(1, 3, 9), c(3, 7, 10))
      subject <- IRanges(c(3, 2, 10), c(3, 13, 12))

      precede(query, subject) # c(3L, 3L, NA)
      precede(IRanges(), subject) # integer()
      precede(query, IRanges()) # rep(NA_integer_, 3)
      precede(query) # c(3L, 3L, NA)

      follow(query, subject) # c(NA, NA, 1L)
      follow(IRanges(), subject) # integer()
      follow(query, IRanges()) # rep(NA_integer_, 3)
      follow(query) # c(NA, NA, 2L)

[Package IRanges version 1.2.3 Index]