\HeaderA{coverage}{Coverage across a set of ranges}{coverage}
\aliasA{coverage,IRanges-method}{coverage}{coverage,IRanges.Rdash.method}
\aliasA{coverage,MaskCollection-method}{coverage}{coverage,MaskCollection.Rdash.method}
\aliasA{coverage,numeric-method}{coverage}{coverage,numeric.Rdash.method}
\aliasA{coverage,RangedData-method}{coverage}{coverage,RangedData.Rdash.method}
\aliasA{coverage,RangesList-method}{coverage}{coverage,RangesList.Rdash.method}
\aliasA{coverage,Views-method}{coverage}{coverage,Views.Rdash.method}
\aliasA{coverage.normargWidth}{coverage}{coverage.normargWidth}
\keyword{methods}{coverage}
\begin{Description}\relax
Counts the number of times a position is represented in a set of ranges.
\end{Description}
\begin{Usage}
\begin{verbatim}
  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)))
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] An \LinkA{IRanges}{IRanges}, \LinkA{Views}{Views}, \LinkA{MaskCollection}{MaskCollection}, 
\LinkA{RangesList}{RangesList}, \LinkA{RangedData}{RangedData} object, or any object for which a
\code{coverage} method is defined.

\item[\code{shift}] For most methods, an integer vector (recycled to the length of
\code{x}) specifying how each element in \code{x} should be
(horizontally) shifted before the coverage is computed. Only shifted
indices in the range [1, \code{width}] will be included in the coverage
calculation.
For \LinkA{RangesList}{RangesList} and \LinkA{RangedData}{RangedData} objects, a list or vector
of the same length as \code{x} to be used for the corresponding element
in \code{x}. In addition for \LinkA{RangedData}{RangedData} objects, can also be
a character vector of length 1 denoting the column to use in
\code{values(x)}.

\item[\code{width}] For most methods, the length of the returned coverage vector. For
\LinkA{RangesList}{RangesList} and \LinkA{RangedData}{RangedData} objects, a list or vector of
the same length as \code{x} to be used for the corresponding element
in \code{x}. In addition for \LinkA{RangedData}{RangedData} objects, can also be
a character vector of length 1 denoting the column to use in
\code{values(x)}.

If \code{width=NULL} (the default), then the specific \code{coverage}
method that is actually selected will choose the length of the returned
vector "in a way that makes sense".

For example, when \code{width=NULL}, the method for \LinkA{IRanges}{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 \code{x} after
those ranges have been shifted (see the \code{shift} argument above).
This ensures that any longer coverage vector would be a "padded with zeros"
version of the vector returned when \code{width=NULL}.

When \code{width=NULL}, the method for \LinkA{Views}{Views} objects
returns a vector with \code{length(subject(x))} elements.

When \code{width=NULL}, the method for \LinkA{MaskCollection}{MaskCollection} objects
returns a vector with \code{width(x)} elements.

\item[\code{weight}] For most methods, an integer vector specifying how much each element in
\code{x} counts. For \LinkA{RangesList}{RangesList} and \LinkA{RangedData}{RangedData} objects, a
list or vector of the same length as \code{x} to be used for the
corresponding element in \code{x}.

\item[\code{...}] Further arguments to be passed to or from other methods.

\end{ldescription}
\end{Arguments}
\begin{Value}
For most methods, an \LinkA{Rle}{Rle} object representing the coverage of
\code{x}. For \LinkA{RangesList}{RangesList} and \LinkA{RangedData}{RangedData} objects, a
\LinkA{SimpleRleList}{SimpleRleList} object representing a list of coverage vectors.

An integer value called the "coverage" can be associated to each position
in \code{x}, indicating how many times this position is covered by the
elements contained in \code{x}.
For example, if \code{x} is a \LinkA{Views}{Views} object, the coverage of
a given position in \code{subject(x)} is the number of views it belongs to.
\end{Value}
\begin{Author}\relax
H. Pages and P. Aboyoun
\end{Author}
\begin{SeeAlso}\relax
\LinkA{IRanges-class}{IRanges.Rdash.class},
\LinkA{Views-class}{Views.Rdash.class},
\LinkA{Rle-class}{Rle.Rdash.class},
\LinkA{MaskCollection-class}{MaskCollection.Rdash.class}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
  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)
\end{ExampleCode}
\end{Examples}

