inter-range-methods: Inter range transformations of an IntegerRanges, Views,...

In IRanges: Foundation of integer range manipulation in Bioconductor

Description

Range-based transformations are grouped in 2 categories:

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

2. 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.

Usage

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

Arguments

x	A IntegerRanges or IntegerRangesList object for range, disjoin, isDisjoint, and disjointBins. A IntegerRanges, Views, or IntegerRangesList object for reduce and gaps.
...	For range, additional IntegerRanges or IntegerRangesList object 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 output to input ranges be stored in the returned object? If yes, then it is stored as metadata column revmap of type IntegerList.
with.inframe.attrib	TRUE or FALSE. For internal use.
start, end	If x is a IntegerRanges 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 IntegerRangesList object: Integer vectors containing the coordinate bounds for each IntegerRangesList top-level element.

Details

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

reduce first orders the ranges in x from left to right, then merges the overlapping or adjacent ones.

range

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

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.

isDisjoint

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

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.

Value

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 Views object: reduce and gaps return a Views object on the same subject as x but with modified views.

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.

Author(s)

H. Pagès, M. Lawrence, and P. Aboyoun

See Also

• 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.

Examples

## ---------------------------------------------------------------------
## 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)

IRanges documentation built on Dec. 14, 2020, 2 a.m.