| % File src/library/stats/man/plot.lm.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 1995-2022 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{plot.lm} |
| \alias{plot.lm} |
| % \alias{plot.mlm} %which is .NotYetImplemented() |
| \title{Plot Diagnostics for an \code{lm} Object} |
| \usage{ |
| \method{plot}{lm}(x, which = c(1,2,3,5), %% was which = 1:4 |
| 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) function(x, y, ...) |
| panel.smooth(x, y, iter=iter.smooth, ...) else points, |
| sub.caption = NULL, main = "", |
| ask = prod(par("mfcol")) < length(which) && dev.interactive(), |
| \dots, |
| id.n = 3, labels.id = names(residuals(x)), cex.id = 0.75, |
| qqline = TRUE, cook.levels = c(0.5, 1.0), |
| cook.col = 8, cook.lty = 2, cook.legendChanges = list(), |
| add.smooth = getOption("add.smooth"), |
| iter.smooth = if(isGlm) 0 else 3, |
| label.pos = c(4,2), |
| cex.caption = 1, cex.oma.main = 1.25 |
| , extend.ylim.f = 0.08 |
| ) |
| } |
| \arguments{ |
| \item{x}{\code{lm} object, typically result of \code{\link{lm}} or |
| \code{\link{glm}}.} |
| \item{which}{a subset of the numbers \code{1:6}, by default \code{1:3, 5}, |
| referring to \enumerate{ |
| \item "Residuals vs Fitted", aka \sQuote{Tukey-Anscombe} plot % 1 |
| \item "Normal Q-Q" plot, an enhanced \code{\link{qqnorm}(resid(.))} % 2 |
| \item "Scale-Location" % 3 |
| \item "Cook's distance" % 4 |
| \item "Residuals vs Leverage" % 5 |
| \item "Cook's dist vs Lev./(1-Lev.)" % 6 |
| } |
| See also \sQuote{Details} below.} |
| \item{caption}{captions to appear above the plots; |
| \code{\link{character}} vector or \code{\link{list}} of valid |
| graphics annotations, see \code{\link{as.graphicsAnnot}}, of length |
| 6, the j-th entry corresponding to \code{which[j]}, see also the |
| default vector in \sQuote{Usage}. Can be set to |
| \code{""} or \code{NA} to suppress all captions. |
| } |
| \item{panel}{panel function. The useful alternative to |
| \code{\link{points}}, \code{\link{panel.smooth}} can be chosen |
| by \code{add.smooth = TRUE}.} |
| \item{sub.caption}{common title---above the figures if there are more |
| than one; used as \code{sub} (s.\code{\link{title}}) otherwise. If |
| \code{NULL}, as by default, a possible abbreviated version of |
| \code{deparse(x$call)} is used.} |
| \item{main}{title to each plot---in addition to \code{caption}.} |
| \item{ask}{logical; if \code{TRUE}, the user is \emph{ask}ed before |
| each plot, see \code{\link{par}(ask=.)}.} |
| \item{\dots}{other parameters to be passed through to plotting |
| functions.} |
| \item{id.n}{number of points to be labelled in each plot, starting |
| with the most extreme.} |
| \item{labels.id}{vector of labels, from which the labels for extreme |
| points will be chosen. \code{NULL} uses observation numbers.} |
| \item{cex.id}{magnification of point labels.} |
| \item{qqline}{logical indicating if a \code{\link{qqline}()} should be |
| added to the normal Q-Q plot.} |
| \item{cook.levels}{levels of Cook's distance at which to draw contours.} |
| \item{cook.col, cook.lty}{color and line type to use for these contour |
| lines.} |
| \item{cook.legendChanges}{a \code{\link{list}} (or \code{NULL} to |
| suppress the call) of arguments to \code{\link{legend}} which should be |
| \emph{modified} from (or added to) the \code{plot.lm()} default \code{ |
| list(x = "bottomleft", legend = "Cook's distance", |
| lty = cook.lty, col = cook.col, text.col = cook.col, |
| bty = "n", x.intersp = 1/4, y.intersp = 1/8) }.} |
| \item{add.smooth}{logical indicating if a smoother should be added to |
| most plots; see also \code{panel} above.} |
| \item{iter.smooth}{the number of robustness iterations, the argument |
| \code{iter} in \code{\link{panel.smooth}()}; the default uses no such |
| iterations for \code{\link{glm}} fits which is |
| particularly desirable for the (predominant) case of binary |
| observations, but also for other models where the response |
| distribution can be highly skewed.} |
| \item{label.pos}{positioning of labels, for the left half and right |
| half of the graph respectively, for plots 1-3, 5, 6.} |
| \item{cex.caption}{controls the size of \code{caption}.} |
| \item{cex.oma.main}{controls the size of the \code{sub.caption} only if |
| that is \emph{above} the figures when there is more than one.} |
| \item{extend.ylim.f}{a numeric vector of length 1 or 2, to be used in |
| \code{ylim <- \link{extendrange}(r=ylim, f = *)} |
| for plots \code{1} and \code{5} when \code{id.n} is non-empty.} |
| } |
| \description{ |
| Six plots (selectable by \code{which}) are currently available: a plot |
| of residuals against fitted values, a Scale-Location plot of |
| \eqn{\sqrt{| residuals |}}{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. |
| } |
| \details{ |
| \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 (\code{which=3}), 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 |}}{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 (\code{which=5}) 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 the \emph{\sQuote{leverages}} \eqn{h_{ii}}{h.ii} are the diagonal entries |
| of the hat matrix, |
| \code{\link{influence}()$hat} (see also \code{\link{hat}}), and |
| where the Residual-Leverage plot uses the standardized Pearson residuals |
| (\code{\link{residuals.glm}(type = "pearson")}) for \eqn{R[i]}. |
| |
| The Residual-Leverage plot (\code{which=5}) 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{\link{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) (= \dQuote{leverage*}) |
| plot (\code{which=6}), contours of |
| standardized residuals (\code{\link{rstandard}(.)}) that are equal in |
| magnitude are lines through the origin. These lines are labelled with |
| the magnitudes. The x-axis is labeled with the (non equidistant) |
| leverages \eqn{h_{ii}}{h.ii}. |
| |
| Notice that some plots may not make much sense for the \code{glm} |
| case; e.g., the normal Q-Q plot only makes sense if the distribution |
| is approximately normal. |
| } |
| |
| \references{ |
| 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.\sspace{}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. |
| \doi{10.2307/2334491}. |
| |
| McCullagh, P. and Nelder, J. A. (1989). |
| \emph{Generalized Linear Models}. |
| London: Chapman and Hall. |
| } |
| \author{ |
| John Maindonald and Martin Maechler. |
| } |
| \seealso{\code{\link{termplot}}, \code{\link{lm.influence}}, |
| \code{\link{cooks.distance}}, \code{\link{hatvalues}}. |
| } |
| \examples{ |
| require(graphics) |
| |
| ## Analysis of the life-cycle savings data |
| ## given in Belsley, Kuh and Welsch. |
| lm.SR <- lm(sr ~ pop15 + pop75 + dpi + ddpi, data = LifeCycleSavings) |
| plot(lm.SR) |
| |
| ## 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)) -> opar |
| 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) |
| |
| ## All the above fit a smooth curve where applicable |
| ## by default unless "add.smooth" is changed. |
| ## Give a smoother curve by increasing the lowess span : |
| 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") |
| |
| ## Cook's distance tweaking |
| par(mfrow = c(2,3)) # same oma ... |
| plot(lm.SR, which = 1:6, cook.col = "royalblue") |
| |
| ## A case where over plotting of the "legend" is to be avoided: |
| if(dev.interactive(TRUE)) getOption("device")(height = 6, width = 4) |
| par(mfrow = c(3,1), mar = c(5,5,4,2)/2 +.1, mgp = c(1.4, .5, 0)) |
| plot(lm.SR, which = 5, extend.ylim.f = c(0.2, 0.08)) |
| plot(lm.SR, which = 5, cook.lty = "dotdash", |
| cook.legendChanges = list(x = "bottomright", legend = "Cook")) |
| plot(lm.SR, which = 5, cook.legendChanges = NULL) # no "legend" |
| |
| \dontshow{ |
| ## An example with *long* formula that needs abbreviation: |
| par(mfrow = c(2,2)) |
| for(i in 1:5) assign(paste("long.var.name", i, sep = "."), runif(10)) |
| plot(lm(long.var.name.1 ~ |
| long.var.name.2 + long.var.name.3 + long.var.name.4 + long.var.name.5)) |
| } |
| par(opar) # reset par()s |
| } |
| \keyword{hplot} |
| \keyword{regression} |