Set operations on Ranges and RangesList objects

Description

Performs set operations on Ranges and RangesList objects.

Usage

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

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

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

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

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

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

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

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

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

Arguments

Details

The union, intersect and setdiff methods for Ranges objects return a "normal" Ranges 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 Ranges objects are defined. For these methods, x and y must have the same length (i.e. same number of ranges). They return a Ranges object parallel to x and y i.e. where the i-th range corresponds to the i-th range in x and iny) 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 Ranges objects, union, intersect, and setdiff return an IRanges instance that is guaranteed to be normal (see isNormal) but is NOT promoted to NormalIRanges.

On Ranges 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.

• Ranges and RangesList objects. In particular, normality of a Ranges object is discussed in the man page for Ranges 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 RangesList 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)