IRanges-setops            package:IRanges            R Documentation

Set operations on IRanges objects

Description:

     Performs set operations on IRanges objects.

Usage:

       ## Vector-wise operations:
       gaps(x, start=NA, end=NA)
       ## S4 method for signature 'IRanges, IRanges':
       union(x, y)
       ## S4 method for signature 'IRanges, IRanges':
       intersect(x, y)
       ## S4 method for signature 'IRanges, IRanges':
       setdiff(x, y)

       ## Element-wise (aka "parallel") operations:
       ## S4 method for signature 'IRanges, IRanges':
       punion(x, y, fill.gap=FALSE, ...)
       ## S4 method for signature 'IRanges, IRanges':
       pintersect(x, y, resolve.empty=c("none", "max.start", "start.x"), ...)
       ## S4 method for signature 'IRanges, IRanges':
       psetdiff(x, y, ...)
       ## S4 method for signature 'IRanges, IRanges':
       pgap(x, y, ...)

Arguments:

    x, y: IRanges objects. 

start, end: 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. 

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:

     'gaps' returns the "normal" IRanges object (of the same class as
     'x') 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.

     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.

Author(s):

     H. Pages 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.

     union, intersect, setdiff, Ranges-class, Ranges-utils,
     IRanges-class, IRanges-utils

Examples:

       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)  # Regions of the -6:20 range that are not masked by 'x0'.

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

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

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

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

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

