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.

For each range in x, precede returns the index of the interval in subject that is directly preceded by the query range. 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 a query range in x directly follows.

Author(s)

M. Lawrence

See Also

findOverlaps 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.8.8 Index]