inter-range-methods {IRanges} | R Documentation

## Inter range transformations of an IntegerRanges, Views, IntegerRangesList, or MaskCollection object

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

[Package IRanges version 2.22.2 Index]