RangesList-utils           package:IRanges           R Documentation

RangesList utility functions

Description:

     Utility functions for manipulating 'RangesList' objects.

Usage:

     # Intra-interval operations
     ## S4 method for signature 'RangesList':
     flank(x, width, start=TRUE, both=FALSE, use.names=TRUE)
     ## S4 method for signature 'RangesList':
     narrow(x, start=NA, end=NA, width=NA, use.names=TRUE)
     ## S4 method for signature 'RangesList':
     resize(x, width, fix="start", use.names=TRUE)
     ## S4 method for signature 'RangesList':
     restrict(x, start=NA, end=NA, keep.all.ranges=FALSE, use.names=TRUE)
     ## S4 method for signature 'RangesList':
     shift(x, shift, use.names=TRUE)

     # Inter-interval operations
     ## S4 method for signature 'RangesList':
     disjoin(x)
     ## S4 method for signature 'RangesList':
     gaps(x, start=NA, end=NA)
     ## S4 method for signature 'RangesList':
     range(x, ..., na.rm = FALSE)
     ## S4 method for signature 'RangesList':
     reduce(x, drop.empty.ranges=FALSE, min.gapwidth=1L,
                                   with.inframe.attrib=FALSE)

     # Set operations
     ## S4 method for signature 'RangesList, RangesList':
     union(x, y)
     ## S4 method for signature 'RangesList, RangesList':
     intersect(x, y)
     ## S4 method for signature 'RangesList, RangesList':
     setdiff(x, y)

Arguments:

    x, y: A 'RangesList'

start, end: For 'flank', 'start' must be either a logical vector or a
          LogicalList object indicating whether 'x' should be flanked
          at the start ('TRUE') or the end ('FALSE'). Recycled as
          necessary so that each element corresponds to a range in 'x'.

          For 'narrow', 'start' and 'end' must be either an integer
          vector or a IntegerList object containing coordinates
          relative to the current ranges.

          For 'restrict', 'start' and 'end' must be either a single
          integer or 'NA'.

          For 'gaps', 'start' and 'end' must be an integer vector
          containing the coordinate bounds for each RangesList element. 

   width: For 'flank' and 'resize', either an integer vector or an
          IntegerList object containing the width of the flanking or
          resized regions. Recycled as necessary so that each element
          corresponds to a range in 'x'. (Note for 'flank': if 'both'
          is 'TRUE', this is effectively doubled.) 

          For 'narrow', either an integer vector or a IntegerList
          object containing the widths to narrow to. See the SEW
          (Start/End/Width) interface for the details
          ('?solveUserSEW'). 

    both: If 'TRUE', extends the flanking region 'width' positions
          _into_ the range. The resulting range thus straddles the end
          point, with 'width' positions on either side. 

use.names: 'TRUE' or 'FALSE'. Should names be preserved? 

     fix: For 'resize', a character vector of length 1, a CharacterList
          object, or a 'character' RleList object containing the values
          '"start"', '"end"', and '"center"' denoting what to use as an
          anchor for each element in 'x'. 

keep.all.ranges: 'TRUE' or 'FALSE'. Should ranges that don't overlap
          with the interval specified by 'start' and 'end' be kept?
          Note that "don't overlap" means that they end strictly before
          'start - 1' or start strictly after 'end + 1'. Ranges that
          end at 'start - 1' or start at 'end + 1' are always kept and
          their width is set to zero in the returned RangesList object. 

   shift: Either an integer vector or a IntegerList object containing
          the shift information. Recycled as necessary so that each
          element corresponds to a range in 'x'. 

drop.empty.ranges: 'TRUE' or 'FALSE'. Should empty ranges be dropped? 

min.gapwidth: Ranges separated by a gap of at least 'min.gapwidth'
          positions won't be merged in the Ranges object returned by
          'reduce'. Otherwise, they will. 

with.inframe.attrib: 'TRUE' or 'FALSE'. For internal use. 

     ...: For 'range', additional 'RangesList' to consider. 

   na.rm: Ignored

Details:

     The 'flank' method generates flanking ranges for each range in
     'x'.

     The 'narrow' method narrows the ranges in 'x' i.e. each range in
     the returned RangesList object is a subrange of the corresponding
     range in 'x'.

     The 'resize' method resizes the ranges to the specified width
     where either the start or end is used as an anchor.

     The 'restrict' method restricts the ranges in 'x' to the interval
     specified by the 'start' and 'end' arguments.

     The 'shift' method shifts all the ranges in 'x'.

     The 'disjoin' method returns disjoint ranges by finding the 
     within element union of the end points of 'x'.

     The 'gaps' method takes the complement (via 'gaps') of each
     element in the list and returns the result as a 'RangesList'.

     'range' finds the 'range', i.e. a 'Ranges' with one range, from
     the minimum start to the maximum end, on each element in 'x' and
     returns the result as a 'RangesList'. If there are additional
     'RangesList' objects in '...', they are merged into 'x' by name,
     if all objects have names, otherwise, if they are all of the same
     length, by position. Else, an exception is thrown.

     The 'reduce' method merges (via 'reduce') each of the elements in
     the list and returns the result as a 'RangesList'.

     The 'union' method performs elementwise 'union' operations for two
     'RangesList' objects.

     The 'intersect' method performs elementwise 'intersect' operations
     for two 'RangesList' objects.

     The 'setdiff' method performs elementwise 'setdiff' operations for
     two 'RangesList' objects.

Value:

     A 'RangesList' object. For 'flank', 'narrow', 'resize',
     'restrict', and 'shift', the length is the same as that of 'x'.

Author(s):

     Michael Lawrence, H. Pages, P. Aboyoun

See Also:

     'RangesList', 'Ranges-utils'

Examples:

       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 <- RangesList(one = range1, range2, range3)

       shift(collection, shift=5)
       restrict(collection, start=2, end=8)
       resize(collection, width=200)
       flank(collection, width=10)
       disjoin(collection)

       # these three are the same
       reduce(collection)
       RangesList(one = reduce(range1), reduce(range2), reduce(range3))
       do.call(RangesList, lapply(collection, reduce))

       # drop empty ranges
       reduce(collection, drop.empty.ranges=TRUE)

       # these three are the same
       gaps(collection)
       RangesList(one = gaps(range1), gaps(range2), gaps(range3))
       do.call(RangesList, lapply(collection, gaps))

       # 'range'
       rl <- RangesList(a = IRanges(c(1,2),c(4,3)), b = IRanges(c(4,6),c(10,7)))
       rl2 <- RangesList(c = IRanges(c(0,2),c(4,5)), a = IRanges(c(4,5),c(6,7)))
       range(rl, rl2) # matched by names
       names(rl2) <- NULL
       range(rl, rl2) # now by position

       # set operations
       union(rl, rl2)
       intersect(rl, rl2)
       setdiff(rl, rl2)

