inter-range-methods {IRanges} | R Documentation |
Except for disjointBins()
, all the transformations described in this
man page are endomorphisms that operate on a single "range-based"
object, that is, they transform the ranges contained in the input object
and return them in an object of the same class as the input object.
Range-based endomorphisms are grouped in 2 categories:
Intra range transformations like shift()
that
transform each range individually (and independently of the other
ranges) and return an object of the same length as the
input object.
Those transformations are described in the intra-range-methods
man page (see ?`intra-range-methods`
).
Inter range transformations like reduce()
that
transform all the ranges together as a set to produce a new set
of ranges and return an object not necessarily of the same length
as the input object.
Those transformations are described in this man page.
## range() ## ------- ## S4 method for signature 'Ranges' range(x, ..., na.rm=FALSE) ## S4 method for signature 'RangesList' range(x, ..., na.rm=FALSE) ## reduce() ## -------- reduce(x, ...) ## S4 method for signature 'Ranges' 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 'RangesList' reduce(x, drop.empty.ranges=FALSE, min.gapwidth=1L, with.revmap=FALSE, with.inframe.attrib=FALSE) ## S4 method for signature 'RangedData' reduce(x, by=character(), drop.empty.ranges=FALSE, min.gapwidth=1L, with.inframe.attrib=FALSE) ## gaps() ## ------ gaps(x, start=NA, end=NA) ## disjoin() ## --------- disjoin(x, ...) ## disjointBins() ## -------------- disjointBins(x, ...)
x |
A Ranges, Views, RangesList, MaskCollection, or RangedData object. |
... |
For |
na.rm |
Ignored. |
drop.empty.ranges |
|
min.gapwidth |
Ranges separated by a gap of at least |
with.revmap |
|
with.inframe.attrib |
|
by |
A character vector. |
start, end |
|
Here we start by describing how each transformation operates on a
Ranges object x
.
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).
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.
reduce
first orders the ranges in x
from left to right,
then merges the overlapping or adjacent ones.
If x
is a RangedData object, reduce
merges the
ranges in each of the spaces after grouping by the by
values
columns and returns the result as a RangedData
containing
the reduced ranges and the by
value columns.
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.
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.
When x
in a RangesList object, doing any of the transformation
above is equivalent to applying the transformation to each RangesList
top-level element separately.
For range
, if there are additional RangesList
objects
in ...
, they are merged into x
by name, if all objects
have names, otherwise, if they are all of the same length, by
position. Else, an exception is thrown.
H. Pages, M. Lawrence, P. Aboyoun
intra-range-methods for intra range transformations.
The Ranges, Views, RangesList, MaskCollection, and RangedData classes.
The inter-range-methods man page in the GenomicRanges package for methods that operate on GenomicRanges and other objects.
setops-methods for set operations on IRanges objects.
solveUserSEW
for the SEW (Start/End/Width)
interface.
## --------------------------------------------------------------------- ## 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 ## On a RangedData object: ranges <- IRanges(c(1,2,3),c(4,5,6)) score <- c(10L, 2L, NA) rd <- RangedData(ranges, score) range(rd) rd2 <- RangedData(IRanges(c(5,2,0), c(6,3,1))) range(rd, rd2) ## --------------------------------------------------------------------- ## 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) ## On a RangedData object: rd <- RangedData( RangesList( chrA=IRanges(start=c(1, 4, 6), width=c(3, 2, 4)), chrB=IRanges(start=c(1, 3, 6), width=c(3, 3, 4))), score=c(2, 7, 3, 1, 1, 1)) rd reduce(rd) ## --------------------------------------------------------------------- ## 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) ## --------------------------------------------------------------------- ## 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)