Learn R
IRanges (version 2.0.1)

inter-range-methods: Inter range transformations of a Ranges, Views, RangesList, MaskCollection, or RangedData object

Description

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:

  1. 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`).
  2. 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.

Usage

## 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.mapping=FALSE, with.inframe.attrib=FALSE)


"reduce"(x, drop.empty.ranges=FALSE, min.gapwidth=1L, with.revmap=FALSE, with.mapping=FALSE, with.inframe.attrib=FALSE)


"reduce"(x, drop.empty.ranges=FALSE, min.gapwidth=1L, with.revmap=FALSE, with.mapping=FALSE, with.inframe.attrib=FALSE)


"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, ...)

Arguments

x
A Ranges, Views, RangesList, MaskCollection, or RangedData object.
...
For range, additional Ranges or RangesList to consider.
na.rm
Ignored.
drop.empty.ranges
TRUE or FALSE. Should empty ranges be dropped?
min.gapwidth
Ranges separated by a gap of at least min.gapwidth positions are not merged.
with.revmap
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.
with.mapping
Defunct. Please use the with.revmap argument instead.
with.inframe.attrib
TRUE or FALSE. For internal use.
by
A character vector.
start, end
  • If 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.
  • If x is a RangesList object: Integer vectors containing the coordinate bounds for each RangesList top-level element.

Details

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.

See Also

Examples

Run this code
## ---------------------------------------------------------------------
## 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)

Run the code above in your browser using DataCamp Workspace