Inter range transformations of an IntegerRanges, Views, IntegerRangesList, or MaskCollection object
Range-based transformations are grouped in 2 categories:
Intra range transformations (e.g. shift())
transform each range individually (and independently of the other
ranges). They return an object parallel to the input object,
that is, where the i-th range corresponds to the i-th range in the
input.
Those transformations are described in the intra-range-methods
man page (see ?`intra-range-methods`).
Inter range transformations (e.g. reduce())
transform all the ranges together as a set to produce a new set
of ranges. They return an object that is generally NOT
parallel to the input object.
Those transformations are described below.
## range()
## -------
## S4 method for signature 'IntegerRanges'
range(x, ..., with.revmap=FALSE, na.rm=FALSE)
## S4 method for signature 'IntegerRangesList'
range(x, ..., with.revmap=FALSE, na.rm=FALSE)
## reduce()
## --------
reduce(x, drop.empty.ranges=FALSE, ...)
## S4 method for signature 'IntegerRanges'
reduce(x, drop.empty.ranges=FALSE, min.gapwidth=1L,
with.revmap=FALSE, with.inframe.attrib=FALSE)
## S4 method for signature 'Views'
reduce(x, drop.empty.ranges=FALSE, min.gapwidth=1L,
with.revmap=FALSE, with.inframe.attrib=FALSE)
## S4 method for signature 'IntegerRangesList'
reduce(x, drop.empty.ranges=FALSE, min.gapwidth=1L,
with.revmap=FALSE, with.inframe.attrib=FALSE)
## gaps()
## ------
gaps(x, start=NA, end=NA)
## disjoin(), isDisjoint(), and disjointBins()
## -------------------------------------------
disjoin(x, ...)
## S4 method for signature 'IntegerRanges'
disjoin(x, with.revmap=FALSE)
## S4 method for signature 'IntegerRangesList'
disjoin(x, with.revmap=FALSE)
isDisjoint(x, ...)
disjointBins(x, ...)x |
A IntegerRanges or IntegerRangesList object for A IntegerRanges, Views, or IntegerRangesList object
for |
... |
For |
na.rm |
Ignored. |
drop.empty.ranges |
|
min.gapwidth |
Ranges separated by a gap of at least |
with.revmap |
|
with.inframe.attrib |
|
start, end |
|
Unless specified otherwise, when x is a IntegerRangesList
object, any transformation described here is equivalent to applying the
transformation to each IntegerRangesList top-level element separately.
reduce first orders the ranges in x from left to right,
then merges the overlapping or adjacent ones.
range first concatenates x and the objects in ...
together. If the IRanges object resulting from this concatenation
contains at least 1 range, then range returns an IRanges
instance with a single range, from the minimum start to the maximum end
of the concatenated object.
Otherwise (i.e. if the concatenated object contains no range),
IRanges() is returned (i.e. an IRanges instance of
length 0).
When passing more than 1 IntegerRangesList object to range(),
they are first merged into a single IntegerRangesList object: by
name if all objects have names, otherwise, if they are all of the same
length, by position. Else, an exception is thrown.
gaps returns the "normal" IRanges object representing
the set of integers that remain after the set of integers represented
by x has been removed from the interval specified by the
start and end arguments.
If x is a Views object, then start=NA and
end=NA are interpreted as start=1 and
end=length(subject(x)), respectively, so, if start
and end are not specified, then gaps are extracted with respect
to the entire subject.
An IntegerRanges object x is considered to be "disjoint"
if its ranges are non-overlapping. isDisjoint tests whether the
object is "disjoint" or not.
Note that a "normal" IntegerRanges object is always "disjoint" but
the opposite is not true. See ?isNormal for more information about
normal IntegerRanges objects.
About empty ranges. isDisjoint handles empty ranges (a.k.a.
zero-width ranges) as follow: single empty range A is considered to
overlap with single range B iff it's contained in B without being on
the edge of B (in which case it would be ambiguous whether A is
contained in or adjacent to B). More precisely, single empty range A
is considered to overlap with single range B iff
start(B) < start(A) and end(A) < end(B)
Because A is an empty range it verifies end(A) = start(A) - 1
so the above is equivalent to:
start(B) < start(A) <= end(B)
and also equivalent to:
start(B) <= end(A) < end(B)
Finally, it is also equivalent to:
pcompare(A, B) == 2
See ?`IPosRanges-comparison` for the meaning of the codes
returned by the pcompare function.
disjoin returns a disjoint object, by finding the union of the
end points in x. In other words, the result consists of a range
for every interval, of maximal length, over which the set of overlapping
ranges in x is the same and at least of size 1.
disjointBins segregates x into a set of bins so that the
ranges in each bin are disjoint. Lower-indexed bins are filled first.
The method returns an integer vector indicating the bin index for each
range.
If x is an IntegerRanges object:
range, reduce, gaps, and disjoin
return an IRanges instance.
isDisjoint returns TRUE or FALSE.
disjointBins returns an integer vector parallel to
x, that is, where the i-th element corresponds to the i-th
element in x.
If x is a IntegerRangesList object:
range, reduce, gaps, and disjoin
return a IntegerRangesList object parallel to x.
isDisjoint returns a logical vector parallel to
x.
disjointBins returns an IntegerList object
parallel to x.
H. Pagès, M. Lawrence, and P. Aboyoun
intra-range-methods for intra range transformations.
The IntegerRanges, Views, IntegerRangesList, and MaskCollection classes.
The inter-range-methods man page in the GenomicRanges package for inter range transformations of genomic ranges.
setops-methods for set operations on IRanges objects.
endoapply in the S4Vectors package.
## ---------------------------------------------------------------------
## range()
## ---------------------------------------------------------------------
## On an IntegerRanges object:
x <- IRanges(start=c(-2, 6, 9, -4, 1, 0, -6, 3, 10),
width=c( 5, 0, 6, 1, 4, 3, 2, 0, 3))
range(x)
## On an IntegerRangesList object (XVector package required):
range1 <- IRanges(start=c(1, 2, 3), end=c(5, 2, 8))
range2 <- IRanges(start=c(15, 45, 20, 1), end=c(15, 100, 80, 5))
range3 <- IRanges(start=c(-2, 6, 7), width=c(8, 0, 0)) # with empty ranges
collection <- IRangesList(one=range1, range2, range3)
if (require(XVector)) {
range(collection)
}
irl1 <- IRangesList(a=IRanges(c(1, 2),c(4, 3)), b=IRanges(c(4, 6),c(10, 7)))
irl2 <- IRangesList(c=IRanges(c(0, 2),c(4, 5)), a=IRanges(c(4, 5),c(6, 7)))
range(irl1, irl2) # matched by names
names(irl2) <- NULL
range(irl1, irl2) # now by position
## ---------------------------------------------------------------------
## reduce()
## ---------------------------------------------------------------------
## On an IntegerRanges object:
reduce(x)
y <- reduce(x, with.revmap=TRUE)
mcols(y)$revmap # an IntegerList
reduce(x, drop.empty.ranges=TRUE)
y <- reduce(x, drop.empty.ranges=TRUE, with.revmap=TRUE)
mcols(y)$revmap
## Use the mapping from reduced to original ranges to split the DataFrame
## of original metadata columns by reduced range:
ir0 <- IRanges(c(11:13, 2, 7:6), width=3)
mcols(ir0) <- DataFrame(id=letters[1:6], score=1:6)
ir <- reduce(ir0, with.revmap=TRUE)
ir
revmap <- mcols(ir)$revmap
revmap
relist(mcols(ir0)[unlist(revmap), ], revmap) # a SplitDataFrameList
## On an IntegerRangesList object. These 4 are the same:
res1 <- reduce(collection)
res2 <- IRangesList(one=reduce(range1), reduce(range2), reduce(range3))
res3 <- do.call(IRangesList, lapply(collection, reduce))
res4 <- endoapply(collection, reduce)
stopifnot(identical(res2, res1))
stopifnot(identical(res3, res1))
stopifnot(identical(res4, res1))
reduce(collection, drop.empty.ranges=TRUE)
## ---------------------------------------------------------------------
## gaps()
## ---------------------------------------------------------------------
## On an IntegerRanges object:
x0 <- IRanges(start=c(-2, 6, 9, -4, 1, 0, -6, 10),
width=c( 5, 0, 6, 1, 4, 3, 2, 3))
gaps(x0)
gaps(x0, start=-6, end=20)
## On a Views object:
subject <- Rle(1:-3, 6:2)
v <- Views(subject, start=c(8, 3), end=c(14, 4))
gaps(v)
## On an IntegerRangesList object. These 4 are the same:
res1 <- gaps(collection)
res2 <- IRangesList(one=gaps(range1), gaps(range2), gaps(range3))
res3 <- do.call(IRangesList, lapply(collection, gaps))
res4 <- endoapply(collection, gaps)
stopifnot(identical(res2, res1))
stopifnot(identical(res3, res1))
stopifnot(identical(res4, res1))
## On a MaskCollection object:
mask1 <- Mask(mask.width=29, start=c(11, 25, 28), width=c(5, 2, 2))
mask2 <- Mask(mask.width=29, start=c(3, 10, 27), width=c(5, 8, 1))
mask3 <- Mask(mask.width=29, start=c(7, 12), width=c(2, 4))
mymasks <- append(append(mask1, mask2), mask3)
mymasks
gaps(mymasks)
## ---------------------------------------------------------------------
## disjoin()
## ---------------------------------------------------------------------
## On an IntegerRanges object:
ir <- IRanges(c(1, 1, 4, 10), c(6, 3, 8, 10))
disjoin(ir) # IRanges(c(1, 4, 7, 10), c(3, 6, 8, 10))
disjoin(ir, with.revmap=TRUE)
## On an IntegerRangesList object:
disjoin(collection)
disjoin(collection, with.revmap=TRUE)
## ---------------------------------------------------------------------
## isDisjoint()
## ---------------------------------------------------------------------
## On an IntegerRanges object:
isDisjoint(IRanges(c(2,5,1), c(3,7,3))) # FALSE
isDisjoint(IRanges(c(2,9,5), c(3,9,6))) # TRUE
isDisjoint(IRanges(1, 5)) # TRUE
## Handling of empty ranges:
x <- IRanges(c(11, 16, 11, -2, 11), c(15, 29, 10, 10, 10))
stopifnot(isDisjoint(x))
## Sliding an empty range along a non-empty range:
sapply(11:17,
function(i) pcompare(IRanges(i, width=0), IRanges(12, 15)))
sapply(11:17,
function(i) isDisjoint(c(IRanges(i, width=0), IRanges(12, 15))))
## On an IntegerRangesList object:
isDisjoint(collection)
## ---------------------------------------------------------------------
## disjointBins()
## ---------------------------------------------------------------------
## On an IntegerRanges object:
disjointBins(IRanges(1, 5)) # 1L
disjointBins(IRanges(c(3, 1, 10), c(5, 12, 13))) # c(2L, 1L, 2L)
## On an IntegerRangesList object:
disjointBins(collection)Please choose more modern alternatives, such as Google Chrome or Mozilla Firefox.