IRanges-utils            package:IRanges            R Documentation

_I_R_a_n_g_e_s _u_t_i_l_i_t_y _f_u_n_c_t_i_o_n_s

_D_e_s_c_r_i_p_t_i_o_n:

     Utility functions for creating or modifying IRanges objects.

_U_s_a_g_e:

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

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

       ## Modify an IRanges object (endomorphisms):
       shift(x, shift, use.names=TRUE)
       restrict(x, start=NA, end=NA, keep.all.ranges=FALSE, use.names=TRUE)
       narrow(x, start=NA, end=NA, width=NA, use.names=TRUE)
       reduce(x, with.inframe.attrib=FALSE)
       gaps(x, start=NA, end=NA)

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

_A_r_g_u_m_e_n_t_s:

   width: For 'successiveIRanges', must be a vector of non-negative
          integers (with no NAs) specifying the widths of the ranges to
          create.

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

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 'shift', 'restrict', 'narrow',
          'reduce', 'gaps' and 'asNormalIRanges'. 

   shift: A single integer. 

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

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

          For 'narrow', 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. 

keep.all.ranges: 'TRUE' or 'FALSE'. Should ranges that become "out of
          limits" after restriction be kept? 

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

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

_D_e_t_a_i_l_s:

     'successiveIRanges' returns an IRanges object containing the
     ranges on 'subject' 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'.

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

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

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

     'narrow' narrows the ranges in 'x' i.e. each range in the returned
     IRanges 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.

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

     'gaps' returns the normal IRanges object describing the set of
     integers obtained by removing the set of integers described by 'x'
     from the interval specified by the 'start' and 'end' arguments.

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

_A_u_t_h_o_r(_s):

     H. Pages

_S_e_e _A_l_s_o:

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

_E_x_a_m_p_l_e_s:

       vec <- as.integer(c(19, 5, 0, 8, 5))
       whichAsIRanges(vec >= 5)
       x <- successiveIRanges(vec)
       x
       shift(x, -3)
       restrict(x, start=12, end=34)
       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))

       x <- IRanges(start=c(-2L, 6L, 9L, -4L, 1L, 0L, -6L, 10L),
                    width=c( 5L, 0L, 6L,  1L, 4L, 3L,  2L,  3L))
       reduce(x)
       gaps(x)
       gaps(x, start=-6, end=20)  # Regions of the -6:20 range that are not masked by '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)

