Vignette on using ggplot2 within a package

[paleolimbot]

@jennybc suggested this recently, since there are several usage patterns that repeatedly cause problems in revdepchecks. A couple of ideas from this set of revdep issues:

• How to map columns without triggering a CMD check error (right now people are using annotate() (Annotation breaks with facets #3305, Annotations with zero-length aesthetics are broken #3317) and passing data directly to aes() or outside of aes() (geom_ribbon() now errors when ymin and ymax aesthetics are set rather than mapped #3318)
• How to specify facet variables without triggering a CMD check error
• How to define a new theme (see Some themes in downstream packages are currently not valid #3310)
• How to test ggplot2 output (see Some tests in downstream packages that use the ggplot object fail #3311)

[clauswilke]

Yes, I fully agree. On themes: I think it's always good practice to start with an existing theme (e.g. theme_grey()) and then %+replace% the elements that should be changed. This is the right strategy even if seemingly all elements are replaced.

Incidentally, theme_void() in ggplot2 does not use this strategy and this has caused (and to some extent continues to cause) bugs.

[paleolimbot]

I'm in the process of writing this now, and I'm curious as to the best way to recommend aes() and vars() usage in packages. Related are issues #2689 and #2693. As far as I can tell, there are three cases:

(1) The column name/expression is known in advance by the developer and never changes:

library(ggplot2)
# col_name is always "class"

# aes()

aes(class) # with utils::globalVariables("class")
aes(.data$class)
aes(.data[["class"]])

# these work but are discouraged?
aes(mpg$class) # bad use of extraction (#2693)
aes(mpg[["class"]]) # bad use of extraction (#2693)
aes_string("class")
aes_(as.name("class"))

# vars()

vars(class) # with utils::globalVariables("class")
vars(.data$class) # fails with annotation layers (#2689)
vars(!!sym("class"))
vars(.data[["class"]]) # fails with annotation layers (#2689)

# these work but are discouraged?
"class"
~class # with utils::globalVariables("class")
vars(mpg$class) # fails with annotation layers (#2689), bad use of extraction (#2693)
vars(mpg[["class"]]) # fails with annotation layers (#2689), bad use of extraction (#2693)

(2) The column name is known but is contained in a variable that refers to a column name (as a character vector):

library(ggplot2)
col_name <- "class"

# aes()

# I think these will both always work
aes(!!sym(col_name))
aes(.data[[!!col_name]])

# these work but are discouraged?
aes(mpg[[col_name]]) # bad use of extraction (#2693)
aes_string(col_name)
aes_(as.name(col_name))

# vars()

# this always works
vars(!!sym(col_name))

# this fails with annotation layers (#2689)
vars(.data[[!!col_name]]) 

# these work but are discouraged?
col_name
~.data[[col_name]]
~mpg[[col_name]] # bad use of extraction (#2693)
vars(mpg[[col_name]]) # bad use of extraction (#2693)

(3) One or more column names/expressions is supplied by the user, and the developer would like to allow the user to use NSE. This is the place for full-on tidy eval, and there's already a good blog post about using it with ggplot2, although there's a few variations:

library(ggplot2)

# this is the version used by the blog post
ggfun1 <- function(col_expr) {
  col_expr <- enquo(col_expr)
  aes(!!col_expr)
}
ggfun1(class)

ggfun2 <- function(col_expr) {
  aes(!!enquo(col_expr))
}
ggfun2(class)

# in development rlang
ggfun3 <- function(col_expr) {
  aes({{col_expr}})
}
ggfun3(class)

[lock]

This old issue has been automatically locked. If you believe you have found a related problem, please file a new issue (with reprex) and link to this issue. https://reprex.tidyverse.org/