IRanges-utils           package:Biostrings           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 object
       intToRanges(x, use.names=TRUE)
       intToAdjacentRanges(x, use.names=TRUE)
       toNormalIRanges(x)

       ## Modify an IRanges object
       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)

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

       x: A vector of integers for 'intToRanges' and
          'intToAdjacentRanges'. An IRanges object for 'shift',
          'restrict', 'reduce', 'toNormalIRanges' and 'gaps'. An
          IRanges object or an integer vector for 'narrow'. 

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

   shift: A single integer. 

   start: A single integer or 'NA'. 

     end: A single integer or 'NA'. 

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

   width: A single number or 'NA'. 

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

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

     'intToRanges' returns an IRanges object of the same length as 'x'
     where each integer in 'x' has been converted into the range that
     starts at 1 and ends at that integer.

     'intToAdjacentRanges' returns an IRanges object of the same length
     as 'x' where the ranges are adjacent and have the width of the
     corresponding integer in 'x'. The first range in the returned
     IRanges object starts at 1.

     'toNormalIRanges' first reduces 'x', then removes the empty
     ranges. The final result is returned as a NormalIRanges object.

     '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'.
     This subrange is determined by the 'start', 'end' and 'width'
     arguments. At least one of 'start', 'end' and 'width' must be 'NA'
     and the other ones must be single numeric values. If at least two
     of them are 'NA's, then 'start=NA' means that the starts are
     unchanged and 'end=NA' means that the ends are unchanged. A
     positive 'start' or 'end' is interpreted relatively to the start
     of the original range whereas a negative 'start' or 'end' is
     interpreted relatively to its end. Note that, if 'width' is 'NA',
     then 'start=NA' is equivalent to 'start=1' and 'end=NA' is
     equivalent to 'end=-1'. Finally, if 'width' is not 'NA', then
     'start' and 'end' cannot be both 'NA's.

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

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

     H. Pages

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

     IRanges-class, MaskCollection-class, 'reverse' 'coverage'

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

       intToRanges(c(19, 5, 0, 8, 5))
       x <- intToAdjacentRanges(c(19, 5, 0, 8, 5))
       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)

       x <- IRanges(start=c(-2L, 6L, 9L, -4L, 1L, 0L, -6L, 10L),
                    width=c( 5L, 0L, 6L,  1L, 4L, 3L,  2L,  3L))
       reduce(x)
       toNormalIRanges(x)   # 3 ranges ordered from left to right and separated by
                            # gaps of width >= 1.
       gaps(x)
       gaps(x, start=-6, end=20)  # Regions of the -6:20 range that are not masked by 'x'.

