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.
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, ...)

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. 
nearest:
Performs conventional nearest neighbour finding.
Returns an integer vector containing the index of the nearest neighbour
tuple/range in subject
for each range in x
. If there is no
nearest neighbour NA
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 in subject
that is directly
preceded by the tuple/range in x
. Overlapping tuples/ranges are
excluded. NA
is returned when there are no qualifying
tuples/ranges in subject
.
follow:
The opposite of precede
, follow
returns
the index of the tuple/range in subject
that is directly followed
by the tuple/range in x
. Overlapping tuples/ranges are excluded.
NA
is returned when there are no qualifying tuples/ranges in
subject
.
Orientation and Strand:
The relevant orientation for precede
and follow
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
and
follow
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. When
ignore.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 the subject
.
distance:
Returns the distance for each tuple/range in x
to the range in
y
. The behaviour of distance
has changed in Bioconductor
2.12. See the man page ?distance
in IRanges for details.
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
.
Peter Hickey for methods involving GTuples
. P. Aboyoun
and V. Obenchain <vobencha@fhcrc.org> for all the real work underlying the
powerful nearest methods.
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.
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)

Questions? Problems? Suggestions? Tweet to @rdrrHQ or email at ian@mutexlabs.com.
All documentation is copyright its authors; we didn't write any of that.