coverage {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

  ## 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, ...)

Arguments

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.

Value

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.

Note

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.

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)

[Package IRanges version 1.2.3 Index]