\Header{aggregate}{Compute Summary Statistics of Data Subsets}
\alias{aggregate.default}{aggregate}
\alias{aggregate.data.frame}{aggregate}
\alias{aggregate.ts}{aggregate}
\keyword{category}{aggregate}
\keyword{array}{aggregate}
\begin{Usage}
\begin{verbatim}
aggregate(x, ...)
aggregate.default(x, ...)
aggregate.data.frame(x, by, FUN, ...)
aggregate.ts(x, nfrequency = 1, FUN = sum, ndeltat = 1)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\texttt{x}] an R object.
\item[\texttt{by}] a list of grouping elements, each as long as the variables
in \texttt{x}.  Names for the grouping variables are provided if
they are not given.
\item[\texttt{FUN}] a scalar function to compute the summary statistics which
can be applied to all data subsets.
\item[\texttt{nfrequency}] new number of observations per unit of time; must
be a divisor of the frequency of \texttt{x}.
\item[\texttt{ndeltat}] new fraction of the sampling period between
successive observations; must be a divisor of the sampling
interval of \texttt{x}.
\item[\texttt{...}] further arguments passed to the method used.
\end{ldescription}
\end{Arguments}
\begin{Description}
Splits the data into subsets, computes summary statistics for each,
and returns the result in a convenient form.\end{Description}
\begin{Details}
\texttt{aggregate} is a generic functions with methods for data frames
and time series.

The default method \texttt{aggregate.default} uses the time series
method if \texttt{x} is a time series, and otherwise coerces \texttt{x}
to a data frame and calls the data frame method.

\texttt{aggregate.data.frame} is the data frame method.  If \texttt{x}
is not a data frame, it is coerced to one.  Then, each of the
variables (columns) in \texttt{x} is split into subsets of cases
(rows) of identical combinations of the components of \texttt{by}, and
\texttt{FUN} is applied to each such subset with further arguments in
\texttt{...} passed to it.
(I.e., \texttt{tapply(VAR, by, FUN, ..., simplify = FALSE)} is done
for each variable \texttt{VAR} in \texttt{x}, conveniently wrapped into
one call to \texttt{lapply()}.)
Empty subsets are removed, and the result is reformatted into a data
frame containing the variables in \texttt{by} and \texttt{x}.  The ones
arising from \texttt{by} contain the unique combinations of grouping
values used for determining the subsets, and the ones arising from
\texttt{x} the corresponding summary statistics for the subset of the
respective variables in \texttt{x}.

\texttt{aggregate.ts} is the time series method.  If \texttt{x} is not a
time series, it is coerced to one.  Then, the variables in \texttt{x}
are split into appropriate blocks of length
\texttt{frequency(x) / nfrequency}, and \texttt{FUN} is applied to each
such block.  The result returned is a time series with frequency
\texttt{nfrequency} holding the aggregated values.\end{Details}
\begin{Author}
Kurt Hornik\end{Author}
\begin{SeeAlso}
\texttt{\Link{apply}}, \texttt{\Link{lapply}}, \texttt{\Link{tapply}}.\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
data(state)

## Compute the averages for the variables in `state.x77', grouped
## according to the region (Northeast, South, North Central, West) that
## each state belongs to.
aggregate(state.x77, list(Region = state.region), mean)

## Compute the averages according to region and the occurrence of more
## than 130 days of frost.
aggregate(state.x77,
          list(Region = state.region,
               Cold = state.x77[,"Frost"] > 130),
          mean)
## (Note that no state in `South' is THAT cold.)

data(presidents)
## Compute the average annual approval ratings for American presidents.
aggregate(presidents, nf = 1, FUN = mean)
\end{ExampleCode}
\end{Examples}

