coverage               package:IRanges               R Documentation

_C_o_v_e_r_a_g_e _a_c_r_o_s_s _a _s_e_t _o_f _r_a_n_g_e_s

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

     Counts the number of times a position is represented in a set of
     ranges.

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

       ## Old interface (IRanges < 1.1.58):
       #coverage(x, start=NA, end=NA, ...)

       ## Transitional interface (the current one):
       coverage(x, start=NA, end=NA, shift=0L, width=NULL, weight=1L, ...)

       ## New interface (in the near future):
       #coverage(x, shift=0L, width=NULL, weight=1L, ...)

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

       x: An IRanges, Views or MaskCollection object, or any object for
          which a 'coverage' method is defined. 

start, end: Single integers specifying the position in 'x' where to
          start and end the extraction of the coverage. IMPORTANT NOTE:
          Please do not use these arguments (use the shift/width
          arguments below). They are temporarily kept for backward
          compatibility with existing code and will be dropped in the
          near future. 

   shift: An integer vector (recycled to the length of 'x') specifying
          how each element in 'x' should be (horizontally) shifted
          before the coverage is computed. 

   width: The length of the returned coverage vector.

          If 'width=NULL' (the default), then the specific 'coverage'
          method that is actually selected will choose the length of
          the returned vector "in a way that makes sense".

          For example, when 'width=NULL', the method for IRanges
          objects returns a vector that has just enough elements to
          have its last element aligned with the rightmost end of all
          the ranges in 'x' after those ranges have been shifted (see
          the 'shift' argument above). This ensures that any longer
          coverage vector would be a "padded with zeros" version of the
          vector returned when 'width=NULL'.

          When 'width=NULL', the method for Views objects returns a
          vector with 'length(subject(x))' elements.

          When 'width=NULL', the method for MaskCollection objects
          returns a vector with 'width(x)' elements. 

  weight: An integer vector specifying how much each element in 'x'
          counts. 

     ...: Further arguments to be passed to or from other methods. 

_V_a_l_u_e:

     An Rle object representing the coverage of 'x'. An integer value
     called the "coverage" can be associated to each position in 'x',
     indicating how many times this position is covered by the elements
     contained in 'x'. For example, if 'x' is a Views object, the
     coverage of a given position in 'subject(x)' is the number of
     views it belongs to.

_N_o_t_e:

     The interface of the 'coverage' generic is currently being
     migrated from "start/end" to "shift/width". In the near future,
     the 'start' and 'end' arguments will be dropped and the remaining
     arguments will be: 'coverage(x, shift=0L, width=NULL, weight=1L,
     ...)' The "shift/width" interface is more intuitive, more
     convenient and offers slighty more control than the "start/end"
     interface. Also it makes sense to add the 'weight' argument to the
     generic (vs having it supported only by some methods) since
     weighting the elements in 'x' can be considered part of the
     concept of coverage in general.

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

     H. Pages and P. Aboyoun

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

     IRanges-class, Views-class, Rle-class, MaskCollection-class

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

       x <- IRanges(start=c(-2L, 6L, 9L, -4L, 1L, 0L, -6L, 10L),
                    width=c( 5L, 0L, 6L,  1L, 4L, 3L,  2L,  3L))
       coverage(x)
       coverage(x, shift=7)
       coverage(x, shift=7, width=27)
       coverage(restrict(x, 1, 10))
       coverage(reduce(x), shift=7)
       coverage(gaps(shift(x, 7), start=1, end=27))

       mask1 <- Mask(mask.width=29, start=c(11, 25, 28), width=c(5, 2, 2))
       mask2 <- Mask(mask.width=29, start=c(3, 10, 27), width=c(5, 8, 1))
       mask3 <- Mask(mask.width=29, start=c(7, 12), width=c(2, 4))
       mymasks <- append(append(mask1, mask2), mask3)
       coverage(mymasks)

