coverage               package:IRanges               R Documentation

Coverage across a set of ranges

Description:

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

Usage:

       coverage(x, shift=0L, width=NULL, weight=1L, ...)
       ## S4 method for signature 'RangesList':
       coverage(x,
              shift = structure(rep(list(0L), length(x)), names = names(x)),
              width = structure(rep(list(NULL), length(x)), names = names(x)),
              weight = structure(rep(list(1L), length(x)), names = names(x)))

Arguments:

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

   shift: For most methods, an integer vector (recycled to the length
          of 'x') specifying how each element in 'x' should be
          (horizontally) shifted before the coverage is computed. Only
          shifted indices in the range [1, 'width'] will be included in
          the coverage calculation. For RangesList and RangedData
          objects, a list or vector of the same length as 'x' to be
          used for the corresponding element in 'x'. In addition for
          RangedData objects, can also be a character vector of length
          1 denoting the column to use in 'values(x)'. 

   width: For most methods, the length of the returned coverage vector.
          For RangesList and RangedData objects, a list or vector of
          the same length as 'x' to be used for the corresponding
          element in 'x'. In addition for RangedData objects, can also
          be a character vector of length 1 denoting the column to use
          in 'values(x)'.

          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: For most methods, an integer vector specifying how much each
          element in 'x' counts. For RangesList and RangedData objects,
          a list or vector of the same length as 'x' to be used for the
          corresponding element in 'x'. 

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

Value:

     For most methods, an Rle object representing the coverage of 'x'.
     For RangesList and RangedData objects, a SimpleRleList object
     representing a list of coverage vectors.

     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.

Author(s):

     H. Pages and P. Aboyoun

See Also:

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

Examples:

       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)

