coverage-methods {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=0L, width=NULL, weight=1L,
       method = c("auto", "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 or numeric 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 IRanges, Views, and MaskCollection objects, this can also be a single string naming a metadata column (i.e. a column in mcols(x)) to be used as the weights. For RangedData objects, this can also be a single string naming a column of values (i.e. a column in values(x)) to be used as the weights.

method

If method is set to "sort", then x is sorted previous to the calculation of the coverage. If method is set to hash, then x is hashed directly to a vector of length width without previous sorting.

The "hash" method is faster than the "sort" method when x is large (i.e. contains a lot of ranges). When x is small and width is big (e.g. x represents a small set of reads aligned to a big chromosome), then method="sort" is faster and uses less memory than method="hash".

Using method="auto" selects the best method based on length(x) and width.

...

Further arguments to be passed to or from other methods.

Value

For most methods, an integer-Rle (if typeof(weight) is "integer") or numeric-Rle (if typeof(weight) is "double") object representing the coverage of x. For RangesList and RangedData objects, a SimpleRleList object representing a list of coverage vectors.

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))

cvg1 <- coverage(x[c(TRUE, FALSE)], width=99)
cvg2 <- coverage(x[c(FALSE, TRUE)], width=99)
stopifnot(identical(coverage(x, width=99), cvg1 + cvg2))
stopifnot(identical(coverage(x, width=99, weight=c(5L, -11L)),
                    cvg1 * 5L + cvg2 * -11L))

cvg3 <- coverage(x, weight=1.5)
cvg3  # numeric-Rle
stopifnot(identical(cvg3, coverage(x) * 1.5))

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