\HeaderA{comparePred}{Compare Predictions}{comparePred}
\methaliasA{comparePred.gls}{comparePred}{comparePred.gls}
\methaliasA{comparePred.lme}{comparePred}{comparePred.lme}
\methaliasA{comparePred.lmList}{comparePred}{comparePred.lmList}
\keyword{models}{comparePred}
\begin{Description}\relax
Predicted values are obtained at the specified values of
\code{primary} for each object. If either \code{object1} or
\code{object2} have a grouping structure
(i.e. \code{getGroups(object)} is not \code{NULL}), predicted values
are obtained for each group. When both objects determine groups, the
group levels must be the same. If other covariates besides
\code{primary} are used in the prediction model, their group-wise averages
(numeric covariates) or most frequent values (categorical covariates)
are used to obtain the predicted values. The original observations are
also included in the returned object.
\end{Description}
\begin{Usage}
\begin{verbatim}
comparePred(object1, object2, primary, minimum, maximum,
    length.out, level, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{object1,object2}] fitted model objects, from which predictions can
be extracted using the \code{predict} method.
\item[\code{primary}] an optional one-sided formula specifying the primary
covariate to be used to generate the augmented predictions. By
default, if a  covariate can be extracted from the data used to generate
the objects (using \code{getCovariate}), it will be used as
\code{primary}.
\item[\code{minimum}] an optional lower limit for the primary
covariate. Defaults to \code{min(primary)}, after \code{primary} is 
evaluated in the \code{data} used in fitting \code{object1}.
\item[\code{maximum}] an optional upper limit for the primary
covariate. Defaults to \code{max(primary)}, after \code{primary} is
evaluated in the \code{data} used in fitting \code{object1}.
\item[\code{length.out}] an optional integer with the number of primary
covariate values at which to evaluate the predictions. Defaults to
51.
\item[\code{level}] an optional integer specifying the desired
prediction level. Levels increase from outermost to innermost
grouping, with level 0 representing the population (fixed effects)
predictions. Only one level can be specified. Defaults to the
innermost level.
\item[\code{...}] some methods for the generic may require additional
arguments.
\end{ldescription}
\end{Arguments}
\begin{Value}
a data frame with four columns representing, respectively, the values
of the primary covariate, the groups (if \code{object} does not have a
grouping structure, all elements will be \code{1}), the predicted or
observed values, and the type of value in the third column: the
objects' names are used to classify the predicted values and
\code{original} is used for the observed values. The returned object
inherits from classes \code{comparePred} and \code{augPred}.
\end{Value}
\begin{Note}\relax
This function is generic; method functions can be written to handle
specific classes of objects. Classes which already have methods for
this function include: \code{gls}, \code{lme}, and \code{lmList}.
\end{Note}
\begin{Author}\relax
Jose Pinheiro \email{Jose.Pinheiro@pharma.novartis.com} and Douglas Bates \email{bates@stat.wisc.edu}
\end{Author}
\begin{SeeAlso}\relax
\code{\LinkA{augPred}{augPred}}, \code{\LinkA{getGroups}{getGroups}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
fm1 <- lme(distance ~ age * Sex, data = Orthodont, random = ~ age)
fm2 <- update(fm1, distance ~ age)
comparePred(fm1, fm2, length.out = 2)
\end{ExampleCode}
\end{Examples}

