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

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.6.16 Index]