Adopt suggestions of #5590 (#5721)

* document `Stat$dropped_aes`

* replace `stat()` with `after_stat()`

* tweak ggproto docs

R/ggproto.R

@@ -27,12 +27,20 @@
 #' To explicitly call a methods in a parent, use
 #' `ggproto_parent(Parent, self)`.
 #'
+#' @section Working with ggproto classes:
+#' The ggproto objects constructed are build on top of environments, which has
+#' some ramifications. Environments do not follow the 'copy on modify' semantics
+#' one might be accustomed to in regular objects. Instead they have
+#' ['modify in place'](https://adv-r.hadley.nz/names-values.html#env-modify)
+#' semantics.
+#'
 #' @param _class Class name to assign to the object. This is stored as the class
 #' attribute of the object. This is optional: if `NULL` (the default),
 #' no class name will be added to the object.
 #' @param _inherit ggproto object to inherit from. If `NULL`, don't
 #' inherit from any object.
-#' @param ... A list of members in the ggproto object.
+#' @param ... A list of named members in the ggproto object. These can be
+#' functions that become methods of the class or regular objects.
 #' @seealso
 #' The `r link_book("ggproto introduction section", "internals#sec-ggproto")`
 #' @export

R/stat-.R

@@ -45,6 +45,9 @@
 #' render the geom.
 #' - `default_aes`: A list (generated by [aes()] of
 #' default values for aesthetics.
+#' - `dropped_aes` is a vecor of aesthetic names that are safe to drop after
+#' statistical transformation. A classic example is the `weight` aesthetic
+#' that is consumed during computation of the stat.
 #'
 #' See also the `r link_book("new stats section", "extensions#sec-new-stats")`
 #' @rdname ggplot2-ggproto

vignettes/extending-ggplot2.Rmd

@@ -284,15 +284,15 @@ This stat illustrates another important point. If we want to make this stat usab
 #| the kernel density estimate of the displacement."
 StatDensityCommon <- ggproto("StatDensity2", Stat, 
  required_aes = "x",
- default_aes = aes(y = stat(density)),
+ default_aes = aes(y = after_stat(density)),
 
  compute_group = function(data, scales, bandwidth = 1) {
  d <- density(data$x, bw = bandwidth)
  data.frame(x = d$x, density = d$y)
  } 
 )
 
-ggplot(mpg, aes(displ, drv, colour = stat(density))) + 
+ggplot(mpg, aes(displ, drv, colour = after_stat(density))) + 
  stat_density_common(bandwidth = 1, geom = "point")
 ```
 
@@ -322,7 +322,7 @@ This is because each density is computed independently, and the estimated `x`s d
 #| )
 StatDensityCommon <- ggproto("StatDensityCommon", Stat, 
  required_aes = "x",
- default_aes = aes(y = stat(density)),
+ default_aes = aes(y = after_stat(density)),
 
  setup_params = function(data, params) {
  min <- min(data$x) - 3 * params$bandwidth
@@ -344,7 +344,7 @@ StatDensityCommon <- ggproto("StatDensityCommon", Stat,
 
 ggplot(mpg, aes(displ, fill = drv)) + 
  stat_density_common(bandwidth = 1, geom = "area", position = "stack")
-ggplot(mpg, aes(displ, drv, fill = stat(density))) + 
+ggplot(mpg, aes(displ, drv, fill = after_stat(density))) + 
  stat_density_common(bandwidth = 1, geom = "raster")
 ```