The R Project SVN R

% File src/library/graphics/man/plotformula.Rd

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

% Copyright 1995--2014 R Core Team

% Distributed under GPL 2 or later

\name{plot.formula}

\alias{plot.formula}

\alias{lines.formula}

\alias{points.formula}

\alias{text.formula}

\title{Formula Notation for Scatterplots}

\description{

  Specify a scatterplot or add points, lines, or text via a formula.

}

\usage{

\method{plot}{formula}(formula, data = parent.frame(), \dots, subset,

             ylab = varnames[response], ask = dev.interactive())

\method{points}{formula}(formula, data = parent.frame(), \dots, subset)

\method{lines}{formula}(formula, data = parent.frame(), \dots, subset)

\method{text}{formula}(formula, data = parent.frame(), \dots, subset)

}

\arguments{

  \item{formula}{a \code{\link{formula}}, such as \code{y ~ x}.}

  \item{data}{a data.frame (or list) from which the variables in

    \code{formula} should be taken.  A matrix is converted to a data frame.}

  \item{\dots}{Arguments to be passed to or from other methods.

    \code{horizontal = TRUE} is also accepted.}

  \item{subset}{an optional vector specifying a subset of observations

    to be used in the fitting process.}

  \item{ylab}{the y label of the plot(s).}

  \item{ask}{logical, see \code{\link{par}}.}

}

\details{

  For the \code{lines}, \code{points} and \code{text} methods the formula

  should be of the form \code{y ~ x} or \code{y ~ 1} with a left-hand

  side and a single term on the right-hand side.  The \code{plot} method

  accepts other forms discussed later in this section.

  Both the terms in the formula and the \code{\dots} arguments are

  evaluated in \code{data} enclosed in \code{parent.frame()} if

  \code{data} is a list or a data frame.  The terms of the formula and

  those arguments in \code{\dots} that are of the same length as

  \code{data} are subjected to the subsetting specified in

  \code{subset}.  A plot against the running index can be specified as

  \code{plot(y ~ 1)}.

  If the formula in the \code{plot} method contains more than one term

  on the right-hand side, a series of plots is produced of the response

  against each non-response term.

  For the \code{plot} method the formula can be of the form

  \code{~ z + y + z}: the variables specified on the right-hand side are

  collected into a data frame, subsetted if specified, and displayed by

  \code{\link{plot.data.frame}}.

  Missing values are not considered in these methods, and in particular

  cases with missing values are not removed.

  If \code{y} is an object (i.e., has a \code{\link{class}} attribute)

  then \code{plot.formula} looks for a plot method for that class first.

  Otherwise, the class of \code{x} will determine the type of the plot.

  For factors this will be a parallel boxplot, and argument

  \code{horizontal = TRUE} can be specified (see \code{\link{boxplot}}).

  Note that some arguments will need to be protected from premature

  evaluation by enclosing them in \code{\link{quote}}: currently this is

  done automatically for \code{main}, \code{sub} and \code{xlab}.  For

  example, it is needed for the \code{panel.first} and \code{panel.last}

  arguments passed to \code{\link{plot.default}}.

}

\value{

  These functions are invoked for their side effect of drawing

  on the active graphics device.

}

\seealso{

  \code{\link{plot.default}}, \code{\link{points}}, \code{\link{lines}},

  \code{\link{plot.factor}}.

}

\examples{

op <- par(mfrow = c(2,1))

plot(Ozone ~ Wind, data = airquality, pch = as.character(Month))

plot(Ozone ~ Wind, data = airquality, pch = as.character(Month),

     subset = Month != 7)

par(op)

## text.formula() can be very natural:

wb <- within(warpbreaks, {

    time <- seq_along(breaks); W.T <- wool:tension })

plot(breaks ~ time, data = wb, type = "b")

text(breaks ~ time, data = wb, labels = W.T, col = 1+as.integer(wool))

}

\keyword{hplot}% plot

\keyword{aplot}% points, etc