merge master into theme_geom

Merge remote-tracking branch 'upstream/master' into theme_geom

# Conflicts:
#	R/theme.r
#	man/element.Rd
#	man/theme.Rd

Author: dpseidel

NAMESPACE

@@ -507,6 +507,7 @@ export(scale_y_time)
 export(sec_axis)
 export(set_last_plot)
 export(should_stop)
+export(standardise_aes_names)
 export(stat)
 export(stat_bin)
 export(stat_bin2d)

NEWS.md

@@ -1,12 +1,34 @@
 # ggplot2 3.0.0.9000
 
+*   All `geom_*()` now display an informative error message when required 
+    aesthetics are missing (@dpseidel, #2637 and #2706).
+
+*   `sec_axis()` and `dup_axis()` now return appropriate breaks for the secondary
+    axis when applied to log transformed scales (@dpseidel, #2729).
+
+*   `sec_axis()` now works as expected when used in combination with tidy eval
+    (@dpseidel, #2788).
+
+*   `stat_contour()`, `stat_density2d()`, `stat_bin2d()`,  `stat_binhex()`
+    now calculate normalized statistics including `nlevel`, `ndensity`, and
+    `ncount`. Also, `stat_density()` now includes the calculated statistic 
+    `nlevel`, an alias for `scaled`, to better match the syntax of `stat_bin()`
+    (@bjreisman, #2679).
+
 *  `geom_hex()` now understands the `size` and `linetype` aesthetics
    (@mikmart, #2488).
 
 *   Data is no longer internally reordered when faceting. This makes it safer to
     feed data columns into `aes()` or into parameters of geoms or stats. However,
     doing so remains discouraged (@clauswilke).
+    
+*   `ggsave()` now exits without creating a new graphics device if previously
+    none was open (@clauswilke, #2363).
 
+*   Aesthetic names are now consistently standardised both in `aes()` and in the
+    `aesthetics` argument of scale functions. Also, the US spelling "color"
+    is now always internally converted to "colour", even when part of a longer
+    aesthetic name (e.g., `point_color`) (@clauswilke, #2649).
 
 # ggplot2 3.0.0
 

R/aes.r

@@ -7,9 +7,9 @@ NULL
 #' properties (aesthetics) of geoms. Aesthetic mappings can be set in
 #' [ggplot2()] and in individual layers.
 #'
-#' This function also standardises aesthetic names by performing partial
-#' matching, converting color to colour, and translating old style R names to
-#' ggplot names (e.g. pch to shape, cex to size).
+#' This function also standardises aesthetic names by converting `color` to `colour`
+#' (also in substrings, e.g. `point_color` to `point_colour`) and translating old style
+#' R names to ggplot names (eg. `pch` to `shape`, `cex` to `size`).
 #'
 #' @section Quasiquotation:
 #'
@@ -143,13 +143,34 @@ print.uneval <- function(x, ...) {
   new_aes(NextMethod())
 }
 
-# Rename American or old-style aesthetics name
-rename_aes <- function(x) {
-  # Convert prefixes to full names
-  full <- match(names(x), ggplot_global$all_aesthetics)
-  names(x)[!is.na(full)] <- ggplot_global$all_aesthetics[full[!is.na(full)]]
+#' Standardise aesthetic names
+#'
+#' This function standardises aesthetic names by converting `color` to `colour`
+#' (also in substrings, e.g. `point_color` to `point_colour`) and translating old style
+#' R names to ggplot names (eg. `pch` to `shape`, `cex` to `size`).
+#' @param x Character vector of aesthetics names, such as `c("colour", "size", "shape")`.
+#' @return Character vector of standardised names.
+#' @keywords internal
+#' @export
+standardise_aes_names <- function(x) {
+  # convert US to UK spelling of colour
+  x <- sub("color", "colour", x, fixed = TRUE)
 
-  plyr::rename(x, ggplot_global$base_to_ggplot, warn_missing = FALSE)
+  # convert old-style aesthetics names to ggplot version
+  plyr::revalue(x, ggplot_global$base_to_ggplot, warn_missing = FALSE)
+}
+
+# x is a list of aesthetic mappings, as generated by aes()
+rename_aes <- function(x) {
+  names(x) <- standardise_aes_names(names(x))
+  duplicated_names <- names(x)[duplicated(names(x))]
+  if (length(duplicated_names) > 0L) {
+    duplicated_message <- paste0(unique(duplicated_names), collapse = ", ")
+    warning(
+      "Duplicated aesthetics after name standardisation: ", duplicated_message, call. = FALSE
+    )
+  }
+  x
 }
 
 # Look up the scale that should be used for a given aesthetic

R/axis-secondary.R

@@ -106,10 +106,9 @@ AxisSecondary <- ggproto("AxisSecondary", NULL,
 
   transform_range = function(self, range) {
     range <- structure(data.frame(range), names = '.')
-    f_eval(self$trans, range)
+    rlang::eval_tidy(rlang::f_rhs(self$trans), data = range)
   },
 
-
   break_info = function(self, range, scale) {
     if (self$empty()) return()
 
@@ -125,29 +124,22 @@ AxisSecondary <- ggproto("AxisSecondary", NULL,
       stop("transformation for secondary axes must be monotonic")
 
     # Get break info for the secondary axis
-    new_range <- range(full_range, na.rm = TRUE)
-    temp_scale <- self$create_scale(new_range)
-    range_info <- temp_scale$break_info()
-
-    # Map the break values back to their correct position on the primary scale
-    old_val <- lapply(range_info$major_source, function(x) which.min(abs(full_range - x)))
-    old_val <- old_range[unlist(old_val)]
-    old_val_trans <- scale$trans$transform(old_val)
-    range_info$major[] <- round(rescale(scale$map(old_val_trans, range(old_val_trans)), from = range), digits = 3)
-
+    new_range <- range(scale$transform(full_range), na.rm = TRUE)
+    sec_scale <- self$create_scale(new_range, scale)
+    range_info <- sec_scale$break_info()
     names(range_info) <- paste0("sec.", names(range_info))
     range_info
   },
 
   # Temporary scale for the purpose of calling break_info()
-  create_scale = function(self, range) {
+  create_scale = function(self, range, primary) {
     scale <- ggproto(NULL, ScaleContinuousPosition,
       name = self$name,
       breaks = self$breaks,
       labels = self$labels,
       limits = range,
       expand = c(0, 0),
-      trans = identity_trans()
+      trans = primary$trans
     )
     scale$train(range)
     scale

R/facet-grid-.r

@@ -3,7 +3,7 @@ NULL
 
 #' Lay out panels in a grid
 #'
-#' `facet_grid` forms a matrix of panels defined by row and column
+#' `facet_grid()` forms a matrix of panels defined by row and column
 #' faceting variables. It is most useful when you have two discrete
 #' variables, and all combinations of the variables exist in the data.
 #'

R/geom-abline.r

@@ -25,9 +25,9 @@ NULL
 #' `size`. They also each have aesthetics that control the position of
 #' the line:
 #'
-#'   - `geom_vline`: `xintercept`
-#'   - `geom_hline`: `yintercept`
-#'   - `geom_abline`: `slope` and `intercept`
+#'   - `geom_vline()`: `xintercept`
+#'   - `geom_hline()`: `yintercept`
+#'   - `geom_abline()`: `slope` and `intercept`
 #'
 #' @seealso See [geom_segment()] for a more general approach to
 #'   adding straight line segments to a plot.

R/geom-boxplot.r

@@ -7,9 +7,9 @@
 #' @section Summary statistics:
 #' The lower and upper hinges correspond to the first and third quartiles
 #' (the 25th and 75th percentiles). This differs slightly from the method used
-#' by the `boxplot` function, and may be apparent with small samples.
+#' by the [boxplot()] function, and may be apparent with small samples.
 #' See [boxplot.stats()] for for more information on how hinge
-#' positions are calculated for `boxplot`.
+#' positions are calculated for [boxplot()].
 #'
 #' The upper whisker extends from the hinge to the largest value no further than
 #' 1.5 * IQR from the hinge (where IQR is the inter-quartile range, or distance
@@ -24,7 +24,7 @@
 #'
 #' @eval rd_aesthetics("geom", "boxplot")
 #'
-#' @seealso [geom_quantile()] for continuous x,
+#' @seealso [geom_quantile()] for continuous `x`,
 #'   [geom_violin()] for a richer display of the distribution, and
 #'   [geom_jitter()] for a useful technique for small data.
 #' @inheritParams layer
@@ -60,7 +60,6 @@
 #' @examples
 #' p <- ggplot(mpg, aes(class, hwy))
 #' p + geom_boxplot()
-#' p + geom_boxplot() + geom_jitter(width = 0.2)
 #' p + geom_boxplot() + coord_flip()
 #'
 #' p + geom_boxplot(notch = TRUE)
@@ -69,6 +68,8 @@
 #' # By default, outlier points match the colour of the box. Use
 #' # outlier.colour to override
 #' p + geom_boxplot(outlier.colour = "red", outlier.shape = 1)
+#' # Remove outliers when overlaying boxplot with original data points
+#' p + geom_boxplot(outlier.shape = NA) + geom_jitter(width = 0.2)
 #'
 #' # Boxplots are automatically dodged when any aesthetic is a factor
 #' p + geom_boxplot(aes(colour = drv))
@@ -79,6 +80,7 @@
 #'   geom_boxplot()
 #' ggplot(diamonds, aes(carat, price)) +
 #'   geom_boxplot(aes(group = cut_width(carat, 0.25)))
+#' # Adjust the transparency of outliers using outlier.alpha
 #' ggplot(diamonds, aes(carat, price)) +
 #'   geom_boxplot(aes(group = cut_width(carat, 0.25)), outlier.alpha = 0.1)
 #'

R/geom-density2d.r

@@ -30,6 +30,15 @@
 #' # set of contours for each value of that variable
 #' d + geom_density_2d(aes(colour = cut))
 #'
+#' # Similarly, if you apply faceting to the plot, contours will be
+#' # drawn for each facet, but the levels will calculated across all facets
+#' d + stat_density_2d(aes(fill = stat(level)), geom = "polygon") +
+#'   facet_grid(. ~ cut) + scale_fill_viridis_c()
+#' # To override this behavior (for instace, to better visualize the density
+#' # within each facet), use stat(nlevel)
+#' d + stat_density_2d(aes(fill = stat(nlevel)), geom = "polygon") +
+#'   facet_grid(. ~ cut) + scale_fill_viridis_c()
+#'
 #' # If we turn contouring off, we can use use geoms like tiles:
 #' d + stat_density_2d(geom = "raster", aes(fill = stat(density)), contour = FALSE)
 #' # Or points:

R/geom-histogram.r

@@ -2,28 +2,28 @@
 #'
 #' Visualise the distribution of a single continuous variable by dividing
 #' the x axis into bins and counting the number of observations in each bin.
-#' Histograms (`geom_histogram`) display the count with bars; frequency
-#' polygons (`geom_freqpoly`) display the counts with lines. Frequency
+#' Histograms (`geom_histogram()`) display the counts with bars; frequency
+#' polygons (`geom_freqpoly()`) display the counts with lines. Frequency
 #' polygons are more suitable when you want to compare the distribution
 #' across the levels of a categorical variable.
 #'
-#' `stat_bin` is suitable only for continuous x data. If your x data is
+#' `stat_bin()` is suitable only for continuous x data. If your x data is
 #' discrete, you probably want to use [stat_count()].
 #'
-#' By default, the underlying computation (`stat_bin`) uses 30 bins;
+#' By default, the underlying computation (`stat_bin()`) uses 30 bins;
 #' this is not a good default, but the idea is to get you experimenting with
 #' different bin widths. You may need to look at a few to uncover the full
 #' story behind your data.
 #'
 #' @section Aesthetics:
-#' `geom_histogram` uses the same aesthetics as [geom_bar()];
-#' `geom_freqpoly` uses the same aesthetics as [geom_line()].
+#' `geom_histogram()` uses the same aesthetics as [geom_bar()];
+#' `geom_freqpoly()` uses the same aesthetics as [geom_line()].
 #'
 #' @export
 #' @inheritParams layer
 #' @inheritParams geom_point
 #' @param geom,stat Use to override the default connection between
-#'   `geom_histogram`/`geom_freqpoly` and `stat_bin`.
+#'   `geom_histogram()`/`geom_freqpoly()` and `stat_bin()`.
 #' @examples
 #' ggplot(diamonds, aes(carat)) +
 #'   geom_histogram()

R/geom-point.r

@@ -5,11 +5,8 @@
 #' It can be used to compare one continuous and one categorical variable, or
 #' two categorical variables, but a variation like [geom_jitter()],
 #' [geom_count()], or [geom_bin2d()] is usually more
-#' appropriate.
-#'
-#' The \emph{bubblechart} is a scatterplot with a third variable mapped to
-#' the size of points. There are no special names for scatterplots where
-#' another variable is mapped to point shape or colour, however.
+#' appropriate. A _bubblechart_ is a scatterplot with a third variable
+#' mapped to the size of points.
 #'
 #' @section Overplotting:
 #' The biggest potential problem with a scatterplot is overplotting: whenever
@@ -47,6 +44,7 @@
 #' # Add aesthetic mappings
 #' p + geom_point(aes(colour = factor(cyl)))
 #' p + geom_point(aes(shape = factor(cyl)))
+#' # A "bubblechart":
 #' p + geom_point(aes(size = qsec))
 #'
 #' # Set aesthetics to fixed value

R/geom-smooth.r

@@ -1,22 +1,22 @@
 #' Smoothed conditional means
 #'
 #' Aids the eye in seeing patterns in the presence of overplotting.
-#' `geom_smooth` and `stat_smooth` are effectively aliases: they
-#' both use the same arguments. Use `geom_smooth` unless you want to
+#' `geom_smooth()` and `stat_smooth()` are effectively aliases: they
+#' both use the same arguments. Use `stat_smooth()` if you want to
 #' display the results with a non-standard geom.
 #'
 #' Calculation is performed by the (currently undocumented)
-#' `predictdf` generic and its methods.  For most methods the standard
+#' `predictdf()` generic and its methods.  For most methods the standard
 #' error bounds are computed using the [predict()] method -- the
-#' exceptions are `loess`, which uses a t-based approximation, and
-#' `glm`, where the normal confidence interval is constructed on the link
+#' exceptions are `loess()`, which uses a t-based approximation, and
+#' `glm()`, where the normal confidence interval is constructed on the link
 #' scale and then back-transformed to the response scale.
 #'
 #' @eval rd_aesthetics("geom", "smooth")
 #' @inheritParams layer
 #' @inheritParams geom_point
 #' @param geom,stat Use to override the default connection between
-#'   `geom_smooth` and `stat_smooth`.
+#'   `geom_smooth()` and `stat_smooth()`.
 #' @seealso See individual modelling functions for more details:
 #'   [lm()] for linear smooths,
 #'   [glm()] for generalised linear smooths, and

R/geom-text.r

@@ -1,6 +1,6 @@
 #' Text
 #'
-#' `geom_text` adds text directly to the plot. `geom_label` draws
+#' `geom_text()` adds text directly to the plot. `geom_label()` draws
 #' a rectangle behind the text, making it easier to read.
 #'
 #' Note that the "width" and "height" of a text element are 0, so stacking
@@ -10,16 +10,16 @@
 #' space they occupy on the plot is not constant in data units: when you
 #' resize a plot, labels stay the same size, but the size of the axes changes.
 #'
-#' `geom_text` and `geom_label` both add a label for each row in the
+#' `geom_text()` and `geom_label()` add labels for each row in the
 #' data, even if coordinates x, y are set to single values in the call
-#' to `geom_label` or `geom_text`.
+#' to `geom_label()` or `geom_text()`.
 #' To add labels at specified points use [annotate()] with
 #' `annotate(geom = "text", ...)` or `annotate(geom = "label", ...)`.
 #'
 #' @eval rd_aesthetics("geom", "text")
-#' @section `geom_label`:
-#' Currently `geom_label` does not support the `rot` parameter and
-#' is considerably slower than `geom_text`. The `fill` aesthetic
+#' @section `geom_label()`:
+#' Currently `geom_label()` does not support the `angle` aesthetic and
+#' is considerably slower than `geom_text()`. The `fill` aesthetic
 #' controls the background colour of the label.
 #'
 #' @section Alignment:

R/guide-colorbar.r

@@ -218,7 +218,7 @@ guide_train.colorbar <- function(guide, scale, aesthetic = NULL) {
 
   # bar specification (number of divs etc)
   .limits <- scale$get_limits()
-  .bar <- seq(.limits[1], .limits[2], length = guide$nbin)
+  .bar <- seq(.limits[1], .limits[2], length.out = guide$nbin)
   if (length(.bar) == 0) {
     .bar = unique(.limits)
   }

R/guide-legend.r

@@ -57,7 +57,6 @@
 #'   multiple guides are displayed, not the contents of the guide itself.
 #'   If 0 (default), the order is determined by a secret algorithm.
 #' @param ... ignored.
-#' @return A guide object
 #' @export
 #' @family guides
 #' @examples

R/labels.r

@@ -19,14 +19,15 @@ update_labels <- function(p, labels) {
 #' Modify axis, legend, and plot labels
 #'
 #' Good labels are critical for making your plots accessible to a wider
-#' audience. Ensure the axis and legend labels display the full variable name.
-#' Use the plot `title` and `subtitle` to explain the main findings.
-#' It's common to use the `caption` to provide information about the
-#' data source. `tag` can be used for adding identification tags.
+#' audience. Always ensure the axis and legend labels display the full
+#' variable name. Use the plot `title` and `subtitle` to explain the
+#' main findings. It's common to use the `caption` to provide information
+#' about the data source. `tag` can be used for adding identification tags
+#' to differentiate between multiple plots.
 #'
 #' You can also set axis and legend labels in the individual scales (using
-#' the first argument, the `name`). I recommend doing that if you're
-#' changing other scale options.
+#' the first argument, the `name`). If you're changing other scale options, this
+#' is recommended.
 #'
 #' @param label The text for the axis, plot title or caption below the plot.
 #' @param subtitle the text for the subtitle for the plot which will be