dplyr: whats the difference between group_by and group_by_ functions?

Question

I can't figure out what the underscore-based function is for the group_by_() function.

From the group_by help:

by_cyl <- group_by(mtcars, cyl)  
summarise(by_cyl, mean(disp), mean(hp))  

yields the expected:

Source: local data frame [3 x 3]  
    cyl mean(disp)  mean(hp)
1   4   105.1364  82.63636
2   6   183.3143 122.28571
3   8   353.1000 209.21429

but this:

by_cyl <- group_by_(mtcars, cyl)  

yields an error:

"Error in as.lazy_dots(list(...)) : object 'cyl' not found"  

So my question is what does the underscore version do? And also, under what circumstances would I want to use it, rather than the "regular" one?

Thanks

Answer 1

The dplyr Non-Standard Evaluation vignette helps here: http://cran.r-project.org/web/packages/dplyr/vignettes/nse.html

Note: the above link is now out of date, but the same information can be found on the github page for the package. https://github.com/tidyverse/dplyr/blob/34423af89703b0772d59edcd0f3485295b629ab0/vignettes/nse.Rmd

Dplyr uses non-standard evaluation (NSE) in all of the most important single table verbs: filter(), mutate(), summarise(), arrange(), select() and group_by(). NSE is important not only to save you typing, but for database backends, is what makes it possible to translate your R code to SQL. However, while NSE is great for interactive use it’s hard to program with. This vignette describes how you can opt out of NSE in dplyr, and instead rely only on SE (along with a little quoting).

...

Every function in dplyr that uses NSE also has a version that uses SE. There’s a consistent naming scheme: the SE is the NSE name with _ on the end. For example, the SE version of summarise() is summarise_(), the SE version of arrange() is arrange_(). These functions work very similarly to their NSE cousins, but the inputs must be “quoted”