The R Project SVN R

% File src/library/stats/man/termplot.Rd

% Part of the R package, https://www.R-project.org

% Copyright 1995-2015 R Core Team

% Distributed under GPL 2 or later

\name{termplot}

\alias{termplot}

\title{Plot Regression Terms}

\description{

  Plots regression terms against their predictors, optionally with

  standard errors and partial residuals added.

}

\usage{

termplot(model, data = NULL, envir = environment(formula(model)),

         partial.resid = FALSE, rug = FALSE,

         terms = NULL, se = FALSE,

         xlabs = NULL, ylabs = NULL, main = NULL,

         col.term = 2, lwd.term = 1.5,

         col.se = "orange", lty.se = 2, lwd.se = 1,

         col.res = "gray", cex = 1, pch = par("pch"),

         col.smth = "darkred", lty.smth = 2, span.smth = 2/3,

         ask = dev.interactive() && nb.fig < n.tms,

         use.factor.levels = TRUE, smooth = NULL, ylim = "common",

         plot = TRUE, transform.x = FALSE, \dots)

}

\arguments{

  \item{model}{fitted model object}

  \item{data}{data frame in which variables in \code{model} can be

    found}

  \item{envir}{environment in which variables in \code{model} can be found}

  \item{partial.resid}{logical; should partial residuals be plotted?}

  \item{rug}{add \link{rug}plots (jittered 1-d histograms) to the axes?}

  \item{terms}{which terms to plot (default \code{NULL} means all

    terms); a vector passed to

    \code{\link{predict}(.., type = "terms", terms = *)}.}

  \item{se}{plot pointwise standard errors?}

  \item{xlabs}{vector of labels for the x axes}

  \item{ylabs}{vector of labels for the y axes}

  \item{main}{logical, or vector of main titles;  if \code{TRUE}, the

    model's call is taken as main title, \code{NULL} or \code{FALSE} mean

    no titles.}

  \item{col.term, lwd.term}{color and line width for the \sQuote{term curve},

    see \code{\link{lines}}.}

  \item{col.se, lty.se, lwd.se}{color, line type and line width for the

    \sQuote{twice-standard-error curve} when \code{se = TRUE}.}

  \item{col.res, cex, pch}{color, plotting character expansion and type

    for partial residuals, when \code{partial.resid = TRUE}, see

    \code{\link{points}}.}

   \item{ask}{logical; if \code{TRUE}, the user is \emph{ask}ed before

     each plot, see \code{\link{par}(ask=.)}.}

   \item{use.factor.levels}{Should x-axis ticks use factor levels or

     numbers for factor terms?}

   \item{smooth}{\code{NULL} or a function with the same arguments as

     \code{\link{panel.smooth}} to draw a smooth through the partial

     residuals for non-factor terms}

   \item{lty.smth, col.smth, span.smth}{Passed to \code{smooth}}

   \item{ylim}{an optional range for the y axis, or \code{"common"} when

     a range sufficient for all the plot will be computed, or

     \code{"free"} when limits are computed for each plot.}

   \item{plot}{if set to \code{FALSE} plots are not produced: instead a

     list is returned containing the data that would have been plotted.}

   \item{transform.x}{logical vector; if an element (recycled as necessary)

     is \code{TRUE}, partial residuals for the corresponding term are

     plotted against transformed values.

     The model response is then a straight line, allowing a

     ready comparison against the data or against the curve

     obtained from \code{smooth-panel.smooth}.}

   \item{\dots}{other graphical parameters.}

}

\details{

  The \code{model} object must have a \code{predict} method that accepts

  \code{type = "terms"}, e.g., \code{\link{glm}} in the \pkg{stats} package,

  \code{\link[survival]{coxph}} and \code{\link[survival]{survreg}} in

  the \CRANpkg{survival} package.

  For the \code{partial.resid = TRUE} option \code{model} must have a

  \code{\link{residuals}} method that accepts \code{type = "partial"},

  which \code{\link{lm}} and \code{\link{glm}} do.

  The \code{data} argument should rarely be needed, but in some cases

  \code{termplot} may be unable to reconstruct the original data

  frame. Using \code{na.action=na.exclude} makes these problems less likely.

  Nothing sensible happens for interaction terms, and they may cause errors.

  The \code{plot = FALSE} option is useful when some special action is needed,

  e.g.\sspace{}to overlay the results of two different models or to plot

  confidence bands.

}

\value{

  For \code{plot = FALSE}, a list with one element for each plot which

  would have been produced.  Each element of the list is a data frame

  with variables \code{x}, \code{y}, and optionally the pointwise

  standard errors \code{se}. For continuous predictors \code{x} will

  contain the ordered unique values and for a factor it will be a factor

  containing one instance of each level.  The list has attribute

  \code{"constant"} copied from the predicted terms object.

  Otherwise, the number of terms, invisibly.

}

\seealso{For (generalized) linear models, \code{\link{plot.lm}} and

  \code{\link{predict.glm}}.}

\examples{

require(graphics)

had.splines <- "package:splines" \%in\% search()

if(!had.splines) rs <- require(splines)

x <- 1:100

z <- factor(rep(LETTERS[1:4], 25))

y <- rnorm(100, sin(x/10)+as.numeric(z))

model <- glm(y ~ ns(x, 6) + z)

par(mfrow = c(2,2)) ## 2 x 2 plots for same model :

termplot(model, main = paste("termplot( ", deparse(model$call)," ...)"))

termplot(model, rug = TRUE)

termplot(model, partial.resid = TRUE, se = TRUE, main = TRUE)

termplot(model, partial.resid = TRUE, smooth = panel.smooth, span.smth = 1/4)

if(!had.splines && rs) detach("package:splines")

\donttest{## requires recommended package MASS

hills.lm <- lm(log(time) ~ log(climb)+log(dist), data = MASS::hills)

termplot(hills.lm, partial.resid = TRUE, smooth = panel.smooth,

        terms = "log(dist)", main = "Original")

termplot(hills.lm, transform.x = TRUE,

         partial.resid = TRUE, smooth = panel.smooth,

	 terms = "log(dist)", main = "Transformed")

}}

\keyword{hplot}

\keyword{regression}