nearest-methods {IRanges}R Documentation

Finding the nearest range neighbor

Description

The nearest, precede, follow, distance and distanceToNearest methods for Ranges objects and subclasses.

Usage

## S4 method for signature 'Ranges,RangesORmissing'
nearest(x, subject, select = c("arbitrary", "all"),
        algorithm = c("nclist", "intervaltree"))

## S4 method for signature 'Ranges,RangesORmissing'
precede(x, subject, select = c("first", "all"))

## S4 method for signature 'Ranges,RangesORmissing'
follow(x, subject, select = c("last", "all"))

## S4 method for signature 'Ranges,RangesORmissing'
distanceToNearest(x, subject, select = c("arbitrary", "all"),
                  algorithm = c("nclist", "intervaltree"))

## S4 method for signature 'Ranges,Ranges'
distance(x, y)

Arguments

x

The query Ranges instance.

subject

The subject Ranges instance, within which the nearest neighbors are found. Can be missing, in which case x is also the subject.

select

Logic for handling ties. By default, all the methods select a single interval (arbitrary for nearest,the first by order in subject for precede, and the last for follow). To get all matchings, as a Hits object, use “all”.

algorithm

This argument is passed to findOverlaps, which nearest and distanceToNearest use internally. See ?findOverlaps for more information. Note that it will be removed in BioC 3.3 so please don't use it unless you have a good reason to do so (e.g. troubleshooting).

y

For the distance method, a Ranges instance. Cannot be missing. If x and y are not the same length, the shortest will be recycled to match the length of the longest.

...

Additional arguments for methods

Details

Value

For nearest, precede and follow, an integer vector of indices in subject, or a Hits if select="all".

For distanceToNearest, a Hits object with an elementMetadata column of the distance between the pair. Access distance with mcols accessor.

For distance, an integer vector of distances between the ranges in x and y.

Author(s)

M. Lawrence

See Also

Examples

  ## ------------------------------------------
  ## precede() and follow()
  ## ------------------------------------------
  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)

  ## ------------------------------------------
  ## nearest()
  ## ------------------------------------------
  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)

  ## ------------------------------------------
  ## distance()
  ## ------------------------------------------
  ## adjacent
  distance(IRanges(1,5), IRanges(6,10)) # 0L
  ## overlap
  distance(IRanges(1,5), IRanges(3,7))  # 0L
  ## zero-width
  sapply(-3:3, function(i) distance(shift(IRanges(4,3), i), IRanges(4,3))) 

[Package IRanges version 2.2.5 Index]