findOverlaps-methods {IRanges} | R Documentation |
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 Ranges,
Views, RangesList, or ViewsList objects. See
?`findOverlaps,GenomicRanges,GenomicRanges-method`
in the GenomicRanges package for methods that operate on
GenomicRanges or GRangesList
objects.
findOverlaps(query, subject, maxgap=0L, minoverlap=1L, type=c("any", "start", "end", "within", "equal"), select=c("all", "first", "last", "arbitrary"), ...) countOverlaps(query, subject, maxgap=0L, minoverlap=1L, type=c("any", "start", "end", "within", "equal"), ...) overlapsAny(query, subject, maxgap=0L, minoverlap=1L, type=c("any", "start", "end", "within", "equal"), ...) query %over% subject query %within% subject query %outside% subject subsetByOverlaps(query, subject, maxgap=0L, minoverlap=1L, type=c("any", "start", "end", "within", "equal"), invert=FALSE, ...) mergeByOverlaps(query, subject, ...) findOverlapPairs(query, subject, ...) poverlaps(query, subject, maxgap = 0L, minoverlap = 1L, type = c("any", "start", "end", "within", "equal"), ...) ## S4 method for signature 'Hits' ranges(x, query, subject) ## S4 method for signature 'HitsList' ranges(x, query, subject)
query, subject |
Each of them can be a Ranges, Views, RangesList,
ViewsList, or RangedData object.
In addition, if If If |
maxgap, minoverlap |
Intervals with a separation of |
type |
By default, any overlap is accepted. By specifying the The |
select |
If If |
invert |
If |
... |
Further arguments to be passed to or from other methods:
|
x |
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 Ranges 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 RangesList objects, it returns an IntegerList object.
overlapsAny
finds the ranges in query
that overlap any
of the ranges in subject
. For Ranges or Views
objects, it returns a logical vector of length equal to the number of
ranges in query
. For RangesList, RangedData, or
ViewsList objects, 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 query
that
has an overlap hit with a range in subject
using the specified
findOverlaps
parameters.
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
.
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.
When x
is a Hits (or HitsList)
object, ranges(x, query, subject)
returns a Ranges
(or RangesList) object of the same shape as x
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
x
.
Same shape means same length when x
is a
Hits object, and same length and same elementNROWS
when x
is a HitsList object.
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 Ranges, Views, RangesList, and ViewsList classes.
The IntegerList and LogicalList classes.
query <- IRanges(c(1, 4, 9), c(5, 7, 10)) subject <- IRanges(c(2, 2, 10), c(2, 3, 12)) ## --------------------------------------------------------------------- ## findOverlaps() ## --------------------------------------------------------------------- ## at most one hit per query findOverlaps(query, subject, select="first") findOverlaps(query, subject, select="last") findOverlaps(query, subject, select="arbitrary") ## overlap even if adjacent only ## (FIXME: the gap between 2 adjacent ranges should be still considered ## 0. So either we have an argument naming problem, or we should modify ## the handling of the 'maxgap' argument so that the user would need to ## specify maxgap=0L to obtain the result below.) findOverlaps(query, subject, maxgap=1L) ## shortcut findOverlaps(query, subject) query <- IRanges(c(1, 4, 9), c(5, 7, 10)) subject <- IRanges(c(2, 2), c(5, 4)) ## one Ranges 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") ## alternative 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") ## --------------------------------------------------------------------- ## "ranges" METHODS FOR Hits OR HitsList OBJECTS ## --------------------------------------------------------------------- ## extract the regions of intersection between the overlapping ranges ranges(ov, query, subject) ## --------------------------------------------------------------------- ## Using RangesList 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)