\Header{plot.gls}{Plot a gls Object}
\keyword{models}{plot.gls}
\begin{Description}\relax
Diagnostic plots for the linear model fit are obtained. The
\code{form} argument gives considerable flexibility in the type of
plot specification. A conditioning expression (on the right side of a
\code{|} operator) always implies that different panels are used for
each level of the conditioning factor, according to a Trellis
display. If \code{form} is a one-sided formula, histograms of the
variable on the right hand side of the formula, before a \code{|}
operator, are displayed (the Trellis function \code{histogram} is
used). If \code{form} is two-sided and both its left and
right hand side variables are numeric, scatter plots are displayed
(the Trellis function \code{xyplot} is used). Finally, if \code{form}
is two-sided and its left had side variable is a factor, box-plots of
the right hand side variable by the levels of the left hand side
variable are displayed (the Trellis function  \code{bwplot} is used).\end{Description}
\begin{Usage}
\begin{verbatim}
## S3 method for class 'gls':
plot(x, form, abline, id, idLabels, idResType, grid, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] an object inheriting from class \code{gls}, representing
a generalized least squares fitted linear model.
\item[\code{form}] an optional formula specifying the desired type of
plot. Any variable present in the original data frame used to obtain
\code{x} can be referenced. In addition, \code{x} itself
can be referenced in the formula using the symbol
\code{"."}. Conditional expressions on the right of a \code{|}
operator can be used to define separate panels in a Trellis
display. Default is \code{resid(., type = "p") \textasciitilde{} fitted(.) },
corresponding to a plot of the standardized residuals versus fitted
values, both evaluated at the innermost level of nesting.
\item[\code{abline}] an optional numeric value, or numeric vector of length
two. If given as a single value, a horizontal line will be added to the
plot at that coordinate; else, if given as a vector, its values are
used as the intercept and slope for a line added to the plot. If
missing, no lines are added to the plot.
\item[\code{id}] an optional numeric value, or one-sided formula. If given as
a value, it is used as a significance level for a two-sided outlier
test for the standardized residuals. Observations with
absolute standardized residuals greater than the \eqn{1 - value/2}{}
quantile of the standard normal distribution are identified in the
plot using \code{idLabels}. If given as a one-sided formula, its
right hand side must evaluate to a  logical, integer, or character
vector which is used to identify observations in the plot. If
missing, no observations are identified.
\item[\code{idLabels}] an optional vector, or one-sided formula. If given as a
vector, it is converted to character mode and used to label the
observations identified according to \code{id}. If given as a
one-sided formula, its right hand side must evaluate to a vector
which is converted to character mode and used to label the identified
observations. Default is the innermost grouping factor.
\item[\code{idResType}] an optional character string specifying the type of
residuals to be used in identifying outliers, when \code{id} is a
numeric value. If \code{"pearson"}, the standardized residuals (raw 
residuals divided by the corresponding standard errors) are used;
else, if \code{"normalized"}, the normalized residuals (standardized
residuals pre-multiplied by the inverse square-root factor of the
estimated error correlation matrix) are used. Partial matching of
arguments is used, so only the first character needs to be
provided. Defaults to \code{"pearson"}.
\item[\code{grid}] an optional logical value indicating whether a grid should
be added to plot. Default depends on the type of Trellis plot used:
if \code{xyplot} defaults to \code{TRUE}, else defaults to
\code{FALSE}.
\item[\code{...}] optional arguments passed to the Trellis plot function.
\end{ldescription}
\end{Arguments}
\begin{Value}
a diagnostic Trellis plot.\end{Value}
\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{\Link{gls}}, \code{\Link{xyplot}},
\code{\Link{bwplot}},
\code{\Link{histogram}}\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
data(Ovary)
fm1 <- gls(follicles ~ sin(2*pi*Time) + cos(2*pi*Time), Ovary,
           correlation = corAR1(form = ~ 1 | Mare))
# standardized residuals versus fitted values by Mare
plot(fm1, resid(., type = "p") ~ fitted(.) | Mare, abline = 0)
# box-plots of residuals by Mare
plot(fm1, Mare ~ resid(.))
# observed versus fitted values by Mare
plot(fm1, follicles ~ fitted(.) | Mare, abline = c(0,1))
\end{ExampleCode}
\end{Examples}

