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]