Rename calc() to stat() (#2620)

Author: karawoo

NAMESPACE

@@ -240,7 +240,6 @@ export(autolayer)
 export(autoplot)
 export(benchplot)
 export(borders)
-export(calc)
 export(calc_element)
 export(combine_vars)
 export(continuous_scale)
@@ -504,6 +503,7 @@ export(scale_y_time)
 export(sec_axis)
 export(set_last_plot)
 export(should_stop)
+export(stat)
 export(stat_bin)
 export(stat_bin2d)
 export(stat_bin_2d)

NEWS.md

@@ -128,12 +128,12 @@
   informative error (#2400).
 
 * New syntax for calculated aesthetics. Instead of using `aes(y = ..count..)` 
-  you can (and should!) use `aes(y = calc(count))`. `calc()` is a real function 
+  you can (and should!) use `aes(y = stat(count))`. `stat()` is a real function 
   with documentation which hopefully will make this part of ggplot2 less 
   confusing (#2059).
 
-  `calc()` is particularly nice for more complex calculations because you 
-  only need to specify it once: `aes(y = calc(count / max(count)))`,
+  `stat()` is particularly nice for more complex calculations because you 
+  only need to specify it once: `aes(y = stat(count / max(count)))`,
   rather than `aes(y = ..count.. / max(..count..))`
 
 * New `tag` label for adding identification tags to plots, typically used for 

R/aes-calculated.r

@@ -4,9 +4,9 @@
 #' however, you want to map from variables computed by the aesthetic. The
 #' most common example of this is the height of bars in [geom_histogram()]:
 #' the height does not come from a variable in the underlying data, but
-#' is instead mapped to the `count` computed by [stat_bin()]. The `calc()`
-#' function is a flag to ggplot2 to it that you want to use
-#' __calculated__ aesthetics produced by the statistic.
+#' is instead mapped to the `count` computed by [stat_bin()]. The `stat()`
+#' function is a flag to ggplot2 to it that you want to use calculated
+#' aesthetics produced by the statistic.
 #'
 #' This replaces the older approach of surrounding the variable name with
 #' `..`.
@@ -16,12 +16,12 @@
 #' @examples
 #' # Default histogram display
 #' ggplot(mpg, aes(displ)) +
-#'   geom_histogram(aes(y = calc(count)))
+#'   geom_histogram(aes(y = stat(count)))
 #'
 #' # Scale tallest bin to 1
 #' ggplot(mpg, aes(displ)) +
-#'   geom_histogram(aes(y = calc(count / max(count))))
-calc <- function(x) {
+#'   geom_histogram(aes(y = stat(count / max(count))))
+stat <- function(x) {
   x
 }
 
@@ -43,7 +43,7 @@ is_calculated <- function(x) {
   } else if (is.symbol(x)) {
     is_dotted_var(as.character(x))
   } else if (is.call(x)) {
-    if (identical(x[[1]], quote(calc))) {
+    if (identical(x[[1]], quote(stat))) {
       TRUE
     } else {
       any(vapply(x, is_calculated, logical(1)))
@@ -67,7 +67,7 @@ strip_dots <- function(expr) {
       expr
     }
   } else if (is.call(expr)) {
-    if (identical(expr[[1]], quote(calc))) {
+    if (identical(expr[[1]], quote(stat))) {
       strip_dots(expr[[2]])
     } else {
       expr[-1] <- lapply(expr[-1], strip_dots)

R/aes-group-order.r

@@ -39,7 +39,7 @@
 #' f + geom_line(aes(linetype = variable))
 #'
 #' # Using facets
-#' k <- ggplot(diamonds, aes(carat, calc(density))) + geom_histogram(binwidth = 0.2)
+#' k <- ggplot(diamonds, aes(carat, stat(density))) + geom_histogram(binwidth = 0.2)
 #' k + facet_grid(. ~ cut)
 #'
 #' # There are three common cases where the default is not enough, and we

R/geom-contour.r

@@ -35,7 +35,7 @@
 #' v + geom_contour(binwidth = 0.001)
 #'
 #' # Other parameters
-#' v + geom_contour(aes(colour = calc(level)))
+#' v + geom_contour(aes(colour = stat(level)))
 #' v + geom_contour(colour = "red")
 #' v + geom_raster(aes(fill = density)) +
 #'   geom_contour(colour = "white")

R/geom-count.r

@@ -30,16 +30,16 @@
 #' # Specifying geom_count without a group identifier leads to a plot which is
 #' # not useful:
 #' d <- ggplot(diamonds, aes(x = cut, y = clarity))
-#' d + geom_count(aes(size = calc(prop)))
+#' d + geom_count(aes(size = stat(prop)))
 #' # To correct this problem and achieve a more desirable plot, we need
 #' # to specify which group the proportion is to be calculated over.
-#' d + geom_count(aes(size = calc(prop), group = 1)) +
+#' d + geom_count(aes(size = stat(prop), group = 1)) +
 #'   scale_size_area(max_size = 10)
 #'
 #' # Or group by x/y variables to have rows/columns sum to 1.
-#' d + geom_count(aes(size = calc(prop), group = cut)) +
+#' d + geom_count(aes(size = stat(prop), group = cut)) +
 #'   scale_size_area(max_size = 10)
-#' d + geom_count(aes(size = calc(prop), group = clarity)) +
+#' d + geom_count(aes(size = stat(prop), group = clarity)) +
 #'   scale_size_area(max_size = 10)
 geom_count <- function(mapping = NULL, data = NULL,
                        stat = "sum", position = "identity",

R/geom-density.r

@@ -38,11 +38,11 @@
 #' ggplot(diamonds, aes(carat, fill = cut)) +
 #'   geom_density(position = "stack")
 #' # Preserves marginal densities
-#' ggplot(diamonds, aes(carat, calc(count), fill = cut)) +
+#' ggplot(diamonds, aes(carat, stat(count), fill = cut)) +
 #'   geom_density(position = "stack")
 #'
 #' # You can use position="fill" to produce a conditional density estimate
-#' ggplot(diamonds, aes(carat, calc(count), fill = cut)) +
+#' ggplot(diamonds, aes(carat, stat(count), fill = cut)) +
 #'   geom_density(position = "fill")
 #' }
 geom_density <- function(mapping = NULL, data = NULL,

R/geom-density2d.r

@@ -21,7 +21,7 @@
 #'  ylim(40, 110)
 #' m + geom_density_2d()
 #' \donttest{
-#' m + stat_density_2d(aes(fill = calc(level)), geom = "polygon")
+#' m + stat_density_2d(aes(fill = stat(level)), geom = "polygon")
 #'
 #' set.seed(4393)
 #' dsmall <- diamonds[sample(nrow(diamonds), 1000), ]
@@ -31,9 +31,9 @@
 #' d + geom_density_2d(aes(colour = cut))
 #'
 #' # If we turn contouring off, we can use use geoms like tiles:
-#' d + stat_density_2d(geom = "raster", aes(fill = calc(density)), contour = FALSE)
+#' d + stat_density_2d(geom = "raster", aes(fill = stat(density)), contour = FALSE)
 #' # Or points:
-#' d + stat_density_2d(geom = "point", aes(size = calc(density)), n = 20, contour = FALSE)
+#' d + stat_density_2d(geom = "point", aes(size = stat(density)), n = 20, contour = FALSE)
 #' }
 geom_density_2d <- function(mapping = NULL, data = NULL,
                             stat = "density2d", position = "identity",

R/geom-histogram.r

@@ -41,7 +41,7 @@
 #'
 #' # To make it easier to compare distributions with very different counts,
 #' # put density on the y axis instead of the default count
-#' ggplot(diamonds, aes(price, calc(density), colour = cut)) +
+#' ggplot(diamonds, aes(price, stat(density), colour = cut)) +
 #'   geom_freqpoly(binwidth = 500)
 #'
 #' if (require("ggplot2movies")) {

R/geom-tile.r

@@ -48,11 +48,11 @@
 #' # Inspired by the image-density plots of Ken Knoblauch
 #' cars <- ggplot(mtcars, aes(mpg, factor(cyl)))
 #' cars + geom_point()
-#' cars + stat_bin2d(aes(fill = calc(count)), binwidth = c(3,1))
-#' cars + stat_bin2d(aes(fill = calc(density)), binwidth = c(3,1))
+#' cars + stat_bin2d(aes(fill = stat(count)), binwidth = c(3,1))
+#' cars + stat_bin2d(aes(fill = stat(density)), binwidth = c(3,1))
 #'
-#' cars + stat_density(aes(fill = calc(density)), geom = "raster", position = "identity")
-#' cars + stat_density(aes(fill = calc(count)), geom = "raster", position = "identity")
+#' cars + stat_density(aes(fill = stat(density)), geom = "raster", position = "identity")
+#' cars + stat_density(aes(fill = stat(count)), geom = "raster", position = "identity")
 #' }
 geom_tile <- function(mapping = NULL, data = NULL,
                       stat = "identity", position = "identity",