IRanges-utils            package:IRanges            R Documentation

IRanges utility functions

Description:

     Utility functions for creating or modifying IRanges objects.

Usage:

     ## Create an IRanges instance:
     successiveIRanges(width, gapwidth=0, from=1)

     ## Turn a logical vector into a set of ranges:
     whichAsIRanges(x)

     ## Coercion:
     asNormalIRanges(x, force=TRUE)

Arguments:

   width: A vector of non-negative integers (with no NAs) specifying
          the widths of the ranges to create. 

gapwidth: A single integer or an integer vector with one less element
          than the 'width' vector specifying the widths of the gaps
          separating one range from the next one. 

    from: A single integer specifying the starting position of the
          first range. 

       x: A logical vector for 'whichAsIRanges'. An IRanges object for
          'asNormalIRanges'. 

   force: 'TRUE' or 'FALSE'. Should 'x' be turned into a NormalIRanges
          object even if 'isNormal(x)' is 'FALSE'? 

Details:

     'successiveIRanges' returns an IRanges instance containing the
     ranges that have the widths specified in the 'width' vector and
     are separated by the gaps specified in 'gapwidth'. The first range
     starts at position 'from'. When 'gapwidth=0' and 'from=1' (the
     defaults), the returned IRanges can be seen as a partitioning of
     the 1:sum(width) interval. See '?Partitioning' for more details on
     this.

     'whichAsIRanges' returns an IRanges instance containing all of the
     ranges where 'x' is 'TRUE'.

     If 'force=TRUE' (the default), then 'asNormalIRanges' will turn
     'x' into a NormalIRanges instance by reordering and reducing the
     set of ranges if necessary (i.e. only if 'isNormal(x)' is 'FALSE',
     otherwise the set of ranges will be untouched). If 'force=FALSE',
     then 'asNormalIRanges' will turn 'x' into a NormalIRanges instance
     only if 'isNormal(x)' is 'TRUE', otherwise it will raise an error.
     Note that when 'force=FALSE', the returned object is guaranteed to
     contain exactly the same set of ranges than 'x'. 'as(x,
     "NormalIRanges")' is equivalent to 'asNormalIRanges(x,
     force=TRUE)'.

Author(s):

     H. Pages

See Also:

     Ranges-class, Ranges-utils, IRanges-class, IRanges-setops,
     'solveUserSEW', 'successiveViews'

Examples:

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

       asNormalIRanges(x)   # 3 ranges ordered from left to right and separated by
                            # gaps of width >= 1.

       ## More on normality:
       example(`IRanges-class`)
       isNormal(x16)                        # FALSE
       if (interactive())
           x16 <- asNormalIRanges(x16)      # Error!
       whichFirstNotNormal(x16)             # 57
       isNormal(x16[1:56])                  # TRUE
       xx <- asNormalIRanges(x16[1:56])
       class(xx)
       max(xx)
       min(xx)

