with                  package:base                  R Documentation

_E_v_a_l_u_a_t_e _a_n _E_x_p_r_e_s_s_i_o_n _i_n _a _D_a_t_a _E_n_v_i_r_o_n_m_e_n_t

_D_e_s_c_r_i_p_t_i_o_n:

     Evaluate an R expression in an environment constructed from data,
     possibly modifying the original data.

_U_s_a_g_e:

     with(data, expr, ...)
     within(data, expr, ...)

_A_r_g_u_m_e_n_t_s:

    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.

     ...: arguments to be passed to future methods.

_D_e_t_a_i_l_s:

     '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 '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'.

_V_a_l_u_e:

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

_S_e_e _A_l_s_o:

     'evalq', 'attach', 'assign', 'transform'.

_E_x_a_m_p_l_e_s:

     require(stats); require(graphics)
     #examples from glm:
     ## Not run: 
     library(MASS)
     with(anorexia, {
         anorex.1 <- glm(Postwt ~ Prewt + Treat + offset(Prewt),
                         family = gaussian)
         summary(anorex.1)
     })
     ## End(Not run)


     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
         rm(Day, Temp)
     })
     head(aq)

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

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