Finding the nearest genomic tuple/range neighbour
Description
The nearest
, precede
, follow
, distance
and distanceToNearest
methods for GTuples
objects and subclasses.
NOTE: These methods treat the tuples as if they were ranges, with
ranges given by [pos_{1}, pos_{m}] and where m is the
size,GTuplesmethod
of the tuples. This is done via inheritance
so that a GTuples
object is treated as a
GRanges
and the appropriate method is dispatched
upon.
Usage
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30  ## S4 method for signature 'GTuples,GTuples'
precede(x, subject, select = c("arbitrary", "all"),
ignore.strand = FALSE, ...)
## S4 method for signature 'GTuples,missing'
precede(x, subject, select = c("arbitrary", "all"),
ignore.strand = FALSE, ...)
## S4 method for signature 'GTuples,GTuples'
follow(x, subject, select = c("arbitrary", "all"),
ignore.strand=FALSE, ...)
## S4 method for signature 'GTuples,missing'
follow(x, subject, select = c("arbitrary", "all"),
ignore.strand = FALSE, ...)
## S4 method for signature 'GTuples,GTuples'
nearest(x, subject, select = c("arbitrary", "all"),
ignore.strand = FALSE, ...)
## S4 method for signature 'GTuples,missing'
nearest(x, subject, select = c("arbitrary", "all"),
ignore.strand = FALSE, ...)
## S4 method for signature 'GTuples,GTuples'
distanceToNearest(x, subject, ignore.strand = FALSE,
...)
## S4 method for signature 'GTuples,missing'
distanceToNearest(x, subject, ignore.strand = FALSE,
...)
## S4 method for signature 'GTuples,GTuples'
distance(x, y, ignore.strand = FALSE, ...)

Arguments
x 
The query GTuples instance. 
subject 
The subject GTuples instance
within which the nearest neighbours are found. Can be missing,
in which case 
y 
For the 
select 
Logic for handling ties. By default, all methods
select a single tuple/range (arbitrary for When 
ignore.strand 
A 
... 
Additional arguments for methods. 
Details
nearest: Performs conventional nearest neighbour finding. Returns an integer vector containing the index of the nearest neighbour tuple/range in
subject
for each range inx
. If there is no nearest neighbourNA
is returned. For details of the algorithm see the man page in IRanges, ?nearest
.precede: For each range in
x
,precede
returns the index of the tuple/range insubject
that is directly preceded by the tuple/range inx
. Overlapping tuples/ranges are excluded.NA
is returned when there are no qualifying tuples/ranges insubject
.follow: The opposite of
precede
,follow
returns the index of the tuple/range insubject
that is directly followed by the tuple/range inx
. Overlapping tuples/ranges are excluded.NA
is returned when there are no qualifying tuples/ranges insubject
.Orientation and Strand: The relevant orientation for
precede
andfollow
is 5' to 3', consistent with the direction of translation. Because positional numbering along a chromosome is from left to right and transcription takes place from 5' to 3',precede
andfollow
can appear to have ‘opposite’ behaviour on the+
and
strand. Using positions 5 and 6 as an example, 5 precedes 6 on the+
strand but follows 6 on the
strand.A tuple/range with strand
*
can be compared to tuples/ranges on either the+
or
strand. Below we outline the priority when tuples/ranges on multiple strands are compared. Whenignore.strand=TRUE
all tuples/ranges are treated as if on the+
strand.x on + strand can match to tuples/ranges on both + and * strands. In the case of a tie the first tuple/range by order is chosen.
x on  strand can match to tuples/ranges on both  and * strands. In the case of a tie the first tuple/range by order is chosen.
x on * strand can match to tuples/ranges on any of +,  or * strands. In the case of a tie the first tuple/range by order is chosen.
distanceToNearest: Returns the distance for each tuple/range in
x
to its nearest neighbour in thesubject
.distance: Returns the distance for each tuple/range in
x
to the range iny
. The behaviour ofdistance
has changed in Bioconductor 2.12. See the man page?distance
in IRanges for 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 a
column for the query
index (from), subject
index
(to) and the distance
between the pair.
For distance
, an integer vector of distances between the tuples/ranges
in x
and y
.
Author(s)
Peter Hickey for methods involving GTuples
. P. Aboyoun
and V. Obenchain <vobencha@fhcrc.org> for all the real work underlying the
powerful nearest methods.
See Also
The GTuples and GRanges classes.
The GenomicRanges and GRanges classes in the GenomicRanges package.
The Ranges class in the IRanges package.
The Hits class in the S4Vectors package.
The nearestmethods man page in the GenomicRanges package.

findOverlapsmethods for finding just the overlapping ranges.
Examples
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57  ## 
## precede() and follow()
## 
query < GTuples("A", matrix(c(5L, 20L, 6L, 21L), ncol = 2), strand = "+")
subject < GTuples("A", matrix(c(rep(c(10L, 15L), 2), rep(c(11L, 16L), 2)),
ncol = 2),
strand = c("+", "+", "", ""))
precede(query, subject)
follow(query, subject)
strand(query) < ""
precede(query, subject)
follow(query, subject)
## ties choose first in order
query < GTuples("A", matrix(c(10L, 11L), ncol = 2), c("+", "", "*"))
subject < GTuples("A", matrix(c(rep(c(5L, 15L), each = 3),
rep(c(6L, 16L), each = 3)), ncol = 2),
rep(c("+", "", "*"), 2))
precede(query, subject)
precede(query, rev(subject))
## ignore.strand = TRUE treats all ranges as '+'
precede(query[1], subject[4:6], select="all", ignore.strand = FALSE)
precede(query[1], subject[4:6], select="all", ignore.strand = TRUE)
## 
## nearest()
## 
## When multiple tuples overlap an "arbitrary" tuple is chosen
query < GTuples("A", matrix(c(5L, 15L), ncol = 2))
subject < GTuples("A", matrix(c(1L, 15L, 5L, 19L), ncol = 2))
nearest(query, subject)
## select = "all" returns all hits
nearest(query, subject, select = "all")
## Tuples in 'x' will selfselect when 'subject' is present
query < GTuples("A", matrix(c(1L, 10L, 6L, 15L), ncol = 2))
nearest(query, query)
## Tuples in 'x' will not selfselect when 'subject' is missing
nearest(query)
## 
## distance(), distanceToNearest()
## 
## Adjacent, overlap, separated by 1
query < GTuples("A", matrix(c(1L, 2L, 10L, 5L, 8L, 11L), ncol = 2))
subject < GTuples("A", matrix(c(6L, 5L, 13L, 10L, 10L, 15L), ncol = 2))
distance(query, subject)
## recycling
distance(query[1], subject)
query < GTuples(c("A", "B"), matrix(c(1L, 5L, 2L, 6L), ncol = 2))
distanceToNearest(query, subject)
