Finding overlapping ranges
Various methods for finding/counting interval overlaps between two "range-based" objects: a query and a subject.
NOTE: This man page describes the methods that operate on
IntegerRanges and IntegerRangesList derivatives. See
?`findOverlaps,GenomicRanges,GenomicRanges-method`
in the GenomicRanges package for methods that operate on
GenomicRanges or GRangesList
objects.
findOverlaps(query, subject, maxgap=-1L, minoverlap=0L,
type=c("any", "start", "end", "within", "equal"),
select=c("all", "first", "last", "arbitrary"),
...)
countOverlaps(query, subject, maxgap=-1L, minoverlap=0L,
type=c("any", "start", "end", "within", "equal"),
...)
overlapsAny(query, subject, maxgap=-1L, minoverlap=0L,
type=c("any", "start", "end", "within", "equal"),
...)
query %over% subject
query %within% subject
query %outside% subject
subsetByOverlaps(x, ranges, maxgap=-1L, minoverlap=0L,
type=c("any", "start", "end", "within", "equal"),
invert=FALSE,
...)
overlapsRanges(query, subject, hits=NULL, ...)
poverlaps(query, subject, maxgap = 0L, minoverlap = 1L,
type = c("any", "start", "end", "within", "equal"),
...)
mergeByOverlaps(query, subject, ...)
findOverlapPairs(query, subject, ...)query, subject, x, ranges |
Each of them can be an IntegerRanges (e.g. IRanges,
Views) or IntegerRangesList (e.g. IRangesList,
ViewsList) derivative.
In addition, if If If both arguments are list-like objects with names, each list element from the 2nd argument is paired with the list element from the 1st argument with the matching name, if any. Otherwise, list elements are paired by position. The overlap is then computed between the pairs as described below. If |
maxgap |
A single integer >= -1. If If |
minoverlap |
A single non-negative integer. Only ranges with a minimum of When |
type |
By default, any overlap is accepted. By specifying the The |
select |
If If |
invert |
If |
hits |
The Hits or HitsList object returned
by |
... |
Further arguments to be passed to or from other methods:
|
A common type of query that arises when working with intervals is finding which intervals in one set overlap those in another.
The simplest approach is to call the findOverlaps function
on a IntegerRanges or other object with range information (aka
"range-based object").
For findOverlaps: see select argument above.
For countOverlaps: the overlap hit count for each range
in query using the specified findOverlaps parameters.
For IntegerRangesList objects, it returns an IntegerList
object.
overlapsAny finds the ranges in query that overlap any
of the ranges in subject. For IntegerRanges derivatives,
it returns a logical vector of length equal to the number of
ranges in query. For IntegerRangesList derivatives,
it returns a LogicalList object where each element of the result
corresponds to a space in query.
%over% and %within% are convenience wrappers for the
2 most common use cases. Currently defined as
`%over%` <- function(query, subject) overlapsAny(query, subject)
and
`%within%` <- function(query, subject)
overlapsAny(query, subject,
type="within"). %outside% is simply the inverse of %over%.
subsetByOverlaps returns the subset of x that
has an overlap hit with a range in ranges using the specified
findOverlaps parameters.
When hits is a Hits (or HitsList)
object, overlapsRanges(query, subject, hits) returns a
IntegerRanges (or IntegerRangesList) object of the same
shape as hits holding the regions of intersection between the
overlapping ranges in objects query and subject, which should
be the same query and subject used in the call to findOverlaps that
generated hits.
Same shape means same length when hits is a
Hits object, and same length and same elementNROWS
when hits is a HitsList object.
poverlaps compares query and subject in parallel
(like e.g., pmin) and returns a logical vector indicating
whether each pair of ranges overlaps. Integer vectors are treated as
width-one ranges.
mergeByOverlaps computes the overlap between query and subject
according to the arguments in .... It then extracts the
corresponding hits from each object and returns a DataFrame
containing one column for the query and one for the subject, as well
as any mcols that were present on either object. The query and
subject columns are named by quoting and deparsing the corresponding
argument.
findOverlapPairs is like mergeByOverlaps, except it
returns a formal Pairs object
that provides useful downstream conveniences, such as finding the
intersection of the overlapping ranges with pintersect.
Michael Lawrence and Hervé Pagès
Allen's Interval Algebra: James F. Allen: Maintaining knowledge about temporal intervals. In: Communications of the ACM. 26/11/1983. ACM Press. S. 832-843, ISSN 0001-0782
Hits and HitsList objects in the S4Vectors package for representing a set of hits between 2 vector-like or list-like objects.
findOverlaps,GenomicRanges,GenomicRanges-method in the GenomicRanges package for methods that operate on GRanges or GRangesList objects.
The NCList class and constructor.
The IntegerRanges, Views, IntegerRangesList, and ViewsList classes.
The IntegerList and LogicalList classes.
## ---------------------------------------------------------------------
## findOverlaps()
## ---------------------------------------------------------------------
query <- IRanges(c(1, 4, 9), c(5, 7, 10))
subject <- IRanges(c(2, 2, 10), c(2, 3, 12))
findOverlaps(query, subject)
## at most one hit per query
findOverlaps(query, subject, select="first")
findOverlaps(query, subject, select="last")
findOverlaps(query, subject, select="arbitrary")
## including adjacent ranges in the result
findOverlaps(query, subject, maxgap=0L)
query <- IRanges(c(1, 4, 9), c(5, 7, 10))
subject <- IRanges(c(2, 2), c(5, 4))
## one IRanges object with itself
findOverlaps(query)
## single points as query
subject <- IRanges(c(1, 6, 13), c(4, 9, 14))
findOverlaps(c(3L, 7L, 10L), subject, select="first")
## special overlap types
query <- IRanges(c(1, 5, 3, 4), width=c(2, 2, 4, 6))
subject <- IRanges(c(1, 3, 5, 6), width=c(4, 4, 5, 4))
findOverlaps(query, subject, type="start")
findOverlaps(query, subject, type="start", maxgap=1L)
findOverlaps(query, subject, type="end", select="first")
ov <- findOverlaps(query, subject, type="within", maxgap=1L)
ov
## Using pairs to find intersection of overlapping ranges
hits <- findOverlaps(query, subject)
p <- Pairs(query, subject, hits=hits)
pintersect(p)
## Shortcut
p <- findOverlapPairs(query, subject)
pintersect(p)
## ---------------------------------------------------------------------
## overlapsAny()
## ---------------------------------------------------------------------
overlapsAny(query, subject, type="start")
overlapsAny(query, subject, type="end")
query %over% subject # same as overlapsAny(query, subject)
query %within% subject # same as overlapsAny(query, subject,
# type="within")
## ---------------------------------------------------------------------
## overlapsRanges()
## ---------------------------------------------------------------------
## Extract the regions of intersection between the overlapping ranges:
overlapsRanges(query, subject, ov)
## ---------------------------------------------------------------------
## Using IntegerRangesList objects
## ---------------------------------------------------------------------
query <- IRanges(c(1, 4, 9), c(5, 7, 10))
qpartition <- factor(c("a","a","b"))
qlist <- split(query, qpartition)
subject <- IRanges(c(2, 2, 10), c(2, 3, 12))
spartition <- factor(c("a","a","b"))
slist <- split(subject, spartition)
## at most one hit per query
findOverlaps(qlist, slist, select="first")
findOverlaps(qlist, slist, select="last")
findOverlaps(qlist, slist, select="arbitrary")
query <- IRanges(c(1, 5, 3, 4), width=c(2, 2, 4, 6))
qpartition <- factor(c("a","a","b","b"))
qlist <- split(query, qpartition)
subject <- IRanges(c(1, 3, 5, 6), width=c(4, 4, 5, 4))
spartition <- factor(c("a","a","b","b"))
slist <- split(subject, spartition)
overlapsAny(qlist, slist, type="start")
overlapsAny(qlist, slist, type="end")
qlist
subsetByOverlaps(qlist, slist)
countOverlaps(qlist, slist)Please choose more modern alternatives, such as Google Chrome or Mozilla Firefox.