\Header{by}{Apply a Function to a Data Frame split by Factors}
\methalias{by.data.frame}{by}
\methalias{by.default}{by}
\alias{print.by}{by}
\keyword{iteration}{by}
\keyword{category}{by}
\begin{Description}\relax
Function \code{by} is an object-oriented wrapper for
\code{\Link{tapply}} applied to data frames.
\end{Description}
\begin{Usage}
\begin{verbatim}
by(data, INDICES, FUN, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{data}] an \R{} object, normally a data frame, possibly a matrix.
\item[\code{INDICES}] a factor or a list of factors, each of length \code{nrow(x)}.
\item[\code{FUN}] a function to be applied to data frame subsets of \code{x}.
\item[\code{...}] further arguments to \code{FUN}.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
A data frame is split by row into data frames
subsetted by the values of one or more factors, and function
\code{FUN} is applied to each subset in term.

Object \code{data} will be coerced to a data frame by default.
\end{Details}
\begin{Value}
A list of class \code{"by"}, giving the results for each subset.
\end{Value}
\begin{SeeAlso}\relax
\code{\Link{tapply}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
require(stats)
data(warpbreaks)
attach(warpbreaks)
by(warpbreaks[, 1:2], tension, summary)
by(warpbreaks[, 1], list(wool=wool, tension=tension), summary)
by(warpbreaks, tension, function(x) lm(breaks ~ wool, data=x))

## now suppose we want to extract the coefficients by group
tmp <- by(warpbreaks, tension, function(x) lm(breaks ~ wool, data=x))
sapply(tmp, coef)

detach("warpbreaks")
\end{ExampleCode}
\end{Examples}

