setops-methods {IRanges} | R Documentation

## Set operations on IntegerRanges and IntegerRangesList objects

### Description

Performs set operations on IntegerRanges and IntegerRangesList objects.

### Usage

    ## Vector-wise set operations
    ## --------------------------

    ## S4 method for signature 'IntegerRanges,IntegerRanges'
    union(x, y)
    ## S4 method for signature 'Pairs,missing'
    union(x, y, ...)

    ## S4 method for signature 'IntegerRanges,IntegerRanges'
    intersect(x, y)
    ## S4 method for signature 'Pairs,missing'
    intersect(x, y, ...)

    ## S4 method for signature 'IntegerRanges,IntegerRanges'
    setdiff(x, y)
    ## S4 method for signature 'Pairs,missing'
    setdiff(x, y, ...)

    ## Element-wise (aka "parallel") set operations
    ## --------------------------------------------

    ## S4 method for signature 'IntegerRanges,IntegerRanges'
    punion(x, y, fill.gap=FALSE)
    ## S4 method for signature 'Pairs,missing'
    punion(x, y, ...)

    ## S4 method for signature 'IntegerRanges,IntegerRanges'
    pintersect(x, y, resolve.empty=c("none", "max.start", "start.x"))
    ## S4 method for signature 'Pairs,missing'
    pintersect(x, y, ...)

    ## S4 method for signature 'IntegerRanges,IntegerRanges'
    psetdiff(x, y)
    ## S4 method for signature 'Pairs,missing'
    psetdiff(x, y, ...)

    ## S4 method for signature 'IntegerRanges,IntegerRanges'
    pgap(x, y)

### Arguments

`x, y` | Objects representing ranges.
`fill.gap` | Logical indicating whether or not to force a union by using the rule `start = min(start(x), start(y)), end = max(end(x), end(y))`.
`resolve.empty` | One of `"none"`, `"max.start"`, or `"start.x"` denoting how to handle ambiguous empty ranges formed by intersections. `"none"` - throw an error if an ambiguous empty range is formed, `"max.start"` - associate the maximum start value with any ambiguous empty range, and `"start.x"` - associate the start value of `x` with any ambiguous empty range. (See Details section below for the definition of an ambiguous range.)
`...` | The methods for Pairs objects pass any extra argument to the internal call to `punion(first(x), last(x), ...)`, `pintersect(first(x), last(x), ...)`, etc...

### Details

The `union`, `intersect` and `setdiff` methods for IntegerRanges objects return a "normal" IntegerRanges object representing the union, intersection and (asymmetric!) difference of the sets of integers represented by `x` and `y`.

`punion`, `pintersect`, `psetdiff` and `pgap` are generic functions that compute the element-wise (aka "parallel") union, intersection, (asymmetric!) difference and gap between each element in `x` and its corresponding element in `y`. Methods for IntegerRanges objects are defined. For these methods, `x` and `y` must have the same length (i.e. same number of ranges). They return a IntegerRanges object parallel to `x` and `y` i.e. where the i-th range corresponds to the i-th range in `x` and in`y`) and represents the union/intersection/difference/gap of/between the corresponding `x[i]` and `y[i]`.

If `x` is a `Pairs` object, then `y` should be missing, and the operation is performed between the members of each pair.

By default, `pintersect` will throw an error when an "ambiguous empty range" is formed. An ambiguous empty range can occur three different ways: 1) when corresponding non-empty ranges elements `x` and `y` have an empty intersection, 2) if the position of an empty range element does not fall within the corresponding limits of a non-empty range element, or 3) if two corresponding empty range elements do not have the same position. For example if empty range element [22,21] is intersected with non-empty range element [1,10], an error will be produced; but if it is intersected with the range [22,28], it will produce [22,21]. As mentioned in the Arguments section above, this behavior can be changed using the `resolve.empty` argument.

### Value

On IntegerRanges objects, `union`, `intersect`, and `setdiff` return an IRanges instance that is guaranteed to be normal (see `isNormal`) but is NOT promoted to NormalIRanges.

On IntegerRanges objects, `punion`, `pintersect`, `psetdiff`, and `pgap` return an object of the same class and length as their first argument.

### Author(s)

H. Pagès and M. Lawrence

### See Also

- `pintersect` is similar to `narrow`, except the end points are absolute, not relative. `pintersect` is also similar to `restrict`, except ranges outside of the restriction become empty and are not discarded.

- setops-methods in the GenomicRanges package for set operations on genomic ranges.

- findOverlaps-methods for finding/counting overlapping ranges.

- intra-range-methods and inter-range-methods for intra range and inter range transformations.

- IntegerRanges and IntegerRangesList objects. In particular, normality of an IntegerRanges object is discussed in the man page for IntegerRanges objects.

- `mendoapply` in the S4Vectors package.

### Examples

    x <- IRanges(c(1, 5, -2, 0, 14), c(10, 9, 3, 11, 17))
    subject <- Rle(1:-3, 6:2)
    y <- Views(subject, start=c(14, 0, -5, 6, 18), end=c(20, 2, 2, 8, 20))

    ## Vector-wise operations:
    union(x, ranges(y))
    union(ranges(y), x)

    intersect(x, ranges(y))
    intersect(ranges(y), x)

    setdiff(x, ranges(y))
    setdiff(ranges(y), x)

    ## Element-wise (aka "parallel") operations:
    try(punion(x, ranges(y)))
    punion(x[3:5], ranges(y)[3:5])
    punion(x, ranges(y), fill.gap=TRUE)
    try(pintersect(x, ranges(y)))
    pintersect(x[3:4], ranges(y)[3:4])
    pintersect(x, ranges(y), resolve.empty="max.start")
    psetdiff(ranges(y), x)
    try(psetdiff(x, ranges(y)))
    start(x)[4] <- -99
    end(y)[4] <- 99
    psetdiff(x, ranges(y))
    pgap(x, ranges(y))

    ## On IntegerRangesList objects:
    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)))
    union(irl1, irl2)
    intersect(irl1, irl2)
    setdiff(irl1, irl2)

[Package IRanges version 2.24.1 Index]