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, \dots)

  ## Transitional interface (the current one):
  coverage(x, start=NA, end=NA, shift=0L, width=NULL, weight=1L, ...)
  ## S4 method for signature 'RangesList':
coverage(x,
       start = structure(rep(list(NA), length(x)), names = names(x)),
       end = structure(rep(list(NA), length(x)), names = names(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)))

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

Arguments

x An IRanges, Views, MaskCollection, RangesList, RangedData object, or any object for which a coverage method is defined.
start, end For most methods, single integers specifying the position in x where to start and end the extraction of the coverage. 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). 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 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.

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 slightly more control than the "start/end" interface. Also it makes sense to add the weight argument to the generic (versus 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.4.16 Index]