nearest               package: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)

