nearest-methods {IRanges} | R Documentation |
Finding the nearest range/position neighbor
Description
The nearest()
, precede()
, follow()
, distance()
and distanceToNearest()
methods for IntegerRanges
derivatives (e.g. IRanges objects).
Usage
## S4 method for signature 'IntegerRanges,IntegerRanges_OR_missing'
nearest(x, subject, select=c("arbitrary", "all"))
## S4 method for signature 'IntegerRanges,IntegerRanges_OR_missing'
precede(x, subject, select=c("first", "all"))
## S4 method for signature 'IntegerRanges,IntegerRanges_OR_missing'
follow(x, subject, select=c("last", "all"))
## S4 method for signature 'IntegerRanges,IntegerRanges'
distance(x, y)
## S4 method for signature 'Pairs,missing'
distance(x, y)
## S4 method for signature 'IntegerRanges,IntegerRanges_OR_missing'
distanceToNearest(x, subject, select=c("arbitrary", "all"))
Arguments
x |
The query IntegerRanges derivative, or (for
|
subject |
The subject IntegerRanges object, within which
the nearest neighbors are found. Can be missing, in which case
|
select |
Logic for handling ties. By default, all the methods
select a single interval (arbitrary for |
y |
For the |
hits |
The hits between |
... |
Additional arguments for methods |
Details
nearest(x, subject, select=c("arbitrary", "all"))
:-
The conventional nearest neighbor finder. Returns an integer vector containing the index of the nearest neighbor range in
subject
for each range inx
. If there is no nearest neighbor (ifsubject
is empty), NA's are returned.Here is roughly how it proceeds, for a range
xi
inx
:Find the ranges in
subject
that overlapxi
. If a single rangesi
insubject
overlapsxi
,si
is returned as the nearest neighbor ofxi
. If there are multiple overlaps, one of the overlapping ranges is chosen arbitrarily.If no ranges in
subject
overlap withxi
, then the range insubject
with the shortest distance from its end to the startxi
or its start to the end ofxi
is returned.
precede(x, subject, select=c("first", "all"))
:-
For each range in
x
,precede
returns the index of the interval insubject
that is directly preceded by the query range. Overlapping ranges are excluded.NA
is returned when there are no qualifying ranges insubject
. follow(x, subject, select=c("last", "all"))
:-
The opposite of
precede
, this function returns the index of the range insubject
that a query range inx
directly follows. Overlapping ranges are excluded.NA
is returned when there are no qualifying ranges insubject
. distance(x, y)
:-
Returns the distance for each range in
x
to the range iny
.The
distance
method differs from others documented on this page in that it is symmetric;y
cannot be missing. Ifx
andy
are not the same length, the shortest will be recycled to match the length of the longest. Theselect
argument is not available fordistance
because comparisons are made in a pair-wise fashion. The return value is the length of the longest ofx
andy
.The
distance
calculation changed in BioC 2.12 to accommodate zero-width ranges in a consistent and intuitive manner. The new distance can be explained by a block model where a range is represented by a series of blocks of size 1. Blocks are adjacent to each other and there is no gap between them. A visual representation ofIRanges(4,7)
would be+-----+-----+-----+-----+ 4 5 6 7
The distance between two consecutive blocks is 0L (prior to Bioconductor 2.12 it was 1L). The new distance calculation now returns the size of the gap between two ranges.
This change to distance affects the notion of overlaps in that we no longer say:
x and y overlap <=> distance(x, y) == 0
Instead we say
x and y overlap => distance(x, y) == 0
or
x and y overlap or are adjacent <=> distance(x, y) == 0
distanceToNearest(x, subject, select=c("arbitrary", "all"))
:-
Returns the distance for each range in
x
to its nearest neighbor insubject
. selectNearest(hits, x, subject)
:-
Selects the hits that have the minimum distance within those for each query range. Ties are possible and can be broken with
breakTies
.
Value
For nearest()
, precede()
and follow()
, an integer
vector of indices in subject
, or a Hits object
if select="all"
.
For distance()
, an integer vector of distances between the ranges
in x
and y
.
For distanceToNearest()
, a Hits object with
a metadata column reporting the distance
between the pair.
Access the distance
metadata column with the
mcols()
accessor.
For selectNearest()
, a Hits object, sorted by query.
Author(s)
M. Lawrence
See Also
-
Hits objects implemented in the S4Vectors package.
-
findOverlaps
for finding just the overlapping ranges. The IntegerRanges class.
-
nearest-methods in the GenomicRanges package for the
nearest()
,precede()
,follow()
,distance()
, anddistanceToNearest()
methods for GenomicRanges objects.
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)))