with {base} | R Documentation

## 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, ...)
    within(data, expr, ...)
    ## S3 method for class 'list'
    within(data, expr, keepAttrs = TRUE, ...)

### Arguments

`data` | data to use for constructing an environment. For the default `with` method this may be an environment, a list, a data frame, or an integer as in `sys.call`. For `within`, it can be a list or a data frame.
`expr` | expression to evaluate; particularly for `within()` often a “compound” expression, i.e., of the form
       {
         a <- somefun()
         b <- otherfun()
         .....
         rm(unused1, temp)
       }
`keepAttrs` | for the `list` method of `within()`, a `logical` specifying if the resulting list should keep the `attributes` from `data` and have its `names` in the same order. Often this is unneeded as the result is a named list anyway, and then `keepAttrs = FALSE` is more efficient.
`...` | arguments to be passed to (future) methods.

### Details

`with` is a generic function that evaluates `expr` in a local environment constructed from `data`. The environment has the caller's environment as its parent. This is useful for simplifying calls to modeling functions. (Note: if `data` is already an environment then this is used with its existing parent.)

Note that assignments within `expr` take place in the constructed environment and not in the user's workspace.

`within` is similar, except that it examines the environment after the evaluation of `expr` and makes the corresponding modifications to a copy of `data` (this may fail in the data frame case if objects are created which cannot be stored in a data frame), and returns it. `within` can be used as an alternative to `transform`.

### Value

For `with`, the value of the evaluated `expr`. For `within`, the modified object.

### Note

For interactive use this is very effective and nice to read. For programming however, i.e., in one's functions, more care is needed, and typically one should refrain from using `with()`, as, e.g., variables in `data` may accidentally override local variables, see the reference.

Further, when using modeling or graphics functions with an explicit `data` argument (and typically using `formula`s), it is typically preferred to use the `data` argument of that function rather than to use `with(data, ...)`.

### References

Thomas Lumley (2003) Standard nonstandard evaluation rules. http://developer.r-project.org/nonstandard-eval.pdf

### See Also

`evalq`, `attach`, `assign`, `transform`.

### 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"))

[Package base version 3.6.1 Index]