\HeaderA{gapply}{Apply a Function by Groups}{gapply}
\keyword{data}{gapply}
\begin{Description}\relax
Applies the function to the distinct sets of rows of the data frame
defined by \code{groups}.
\end{Description}
\begin{Usage}
\begin{verbatim}
gapply(object, which, FUN, form, level, groups, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{object}] an object to which the function will be applied - usually
a \code{groupedData} object or a \code{data.frame}. Must inherit from
class \code{data.frame}.

\item[\code{which}] an optional character or positive integer vector
specifying which columns of \code{object} should be used with
\code{FUN}. Defaults to all columns in \code{object}.

\item[\code{FUN}] function to apply to the distinct sets of rows
of the data frame \code{object} defined by the values of
\code{groups}.

\item[\code{form}] an optional one-sided formula that defines the groups.
When this formula is given the right-hand side is evaluated in
\code{object}, converted to a factor if necessary, and the unique
levels are used to define the groups.  Defaults to
\code{formula(object)}.

\item[\code{level}] an optional positive integer giving the level of grouping
to be used in an object with multiple nested grouping levels.
Defaults to the highest or innermost level of grouping.

\item[\code{groups}] an optional factor that will be used to split the 
rows into groups.  Defaults to \code{getGroups(object, form, level)}.

\item[\code{...}] optional additional arguments to the summary function
\code{FUN}.  Often it is helpful to specify \code{na.rm = TRUE}.

\end{ldescription}
\end{Arguments}
\begin{Value}
Returns a data frame with as many rows as there are levels in the
\code{groups} argument.
\end{Value}
\begin{Author}\relax
Jose Pinheiro \email{Jose.Pinheiro@pharma.novartis.com} and Douglas Bates \email{bates@stat.wisc.edu}
\end{Author}
\begin{References}\relax
Pinheiro, J.C., and Bates, D.M. (2000) "Mixed-Effects Models
in S and S-PLUS", Springer, esp. sec. 3.4.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{gsummary}{gsummary}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
## Find number of non-missing "conc" observations for each Subject
gapply( Phenobarb, FUN = function(x) sum(!is.na(x$conc)) )

# Pinheiro and Bates, p. 127 
table( gapply(Quinidine, "conc", function(x) sum(!is.na(x))) )
changeRecords <- gapply( Quinidine, FUN = function(frm)
    any(is.na(frm[["conc"]]) & is.na(frm[["dose"]])) )
\end{ExampleCode}
\end{Examples}

