3
\alias{nearest-methods}
5
\alias{precede,GenomicRanges,GenomicRanges-method}
6
\alias{precede,GenomicRanges,missing-method}
7
\alias{follow,GenomicRanges,GenomicRanges-method}
8
\alias{follow,GenomicRanges,missing-method}
9
\alias{nearest,GenomicRanges,GenomicRanges-method}
10
\alias{nearest,GenomicRanges,missing-method}
11
\alias{distance,GenomicRanges,GenomicRanges-method}
12
\alias{distanceToNearest,GenomicRanges,GenomicRanges-method}
13
\alias{distanceToNearest,GenomicRanges,missing-method}
15
\title{Finding the nearest genomic range neighbor}
18
The \code{nearest}, \code{precede}, \code{follow}, \code{distance}
19
and \code{distanceToNearest} methods for \code{\linkS4class{GenomicRanges}}
20
objects and subclasses.
24
\S4method{precede}{GenomicRanges,GenomicRanges}(x, subject, select=c("arbitrary", "all"), ignore.strand=FALSE, ...)
25
\S4method{precede}{GenomicRanges,missing}(x, subject, select=c("arbitrary", "all"), ignore.strand=FALSE, ...)
27
\S4method{follow}{GenomicRanges,GenomicRanges}(x, subject, select=c("arbitrary", "all"), ignore.strand=FALSE, ...)
28
\S4method{follow}{GenomicRanges,missing}(x, subject, select=c("arbitrary", "all"), ignore.strand=FALSE, ...)
30
\S4method{nearest}{GenomicRanges,GenomicRanges}(x, subject, select=c("arbitrary", "all"), ignore.strand=FALSE, ...)
31
\S4method{nearest}{GenomicRanges,missing}(x, subject, select=c("arbitrary", "all"), ignore.strand=FALSE, ...)
33
\S4method{distanceToNearest}{GenomicRanges,GenomicRanges}(x, subject, ignore.strand=FALSE, ...)
34
\S4method{distanceToNearest}{GenomicRanges,missing}(x, subject, ignore.strand=FALSE, ...)
36
\S4method{distance}{GenomicRanges,GenomicRanges}(x, y, ignore.strand=FALSE, ...)
40
\item{x}{The query \link{GenomicRanges} instance.
42
\item{subject}{The subject \link{GenomicRanges} instance
43
within which the nearest neighbors are found. Can be missing,
44
in which case \code{x} is also the subject.
46
\item{y}{For the \code{distance} method, a \code{GRanges} instance.
47
Cannot be missing. If \code{x} and \code{y} are not the same
48
length, the shortest will be recycled to match the length of the
51
\item{select}{Logic for handling ties. By default, all methods
52
select a single interval (arbitrary for \code{nearest},
53
the first by order in \code{subject} for \code{precede}, and the
54
last for \code{follow}).
56
When \code{select="all"} a \link[IRanges]{Hits} object is returned with
57
all matches for \code{x}. If \code{x} does not have a match in
58
\code{subject} the \code{x} is not included in the \code{Hits} object.
61
A \code{logical} indicating if the strand of the input ranges
62
should be ignored. When \code{TRUE}, strand is set to \code{'+'}.
64
\item{...}{Additional arguments for methods.}
70
Performs conventional nearest neighbor finding.
71
Returns an integer vector containing the index of the nearest neighbor
72
range in \code{subject} for each range in \code{x}. If there is no
73
nearest neighbor \code{NA} is returned. For details of the algorithm
74
see the man page in IRanges, ?\code{nearest}.
77
For each range in \code{x}, \code{precede} returns
78
the index of the range in \code{subject} that is directly
79
preceded by the range in \code{x}. Overlapping ranges are excluded.
80
\code{NA} is returned when there are no qualifying ranges in
84
The opposite of \code{precede}, \code{follow} returns
85
the index of the range in \code{subject} that is directly followed by the
86
range in \code{x}. Overlapping ranges are excluded. \code{NA} is returned
87
when there are no qualifying ranges in \code{subject}.
89
\item{Orientation and Strand: }{
90
The relevant orientation for \code{precede} and \code{follow}
91
is 5' to 3', consistent with the direction of translation.
92
Because positional numbering along a chromosome is from left to
93
right and transcription takes place from 5' to 3', \code{precede} and
94
\code{follow} can appear to have `opposite' behavior on the \code{+}
95
and \code{-} strand. Using positions 5 and 6 as an example, 5 precedes
96
6 on the \code{+} strand but follows 6 on the \code{-} strand.
98
A range with strand \code{*} can be compared to ranges on either the
99
\code{+} or \code{-} strand. Below we outline the priority when ranges
100
on multiple strands are compared. When \code{ignore.strand=TRUE} all
101
ranges are treated as if on the \code{+} strand.
103
\item{}{x on + strand can match to ranges on both + and
104
* strands. In the case of a tie the first range by order
107
\item{}{x on - strand can match to ranges on both - and
108
* strands. In the case of a tie the first range by order
111
\item{}{x on * strand can match to ranges on any of +,
112
- or * strands. In the case of a tie the first range by
117
\item{distanceToNearest: }{Returns the distance for each range in \code{x}
118
to its nearest neighbor in the \code{subject}.
121
Returns the distance for each range in \code{x} to the range in \code{y}.
122
The behavior of \code{distance} has changed in Bioconductor 2.12.
123
See the man page \code{?distance} in IRanges for details.
129
For \code{nearest}, \code{precede} and \code{follow}, an integer
130
vector of indices in \code{subject}, or a \code{\linkS4class{Hits}} if
133
For \code{distanceToNearest}, a \code{Hits} object with a column for
134
the \code{query} index (queryHits), \code{subject} index (subjectHits)
135
and the \code{distance} between the pair.
137
For \code{distance}, an integer vector of distances between the ranges
138
in \code{x} and \code{y}.
141
\author{P. Aboyoun and V. Obenchain <vobencha@fhcrc.org>}
145
\item The \link{GenomicRanges} and \link{GRanges} classes.
146
\item The \link[IRanges]{Ranges} and \link[IRanges]{Hits} classes in the
148
\item The \link[IRanges]{nearest-methods} man page in the IRanges package.
149
\item \link[GenomicRanges]{findOverlaps-methods} for finding just the
155
## -----------------------------------------------------------
156
## precede() and follow()
157
## -----------------------------------------------------------
158
query <- GRanges("A", IRanges(c(5, 20), width=1), strand="+")
159
subject <- GRanges("A", IRanges(rep(c(10, 15), 2), width=1),
160
strand=c("+", "+", "-", "-"))
161
precede(query, subject)
162
follow(query, subject)
165
precede(query, subject)
166
follow(query, subject)
168
## ties choose first in order
169
query <- GRanges("A", IRanges(10, width=1), c("+", "-", "*"))
170
subject <- GRanges("A", IRanges(c(5, 5, 5, 15, 15, 15), width=1),
171
rep(c("+", "-", "*"), 2))
172
precede(query, subject)
173
precede(query, rev(subject))
175
## ignore.strand=TRUE treats all ranges as '+'
176
precede(query[1], subject[4:6], select="all", ignore.strand=FALSE)
177
precede(query[1], subject[4:6], select="all", ignore.strand=TRUE)
180
## -----------------------------------------------------------
182
## -----------------------------------------------------------
183
## When multiple ranges overlap an "arbitrary" range is chosen
184
query <- GRanges("A", IRanges(5, 15))
185
subject <- GRanges("A", IRanges(c(1, 15), c(5, 19)))
186
nearest(query, subject)
188
## select="all" returns all hits
189
nearest(query, subject, select="all")
191
## Ranges in 'x' will self-select when 'subject' is present
192
query <- GRanges("A", IRanges(c(1, 10), width=5))
193
nearest(query, query)
195
## Ranges in 'x' will not self-select when 'subject' is missing
198
## -----------------------------------------------------------
199
## distance(), distanceToNearest()
200
## -----------------------------------------------------------
201
## Adjacent, overlap, separated by 1
202
query <- GRanges("A", IRanges(c(1, 2, 10), c(5, 8, 11)))
203
subject <- GRanges("A", IRanges(c(6, 5, 13), c(10, 10, 15)))
204
distance(query, subject)
207
distance(query[1], subject)
210
zw <- GRanges("A", IRanges(4,3))
211
stopifnot(distance(zw, GRanges("A", IRanges(3,4))) == 0L)
212
sapply(-3:3, function(i)
213
distance(shift(zw, i), GRanges("A", IRanges(4,3))))
215
query <- GRanges(c("A", "B"), IRanges(c(1, 5), width=1))
216
distanceToNearest(query, subject)
added
removed
man/nearest-methods.Rd
