R: Coverage across a set of ranges

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`. For `RangedData` objects, this can also be a single string naming a column to be used as the weights.
`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

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.12.6 Index]