\HeaderA{rowsum}{Give column sums of a matrix or data frame, based on a grouping variable}{rowsum}
\methaliasA{rowsum.data.frame}{rowsum}{rowsum.data.frame}
\methaliasA{rowsum.default}{rowsum}{rowsum.default}
\keyword{manip}{rowsum}
\begin{Description}\relax
Compute column sums across rows of a matrix-like object for each level of a
grouping variable.  \code{rowsum} is generic, with a method for data
frames and a default method for vectors and matrices.
\end{Description}
\begin{Usage}
\begin{verbatim}
rowsum(x, group, reorder = TRUE, ...)

## S3 method for class 'data.frame':
rowsum(x, group, reorder = TRUE, na.rm = FALSE, ...)

## Default S3 method:
rowsum(x, group, reorder = TRUE, na.rm = FALSE, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] a matrix, data frame or vector of numeric data.  Missing
values are allowed.  A numeric vector will be treated as a column vector.
\item[\code{group}] a vector or factor giving the grouping, with one element
per row of \code{x}.  Missing values will be treated as another
group and a warning will be given.
\item[\code{reorder}] if \code{TRUE}, then the result will be in order of
\code{sort(unique(group))}, if \code{FALSE}, it will be in the order
that groups were encountered.
\item[\code{na.rm}] logical (\code{TRUE} or \code{FALSE}).  Should \code{NA}
values be discarded?
\item[\code{...}] other arguments to be passed to or from methods
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The default is to reorder the rows to agree with \code{tapply} as in
the example below.  Reordering should not add noticeably to the time
except when there are very many distinct values of \code{group} and
\code{x} has few columns.

The original function was written by Terry Therneau, but this is a
new implementation using hashing that is much faster for large matrices.

To sum over all the rows of a matrix (ie, a single \code{group}) use
\code{\LinkA{colSums}{colSums}}, which should be even faster.
\end{Details}
\begin{Value}
A matrix or data frame containing the sums.  There will be one row per
unique value of \code{group}.
\end{Value}
\begin{SeeAlso}\relax
\code{\LinkA{tapply}{tapply}}, \code{\LinkA{aggregate}{aggregate}}, \code{\LinkA{rowSums}{rowSums}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
require(stats)

x <- matrix(runif(100), ncol=5)
group <- sample(1:8, 20, TRUE)
(xsum <- rowsum(x, group))
## Slower versions
tapply(x, list(group[row(x)], col(x)), sum)
t(sapply(split(as.data.frame(x), group), colSums))
aggregate(x, list(group), sum)[-1]
\end{ExampleCode}
\end{Examples}

