src/library/base/man/with.Rd

% File src/library/base/man/with.Rd
% Part of the R package, https://www.R-project.org
% Copyright 1995-2017 R Core Team
% Distributed under GPL 2 or later

\name{with}
\alias{with}
\alias{with.default}
\alias{within}
\alias{within.list}
\alias{within.data.frame}
\title{Evaluate an Expression in a Data Environment}
\description{
  Evaluate an \R expression in an environment constructed from data,
  possibly modifying (a copy of) the original data.
}
\usage{
with(data, expr, \dots)
within(data, expr, \dots)
\S3method{within}{list}(data, expr, keepAttrs = TRUE, \dots)
}
\arguments{
  \item{data}{data to use for constructing an environment. For the
    default \code{with} method this may be an environment, a list, a
    data frame, or an integer as in \code{sys.call}. For \code{within},
    it can be a list or a data frame.}
  \item{expr}{expression to evaluate; particularly for \code{within()}
    often a \dQuote{compound} expression, i.e., of the form \preformatted{   {
     a <- somefun()
     b <- otherfun()
     .....
     rm(unused1, temp)
   }
}}
  \item{keepAttrs}{for the \code{\link{list}} method of \code{within()},
    a \code{\link{logical}} specifying if the resulting list should keep
    the \code{\link{attributes}} from \code{data} and have its
    \code{\link{names}} in the same order.  Often this is unneeded as
    the result is a \emph{named} list anyway, and then \code{keepAttrs =
      FALSE} is more efficient.}
  \item{\dots}{arguments to be passed to (future) methods.}
}
\details{
  \code{with} is a generic function that evaluates \code{expr} in a
  local environment constructed from \code{data}.  The environment has
  the caller's environment as its parent.  This is useful for
  simplifying calls to modeling functions.  (Note: if \code{data} is
  already an environment then this is used with its existing parent.)

  Note that assignments within \code{expr} take place in the constructed
  environment and not in the user's workspace.

  \code{within} is similar, except that it examines the environment
  after the evaluation of \code{expr} and makes the corresponding
  modifications to a copy of \code{data} (this may fail in the data
  frame case if objects are created which cannot be stored in a data
  frame), and returns it.  \code{within} can be used as an alternative
  to \code{transform}.
}
\note{
  For \emph{interactive} use this is very effective and nice to read.  For
  \emph{programming} however, i.e., in one's functions, more care is
  needed, and typically one should refrain from using \code{with()}, as,
  e.g., variables in \code{data} may accidentally override local
  variables, see the reference.

  Further, when using modeling or graphics functions with an explicit
  \code{data} argument (and typically using \code{\link{formula}}s),
  it is typically preferred to use the \code{data} argument of that
  function rather than to use \code{with(data, ...)}.
}
\value{
  For \code{with}, the value of the evaluated \code{expr}.  For
  \code{within}, the modified object.
}
\seealso{
  \code{\link{evalq}}, \code{\link{attach}}, \code{\link{assign}},
  \code{\link{transform}}.
}
\references{
  Thomas Lumley (2003)  \emph{Standard nonstandard evaluation rules}.
  \url{http://developer.r-project.org/nonstandard-eval.pdf}
}
\examples{
with(mtcars, mpg[cyl == 8  &  disp > 350])
    # is the same as, but nicer than
mtcars$mpg[mtcars$cyl == 8  &  mtcars$disp > 350]

require(stats); require(graphics)

# examples from glm:
with(data.frame(u = c(5,10,15,20,30,40,60,80,100),
                lot1 = c(118,58,42,35,27,25,21,19,18),
                lot2 = c(69,35,26,21,18,16,13,12,12)),
    list(summary(glm(lot1 ~ log(u), family = Gamma)),
         summary(glm(lot2 ~ log(u), family = Gamma))))

aq <- within(airquality, {     # Notice that multiple vars can be changed
    lOzone <- log(Ozone)
    Month <- factor(month.abb[Month])
    cTemp <- round((Temp - 32) * 5/9, 1) # From Fahrenheit to Celsius
    S.cT <- Solar.R / cTemp  # using the newly created variable
    rm(Day, Temp)
})
head(aq)




# example from boxplot:
with(ToothGrowth, {
    boxplot(len ~ dose, boxwex = 0.25, at = 1:3 - 0.2,
            subset = (supp == "VC"), col = "yellow",
            main = "Guinea Pigs' Tooth Growth",
            xlab = "Vitamin C dose mg",
            ylab = "tooth length", ylim = c(0, 35))
    boxplot(len ~ dose, add = TRUE, boxwex = 0.25, at = 1:3 + 0.2,
            subset = supp == "OJ", col = "orange")
    legend(2, 9, c("Ascorbic acid", "Orange juice"),
           fill = c("yellow", "orange"))
})

# alternate form that avoids subset argument:
with(subset(ToothGrowth, supp == "VC"),
     boxplot(len ~ dose, boxwex = 0.25, at = 1:3 - 0.2,
             col = "yellow", main = "Guinea Pigs' Tooth Growth",
             xlab = "Vitamin C dose mg",
             ylab = "tooth length", ylim = c(0, 35)))
with(subset(ToothGrowth,  supp == "OJ"),
     boxplot(len ~ dose, add = TRUE, boxwex = 0.25, at = 1:3 + 0.2,
             col = "orange"))
legend(2, 9, c("Ascorbic acid", "Orange juice"),
       fill = c("yellow", "orange"))
}
\keyword{data}
\keyword{programming}