\HeaderA{plot.lm}{Plot Diagnostics for an lm Object}{plot.lm}
\aliasA{plot.mlm}{plot.lm}{plot.mlm}
\keyword{hplot}{plot.lm}
\keyword{regression}{plot.lm}
\begin{Description}\relax
Six plots (selectable by \code{which}) are currently available: a plot
of residuals against fitted values, a Scale-Location plot of
\eqn{\sqrt{| residuals |}}{} against fitted values, a Normal Q-Q plot, a
plot of Cook's distances versus row labels, a plot of residuals
against leverages, and a plot of Cook's distances against
leverage/(1-leverage).  By default, the first
three and \code{5} are provided.
\end{Description}
\begin{Usage}
\begin{verbatim}
## S3 method for class 'lm':
plot(x, which = c(1:3,5), 
     caption = list("Residuals vs Fitted", "Normal Q-Q",
          "Scale-Location", "Cook's distance",
          "Residuals vs Leverage",
          expression("Cook's dist vs Leverage  " * h[ii] / (1 - h[ii]))),
     panel = if(add.smooth) panel.smooth else points,
     sub.caption = NULL, main = "",
     ask = prod(par("mfcol")) < length(which) && dev.interactive(),
     ...,
     id.n = 3, labels.id = names(residuals(x)), cex.id = 0.75,
     qqline = TRUE, cook.levels = c(0.5, 1.0),
     add.smooth = getOption("add.smooth"), label.pos = c(4,2),
     cex.caption = 1)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] \code{lm} object, typically result of \code{\LinkA{lm}{lm}} or
\code{\LinkA{glm}{glm}}.
\item[\code{which}] if a subset of the plots is required, specify a subset of
the numbers \code{1:6}.
\item[\code{caption}] captions to appear above the plots;
\code{\LinkA{character}{character}} vector or \code{\LinkA{list}{list}} of valid
graphics annotations, see \code{\LinkA{as.graphicsAnnot}{as.graphicsAnnot}}.
Can be set to \code{""} or \code{NA} to suppress all captions.

\item[\code{panel}] panel function.  The useful alternative to
\code{\LinkA{points}{points}}, \code{\LinkA{panel.smooth}{panel.smooth}} can be chosen
by \code{add.smooth = TRUE}.
\item[\code{sub.caption}] common title---above figures if there are multiple;
used as \code{sub} (s.\code{\LinkA{title}{title}}) otherwise.  If \code{NULL},
as by default, a possible shortened version of
\code{deparse(x\$call)} is used.
\item[\code{main}] title to each plot---in addition to the above
\code{caption}.
\item[\code{ask}] logical; if \code{TRUE}, the user is \emph{ask}ed before
each plot, see \code{\LinkA{par}{par}(ask=.)}.
\item[\code{...}] other parameters to be passed through to plotting
functions.
\item[\code{id.n}] number of points to be labelled in each plot, starting
with the most extreme.
\item[\code{labels.id}] vector of labels, from which the labels for extreme
points will be chosen.  \code{NULL} uses observation numbers.
\item[\code{cex.id}] magnification of point labels.
\item[\code{qqline}] logical indicating if a \code{\LinkA{qqline}{qqline}()} should be
added to the normal Q-Q plot.
\item[\code{cook.levels}] levels of Cook's distance at which to draw contours.
\item[\code{add.smooth}] logical indicating if a smoother should be added to
most plots; see also \code{panel} above.
\item[\code{label.pos}] positioning of labels, for the left half and right
half of the graph respectively, for plots 1-3.
\item[\code{cex.caption}] controls the size of \code{caption}.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
\code{sub.caption}---by default the function call---is shown as
a subtitle (under the x-axis title) on each plot when plots are on
separate pages, or as a subtitle in the outer margin (if any) when
there are multiple plots per page.

The \sQuote{Scale-Location} plot, also called \sQuote{Spread-Location} or
\sQuote{S-L} plot, takes the square root of the absolute residuals in
order to diminish skewness (\eqn{\sqrt{| E |}}{} is much less skewed
than \eqn{| E |}{} for Gaussian zero-mean \eqn{E}{}).

The \sQuote{S-L}, the Q-Q, and the Residual-Leverage plot, use
\emph{standardized} residuals which have identical variance (under the
hypothesis).  They are given as
\eqn{R_i / (s \times \sqrt{1 - h_{ii}})}{R[i] / (s*sqrt(1 - h.ii))}
where \eqn{h_{ii}}{h.ii} are the diagonal entries of the hat matrix,
\code{\LinkA{influence}{influence}()}\code{\$hat}, see also \code{\LinkA{hat}{hat}}, and
where the Residual-Leverage uses standardized Pearson residuals
(\code{\LinkA{residuals.glm}{residuals.glm}(type = "pearson")}) for \eqn{R[i]}{}.

The Residual-Leverage plot shows contours of equal Cook's distance,
for values of \code{cook.levels} (by default 0.5 and 1) and omits
cases with leverage one with a warning.  If the leverages are constant
(as is typically the case in a balanced \code{\LinkA{aov}{aov}} situation)
the plot uses factor level combinations instead of the leverages for
the x-axis.  (The factor levels are ordered by mean fitted value.)

In the Cook's distance vs leverage/(1-leverage) plot, contours of
standardized residuals that are equal in magnitude are lines through
the origin.  The contour lines are labelled with the magnitudes.
\end{Details}
\begin{Author}\relax
John Maindonald and Martin Maechler.
\end{Author}
\begin{References}\relax
Belsley, D. A., Kuh, E. and Welsch, R. E. (1980)
\emph{Regression Diagnostics.}  New York: Wiley.

Cook, R. D. and Weisberg, S. (1982)
\emph{Residuals and Influence in Regression.}
London: Chapman and Hall.

Firth, D. (1991) Generalized Linear Models.  In Hinkley, D. V. and
Reid, N. and Snell, E. J., eds: Pp. 55-82 in Statistical Theory and
Modelling. In Honour of Sir David Cox, FRS.  London: Chapman and Hall.

Hinkley, D. V. (1975) On power transformations to
symmetry. \emph{Biometrika} \bold{62}, 101--111.

McCullagh, P. and Nelder, J. A. (1989)
\emph{Generalized Linear Models.}
London: Chapman and Hall.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{termplot}{termplot}}, \code{\LinkA{lm.influence}{lm.influence}},
\code{\LinkA{cooks.distance}{cooks.distance}}, \code{\LinkA{hatvalues}{hatvalues}}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
require(graphics)

## Analysis of the life-cycle savings data
## given in Belsley, Kuh and Welsch.
plot(lm.SR <- lm(sr ~ pop15 + pop75 + dpi + ddpi, data = LifeCycleSavings))

## 4 plots on 1 page;
## allow room for printing model formula in outer margin:
par(mfrow = c(2, 2), oma = c(0, 0, 2, 0))
plot(lm.SR)
plot(lm.SR, id.n = NULL)               # no id's
plot(lm.SR, id.n = 5, labels.id = NULL)# 5 id numbers

## Was default in R <= 2.1.x:
## Cook's distances instead of Residual-Leverage plot
plot(lm.SR, which = 1:4)

## Fit a smooth curve, where applicable:
plot(lm.SR, panel = panel.smooth)
## Gives a smoother curve
plot(lm.SR, panel = function(x,y) panel.smooth(x, y, span = 1))

par(mfrow=c(2,1))# same oma as above
plot(lm.SR, which = 1:2, sub.caption = "Saving Rates, n=50, p=5")


\end{ExampleCode}
\end{Examples}

