IRanges-class            package:IRanges            R Documentation

_I_R_a_n_g_e_s _a_n_d _N_o_r_m_a_l_I_R_a_n_g_e_s _o_b_j_e_c_t_s

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

     The IRanges class is a simple implementation of the Ranges
     container where 2 integer vectors of the same length are used to
     store the start and width values. See the Ranges virtual class for
     a formal definition of Ranges objects and for their methods (all
     of them should work for IRanges objects).

     Some subclasses of the IRanges class are: NormalIRanges, Views,
     etc...

     A NormalIRanges object is just an IRanges object that is
     guaranteed to be "normal". See the Normality section in the man
     page for Ranges objects for the definition and properties of
     "normal" Ranges objects.

_C_o_n_s_t_r_u_c_t_o_r:


      'IRanges(start=NULL, end=NULL, width=NULL, names=NULL)': Return
          the IRanges object containing the ranges specified by
          'start', 'end' and 'width'. Input falls into one of two
          categories:

          _C_a_t_e_g_o_r_y _1 'start', 'end' and 'width' are numeric vectors (or
               NULLs). If necessary they are expanded cyclically to the
               length of the longest (NULL arguments are filled with
               NAs). After this expansion, each row in the 3-column
               matrix obtained by binding those 3 vectors together is
               "solved" i.e. NAs are treated as unknown in the equation
               'end = start + width - 1'. Finally, the solved matrix is
               returned as an IRanges instance.

          _C_a_t_e_g_o_r_y _2 The 'start' argument is a logical vector or
               logical Rle object and 'IRanges(start)' produces the
               same result as 'as(start, "IRanges")'. Note that, in
               that case, the returned IRanges instance is guaranteed
               to be normal.

          Note that the 'names' argument is never recycled (to remain
          consistent with what '`names<-`' does on standard vectors).


_M_e_t_h_o_d_s _f_o_r _N_o_r_m_a_l_I_R_a_n_g_e_s _o_b_j_e_c_t_s:


      'max(x)': The maximum value in the finite set of integers
          represented by 'x'.

      'min(x)': The minimum value in the finite set of integers
          represented by 'x'.


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

     H. Pages

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

     Ranges-class, IRanges-utils, IRanges-setops.

     Some direct subclasses of the IRanges class (other than
     NormalIRanges): Views-class.

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

       showClass("IRanges")  # shows (some of) the known subclasses

       ## ---------------------------------------------------------------------
       ## A. USING THE IRanges() CONSTRUCTOR
       ## ---------------------------------------------------------------------
       IRanges(start=11, end=rep.int(20, 5))
       IRanges(start=11, width=rep.int(20, 5))
       IRanges(-2, 20)  # only one range
       IRanges(start=c(2, 0, NA), end=c(NA, NA, 14), width=11:0)
       IRanges()  # IRanges instance of length zero
       IRanges(names=character())

       ## With logical input:
       x <- IRanges(c(FALSE, TRUE, TRUE, FALSE, TRUE))  # logical vector input
       isNormal(x)  # TRUE
       x <- IRanges(Rle(1:30) %% 5 <= 2)  # logical Rle input
       isNormal(x)  # TRUE

       ## ---------------------------------------------------------------------
       ## B. MANIPULATING IRanges OBJECTS
       ## ---------------------------------------------------------------------
       ## All the methods defined for Ranges objects work on IRanges objects.
       ## See ?Ranges for some examples.
       ## Also see ?`IRanges-utils` and ?`IRanges-setops` for additional
       ## operations on IRanges objects.

       ## ---------------------------------------------------------------------
       ## C. A NOTE ABOUT PERFORMANCE
       ## ---------------------------------------------------------------------
       ## Using an IRanges object for storing a big set of ranges is more
       ## efficient than using a standard R data frame:
       N <- 2000000L  # nb of ranges
       W <- 180L      # width of each range
       start <- 1L
       end <- 50000000L
       set.seed(777)
       range_starts <- sort(sample(end-W+1L, N))
       range_widths <- rep.int(W, N)
       ## Instantiation is faster
       system.time(x <- IRanges(start=range_starts, width=range_widths))
       system.time(y <- data.frame(start=range_starts, width=range_widths))
       ## Subsetting is faster
       system.time(x16 <- x[c(TRUE, rep.int(FALSE, 15))])
       system.time(y16 <- y[c(TRUE, rep.int(FALSE, 15)), ])
       ## Internal representation is more compact
       object.size(x16)
       object.size(y16)

