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`).
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()
## -------
"range"(x, ..., na.rm=FALSE)
"range"(x, ..., na.rm=FALSE)
## reduce()
## --------
reduce(x, ...)
"reduce"(x, drop.empty.ranges=FALSE, min.gapwidth=1L, with.revmap=FALSE, with.inframe.attrib=FALSE)
"reduce"(x, drop.empty.ranges=FALSE, min.gapwidth=1L, with.revmap=FALSE, with.inframe.attrib=FALSE)
"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, ...)
isDisjoint(x, ...)
disjointBins(x, ...)range,
disjoin, isDisjoint, and disjointBins. A Ranges, Views, or RangesList object for
reduce and gaps.
range, additional Ranges or RangesList
object to consider.
TRUE or FALSE. Should empty ranges be dropped?
min.gapwidth positions
are not merged.
TRUE or FALSE. Should the mapping from reduced to original
ranges be stored in the returned object? If yes, then it is stored as
metadata column "revmap" of type IntegerList.
TRUE or FALSE. For internal use.
x is a Ranges or Views object:
A single integer or NA. Use these arguments to specify
the interval of reference i.e. which interval the returned gaps
should be relative to.
x is a RangesList object:
Integer vectors containing the coordinate bounds for each
RangesList top-level element.
x is a Ranges 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.
x is a Views object: reduce and gaps
return a Views object on the same subject as x but with
modified views.If x is a RangesList object:
range, reduce, gaps, and disjoin
return a RangesList object parallel to x.
isDisjoint returns a logical vector parallel to
x.
disjointBins returns an IntegerList object
parallel to x.
x is a RangesList object,
any transformation described here is equivalent to applying the
transformation to each RangesList top-level element separately.reduce
reduce first orders the ranges in x from left to right,
then merges the overlapping or adjacent ones.
range
range first combines x and the arguments in ....
If the combined IRanges object 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 combined object.
Otherwise (i.e. if the combined object contains no range),
IRanges() is returned (i.e. an IRanges instance of
length 0).
When passing more than 1 RangesList object to range(),
they are first merged into a single RangesList object: by name
if all objects have names, otherwise, if they are all of the same
length, by position. Else, an exception is thrown.
If x is a RangedData object, then range returns
a RangesList object resulting from calling range(ranges(x)),
i.e. the bounds of the ranges in each space.
gaps
gaps returns the "normal" Ranges 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.
isDisjoint
A Ranges 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" Ranges object is always "disjoint" but the
opposite is not true. See ?isNormal for more information about
normal Ranges 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)<="" pre="">
and also equivalent to:
start(B) <= end(a)="" <="" end(b)<="" pre="">
Finally, it is also equivalent to:
pcompare(A, B) == 2
See ?`Ranges-comparison` for the meaning of the codes
returned by the pcompare function.disjoin
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
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.
endoapply in the S4Vectors package.
## ---------------------------------------------------------------------
## range()
## ---------------------------------------------------------------------
## On a Ranges 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 a RangesList 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 a Ranges 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 a RangesList 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 a Ranges 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 a RangesList 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 a Ranges 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))
## On a RangesList object:
disjoin(collection)
## ---------------------------------------------------------------------
## isDisjoint()
## ---------------------------------------------------------------------
## On a Ranges 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 a RangesList object:
isDisjoint(collection)
## ---------------------------------------------------------------------
## disjointBins()
## ---------------------------------------------------------------------
## On a Ranges object:
disjointBins(IRanges(1, 5)) # 1L
disjointBins(IRanges(c(3, 1, 10), c(5, 12, 13))) # c(2L, 1L, 2L)
## On a RangesList object:
disjointBins(collection)
Run the code above in your browser using DataLab