IRanges (version 2.0.1)

setops-methods: Set operations on IRanges, RangesList, and Hits objects

Description

Performs set operations on IRanges objects.

Usage

## Vector-wise operations:
"union"(x, y,...)
"intersect"(x, y,...)
"setdiff"(x, y,...)
## Element-wise (aka "parallel") operations:
"punion"(x, y, fill.gap=FALSE, ...)
"pintersect"(x, y, resolve.empty=c("none", "max.start", "start.x"), ...)
"psetdiff"(x, y, ...)
"pgap"(x, y, ...)

Arguments

x, y

IRanges objects.

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

...

Further arguments to be passed to or from other methods.

Details

The union, intersect and setdiff methods for IRanges objects return a "normal" IRanges object (of the same class as x) 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 IRanges objects are defined. For these methods, x and y must have the same length (i.e. same number of ranges) and they return an IRanges instance of the same length as x and y where each range represents the union/intersection/difference/gap of/between the corresponding ranges in x and y.

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.

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.

union,

Ranges-class,

intra-range-methods for intra range transformations,

inter-range-methods for inter range transformations,

IRanges-class, IRanges-utils

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)