nearest {IRanges} | R Documentation |
The nearest
, precede
and follow
methods find
nearest neighbors between Ranges
instances.
nearest(x, subject, ...) ## S4 method for signature 'Ranges,RangesORmissing' nearest(x, subject, select = c("arbitrary", "all")) precede(x, subject = x, ...) ## S4 method for signature 'Ranges,RangesORmissing' precede(x, subject, select = c("first", "all")) follow(x, subject = x, ...) ## S4 method for signature 'Ranges,RangesORmissing' follow(x, subject, select = c("last", "all")) distanceToNearest(x, subject = x, ...) ## S4 method for signature 'Ranges,RangesORmissing' distanceToNearest(x, subject, select = c("arbitrary", "all"))
x |
The query |
subject |
The subject |
select |
Logic for handling ties. By default, all of the methods
here will select a single interval (arbitrary for |
... |
Additional arguments for methods |
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
:
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.
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.
distanceToNearest
returns the distance for each range
in x
to its nearest neighbor in subject
.
For nearest
, precede
and follow
, an integer
vector of indices in subject
, or
a RangesMatching
if select
is
“all”.
For distanceToNearest
, a DataFrame
with a column for
the query
index, subject
index and distance
between the pair. This may become more formal in the future.
M. Lawrence
findOverlaps
for finding just the overlapping ranges.
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)