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

  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)),
         method = c("sort", "hash"))

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.
method Settings method to hash is intended only for large x objects. If method is set to the sort default, then x is sorted during the calculation of the coverage Rle. If method is set to hash, then x is hashed to a vector of size width. Note that setting method to hash saves time on large x vectors, but at the expense of additional memory usage.
... 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)
[Package IRanges version 1.8.8 Index]