Ranges-utils             package:IRanges             R Documentation

Ranges utility functions

Description:

     Utility functions for modifying Ranges objects.

Usage:

     flank(x, width, start=TRUE, both=FALSE, use.names=TRUE)
     narrow(x, start=NA, end=NA, width=NA, use.names=TRUE)
     reflect(x, bounds, use.names=TRUE)
     resize(x, width, fix="start", use.names=TRUE, ...)
     restrict(x, start=NA, end=NA, keep.all.ranges=FALSE, use.names=TRUE)
     shift(x, shift, use.names=TRUE)

     ## S4 method for signature 'Ranges':
     range(x, ..., na.rm = FALSE)
     ## S4 method for signature 'Ranges':
     reduce(x, drop.empty.ranges=FALSE, min.gapwidth=1L,
            with.inframe.attrib=FALSE)

     threebands(x, start=NA, end=NA, width=NA)

Arguments:

       x: An Ranges object. 

   width: For 'narrow' and 'threebands', a vector of integers,
          eventually with NAs. See the SEW (Start/End/Width) interface
          for the details ('?solveUserSEW').

          For 'resize' and 'flank', the width of the resized or
          flanking regions. Note that if 'both' is 'TRUE', this is
          effectively doubled. Recycled as necessary so that each
          element corresponds to a range in 'x'. 

start, end: A single integer or 'NA' for all functions except 'narrow',
          'threebands', and 'flank'.

          For 'narrow' and 'threebands', the supplied 'start' and 'end'
          arguments must be vectors of integers, eventually with NAs,
          that contain coordinates relative to the current ranges. See
          the Details section below.

          For 'flank', 'start' is a logical 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'. 

    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? 

  bounds: An IRanges object to serve as the reference bounds for the
          reflection, see below. 

     fix: For 'resize', a character vector or character Rle of length 1
          or 'length(x)' 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 IRanges object. 

   shift: A single integer. 

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 'Ranges' to consider. 

   na.rm: Ignored

Details:

     'flank' generates flanking ranges for each range in 'x'. If
     'start' is 'TRUE' for a given range, the flanking occurs at the
     start, otherwise the end. The widths of the flanks are given by
     the 'width' parameter. The widths can be negative, in which case
     the flanking region is reversed so that it represents a prefix or
     suffix of the range in 'x'. The 'flank' operation is illustrated
     below for a call of the form 'flank(x, 3, TRUE)', where 'x'
     indicates a range in 'x' and '-' indicates the resulting flanking
     region:


         ---xxxxxxx

     If 'start' were 'FALSE':


            xxxxxxx---

     For negative width, i.e. 'flank(x, -3, FALSE)', where '*'
     indicates the overlap between 'x' and the result:


            xxxx***

     If 'both' is 'TRUE', then, for all ranges in 'x', the flanking
     regions are extended _into_ (or out of, if width is negative) the
     range, so that the result straddles the given endpoint and has
     twice the width given by 'width'. This is illustrated below for
     'flank(x, 3, both=TRUE)':


         ---***xxxx

     'narrow' narrows the ranges in 'x' i.e. each range in the returned
     Ranges object is a subrange of the corresponding range in 'x'. The
     supplied start/end/width values are solved by a call to
     'solveUserSEW(width(x), start=start, end=end, width=width)' and
     therefore must be compliant with the rules of the SEW
     (Start/End/Width) interface (see '?solveUserSEW' for the details).
     Then each subrange is derived from the original range according to
     the solved start/end/width values for this range. Note that those
     solved values are interpreted relatively to the original range.

     'reflect' "reflects" or reverses each range in 'x' relative to the
     corresponding range in 'bounds', which is recycled as necessary.
     Reflection preserves the width of a range, but shifts it such the
     distance from the left bound to the start of the range becomes the
     distance from the end of the range to the right bound. This is
     illustrated below, where 'x' represents a range in 'x' and '[' and
     ']' indicate the bounds:


         [..xxx.....]
         becomes
         [.....xxx..]

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

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

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

     'range' returns an 'IRanges' instance with a single range, from
     the minimum start to the maximum end in the combined ranges of 'x'
     and the arguments in '...'.

     'reduce' first orders the ranges in 'x' from left to right, then
     merges the overlapping or adjacent ones.

     'threebands' extends the capability of 'narrow' by returning the 3
     ranges objects associated to the narrowing operation. The returned
     value 'y' is a list of 3 ranges objects named '"left"', '"middle"'
     and '"right"'. The middle component is obtained by calling
     'narrow' with the same arguments (except that names are dropped).
     The left and right components are also instances of the same class
     as 'x' and they contain what has been removed on the left and
     right sides (respectively) of the original ranges during the
     narrowing.

     Note that original object 'x' can be reconstructed from the left
     and right bands with 'punion(y$left, y$right, fill.gap=TRUE)'.

Author(s):

     H. Pages, M. Lawrence, P. Aboyoun

See Also:

     'threebands' could be described as a parallel variant of
     'disjoin'.

     Ranges-class, IRanges-setops, 'solveUserSEW'

Examples:

       vec <- as.integer(c(19, 5, 0, 8, 5))
       x <- successiveIRanges(vec)
       x

       shift(x, -3)

       restrict(x, start=12, end=34)
       restrict(x, start=20)
       restrict(x, start=21)
       restrict(x, start=21, keep.all.ranges=TRUE)

       y <- x[width(x) != 0]
       narrow(y, start=4, end=-2)
       narrow(y, start=-4, end=-2)
       narrow(y, end=5, width=3)
       narrow(y, start = c(3, 4, 2, 3), end = c(12, 5, 7, 4))

       resize(y, width = 200)
       resize(y, width = 2, fix = "end")

       z <- threebands(y, start=4, end=-2)
       y0 <- punion(z$left, z$right, fill.gap=TRUE)
       identical(y, y0)  # TRUE
       threebands(y, start=-5)

       x <- IRanges(start=c(-2, 6, 9, -4, 1, 0, -6, 3, 10),
                    width=c( 5, 0, 6,  1, 4, 3,  2, 0,  3))
       reduce(x)
       reduce(x, drop.empty.ranges=TRUE)

       ir1 <- IRanges(c(2,5,1), c(3,7,3))

       bounds <- IRanges(c(0, 5, 3), c(10, 6, 9))
       reflect(ir1, bounds)

       flank(ir1, 2)
       flank(ir1, 2, FALSE)
       flank(ir1, 2, c(FALSE, TRUE, FALSE))
       flank(ir1, c(2, -2, 2))
       flank(ir1, 2, both = TRUE)
       flank(ir1, 2, FALSE, TRUE)
       flank(ir1, -2, FALSE, TRUE)

