Merge branch 'master' into v3.3.0-rc

Author: thomasp85

DESCRIPTION

@@ -1,5 +1,5 @@
 Package: ggplot2
-Version: 3.3.0
+Version: 3.3.0.9000
 Title: Create Elegant Data Visualisations Using the Grammar of Graphics
 Description: A system for 'declaratively' creating graphics,
     based on "The Grammar of Graphics". You provide the data, tell 'ggplot2'

NEWS.md

@@ -1,3 +1,9 @@
+* `annotation_raster()` adds support for native rasters. For large rasters,
+  native rasters render significantly faster than arrays (@kent37, #3388)
+  
+* Support graphics devices that use the `file` argument instead of `fileneame` 
+  in `ggsave()` (@bwiernik, #3810)
+
 # ggplot2 3.3.0
 
 This is a minor release but does contain a range of substantial new features, 
@@ -372,7 +378,10 @@ as the tidyverse is committed to support 5 major versions of R.
 
 ## Breaking changes
 
-This is a minor release and breaking changes have been kept to a minimum. End users of ggplot2 are unlikely to encounter any issues. However, there are a few items that developers of ggplot2 extensions should be aware of. For additional details, see also the discussion accompanying issue #2890.
+This is a minor release and breaking changes have been kept to a minimum. End users of 
+ggplot2 are unlikely to encounter any issues. However, there are a few items that developers 
+of ggplot2 extensions should be aware of. For additional details, see also the discussion 
+accompanying issue #2890.
 
 *   In non-user-facing internal code (specifically in the `aes()` function and in
     the `aesthetics` argument of scale functions), ggplot2 now always uses the British
@@ -972,25 +981,45 @@ This is a minor release and breaking changes have been kept to a minimum. End us
 
 ### Subtitle and caption
 
-Thanks to @hrbrmstr plots now have subtitles and captions, which can be set with the `subtitle`  and `caption` arguments to `ggtitle()` and `labs()`. You can control their appearance with the theme settings `plot.caption` and `plot.subtitle`. The main plot title is now left-aligned to better work better with a subtitle. The caption is right-aligned (@hrbrmstr).
+Thanks to @hrbrmstr plots now have subtitles and captions, which can be set with 
+the `subtitle`  and `caption` arguments to `ggtitle()` and `labs()`. You can 
+control their appearance with the theme settings `plot.caption` and 
+`plot.subtitle`. The main plot title is now left-aligned to better work better 
+with a subtitle. The caption is right-aligned (@hrbrmstr).
 
 ### Stacking
 
-`position_stack()` and `position_fill()` now sort the stacking order to match grouping order. This allows you to control the order through grouping, and ensures that the default legend matches the plot (#1552, #1593). If you want the opposite order (useful if you have horizontal bars and horizontal legend), you can request reverse stacking by using `position = position_stack(reverse = TRUE)` (#1837).
+`position_stack()` and `position_fill()` now sort the stacking order to match 
+grouping order. This allows you to control the order through grouping, and 
+ensures that the default legend matches the plot (#1552, #1593). If you want the 
+opposite order (useful if you have horizontal bars and horizontal legend), you 
+can request reverse stacking by using `position = position_stack(reverse = TRUE)` 
+(#1837).
   
-`position_stack()` and `position_fill()` now accepts negative values which will create stacks extending below the x-axis (#1691).
+`position_stack()` and `position_fill()` now accepts negative values which will 
+create stacks extending below the x-axis (#1691).
 
-`position_stack()` and `position_fill()` gain a `vjust` argument which makes it easy to (e.g.) display labels in the middle of stacked bars (#1821).
+`position_stack()` and `position_fill()` gain a `vjust` argument which makes it 
+easy to (e.g.) display labels in the middle of stacked bars (#1821).
 
 ### Layers
 
-`geom_col()` was added to complement `geom_bar()` (@hrbrmstr). It uses `stat="identity"` by default, making the `y` aesthetic mandatory. It does not support any other `stat_()` and does not provide fallback support for the `binwidth` parameter. Examples and references in other functions were updated to demonstrate `geom_col()` usage. 
+`geom_col()` was added to complement `geom_bar()` (@hrbrmstr). It uses 
+`stat="identity"` by default, making the `y` aesthetic mandatory. It does not 
+support any other `stat_()` and does not provide fallback support for the 
+`binwidth` parameter. Examples and references in other functions were updated to
+demonstrate `geom_col()` usage. 
 
-When creating a layer, ggplot2 will warn if you use an unknown aesthetic or an unknown parameter. Compared to the previous version, this is stricter for aesthetics (previously there was no message), and less strict for parameters (previously this threw an error) (#1585).
+When creating a layer, ggplot2 will warn if you use an unknown aesthetic or an 
+unknown parameter. Compared to the previous version, this is stricter for 
+aesthetics (previously there was no message), and less strict for parameters 
+(previously this threw an error) (#1585).
 
 ### Facetting
 
-The facet system, as well as the internal panel class, has been rewritten in ggproto. Facets are now extendable in the same manner as geoms and stats, as described in `vignette("extending-ggplot2")`.
+The facet system, as well as the internal panel class, has been rewritten in 
+ggproto. Facets are now extendable in the same manner as geoms and stats, as 
+described in `vignette("extending-ggplot2")`.
 
 We have also added the following new fatures.
   
@@ -1012,7 +1041,10 @@ We have also added the following new fatures.
 
 ### Extensions
 
-Unfortunately there was a major oversight in the construction of ggproto which lead to extensions capturing the super object at package build time, instead of at package run time (#1826). This problem has been fixed, but requires re-installation of all extension packages.
+Unfortunately there was a major oversight in the construction of ggproto which 
+lead to extensions capturing the super object at package build time, instead of 
+at package run time (#1826). This problem has been fixed, but requires 
+re-installation of all extension packages.
 
 ## Scales
 
@@ -1047,7 +1079,10 @@ Unfortunately there was a major oversight in the construction of ggproto which l
 
 ### Discrete scales
 
-The treatment of missing values by discrete scales has been thoroughly overhauled (#1584). The underlying principle is that we can naturally represent missing values on discrete variables (by treating just like another level), so by default we should. 
+The treatment of missing values by discrete scales has been thoroughly 
+overhauled (#1584). The underlying principle is that we can naturally represent 
+missing values on discrete variables (by treating just like another level), so 
+by default we should. 
 
 This principle applies to:
 
@@ -1378,7 +1413,8 @@ There were a number of tweaks to the theme elements that control legends:
 
 ### Extensibility
 
-There is now an official mechanism for defining Stats, Geoms, and Positions in other packages. See `vignette("extending-ggplot2")` for details.
+There is now an official mechanism for defining Stats, Geoms, and Positions in 
+other packages. See `vignette("extending-ggplot2")` for details.
 
 * All Geoms, Stats and Positions are now exported, so you can inherit from them
   when making your own objects (#989).
@@ -1449,7 +1485,7 @@ A number of geoms have been renamed to be internally consistent:
   to `geom_density_2d()`/`stat_density_2d()`.
 
 * `stat_spoke()` is now `geom_spoke()` since I realised it's a
-  reparameterisation of `geom_segment().
+  reparameterisation of `geom_segment()`.
 
 * `stat_bindot()` has been removed because it's so tightly coupled to
   `geom_dotplot()`. If you happened to use `stat_bindot()`, just change to
@@ -1618,7 +1654,7 @@ version of ggplot.
 
     *  `geom_smooth()` gains explicit `method`, `se` and `formula` arguments.
 
-    * `geom_histogram()` gains `binwidth`, `bins`, origin` and `right` 
+    * `geom_histogram()` gains `binwidth`, `bins`, `origin` and `right` 
       arguments.
 
     * `geom_jitter()` gains `width` and `height` arguments to make it easier

R/aes.r

@@ -226,7 +226,7 @@ is_position_aes <- function(vars) {
 #' [substitute()] to generate a call to `aes()`.
 #'
 #' I recommend using `aes_()`, because creating the equivalents of
-#' `aes(colour = "my colour")` or \code{aes{x = `X$1`}}
+#' `aes(colour = "my colour")` or \code{aes(x = `X$1`)}
 #' with `aes_string()` is quite clunky.
 #'
 #'

R/annotation-raster.r

@@ -10,7 +10,7 @@ NULL
 #' of the raster, and the raster must already have its own colours). This
 #' is useful for adding bitmap images.
 #'
-#' @param raster raster object to display
+#' @param raster raster object to display, may be an `array` or a `nativeRaster`
 #' @param xmin,xmax x location (in data coordinates) giving horizontal
 #'   location of raster
 #' @param ymin,ymax y location (in data coordinates) giving vertical
@@ -39,7 +39,8 @@ NULL
 #'   geom_point()
 annotation_raster <- function(raster, xmin, xmax, ymin, ymax,
                               interpolate = FALSE) {
-  raster <- grDevices::as.raster(raster)
+  if (!inherits(raster, 'nativeRaster'))
+    raster <- grDevices::as.raster(raster)
 
   layer(
     data = dummy_data(),

R/geom-bar.r

@@ -1,23 +1,28 @@
 #' Bar charts
 #'
 #' There are two types of bar charts: `geom_bar()` and `geom_col()`.
-#' `geom_bar()` makes the height of the
-#' bar proportional to the number of cases in each group (or if the
-#' `weight` aesthetic is supplied, the sum of the weights). If you want the
-#' heights of the bars to represent values in the data, use
-#' `geom_col()` instead. `geom_bar()` uses `stat_count()` by
+#' `geom_bar()` makes the height of the bar proportional to the number of
+#' cases in each group (or if the `weight` aesthetic is supplied, the sum
+#' of the weights). If you want the heights of the bars to represent values
+#' in the data, use `geom_col()` instead. `geom_bar()` uses `stat_count()` by
 #' default: it counts the number of cases at each x position. `geom_col()`
 #' uses `stat_identity()`: it leaves the data as is.
 #'
 #' A bar chart uses height to represent a value, and so the base of the
-#' bar must always be shown to produce a valid visual comparison. This is why
-#' it doesn't make sense to use a log-scaled y axis with a bar chart.
+#' bar must always be shown to produce a valid visual comparison.
+#' Proceed with caution when using transformed scales with a bar chart.
+#' It's important to always use a meaningful reference point for the base of the bar.
+#' For example, for log transformations the reference point is 1. In fact, when
+#' using a log scale, `geom_bar()` automatically places the base of the bar at 1.
+#' Furthermore, never use stacked bars with a transformed scale, because scaling
+#' happens before stacking. As a consequence, the height of bars will be wrong
+#' when stacking occurs with a transformed scale.
 #'
 #' By default, multiple bars occupying the same `x` position will be stacked
 #' atop one another by [position_stack()]. If you want them to be dodged
 #' side-to-side, use [position_dodge()] or [position_dodge2()]. Finally,
-#' [position_fill()] shows relative proportions at each `x` by stacking the bars
-#' and then standardising each bar to have the same height.
+#' [position_fill()] shows relative proportions at each `x` by stacking the
+#' bars and then standardising each bar to have the same height.
 #'
 #' @eval rd_orientation()
 #'
@@ -36,9 +41,6 @@
 #' rare event that this fails it can be given explicitly by setting `orientation`
 #' to either `"x"` or `"y"`. See the *Orientation* section for more detail.
 #' @param width Bar width. By default, set to 90% of the resolution of the data.
-#' @param binwidth `geom_bar()` no longer has a binwidth argument - if
-#'   you use it you'll get an warning telling to you use
-#'   [geom_histogram()] instead.
 #' @param geom,stat Override the default connection between `geom_bar()` and
 #'   `stat_count()`.
 #' @examples
@@ -82,19 +84,10 @@ geom_bar <- function(mapping = NULL, data = NULL,
                      stat = "count", position = "stack",
                      ...,
                      width = NULL,
-                     binwidth = NULL,
                      na.rm = FALSE,
                      orientation = NA,
                      show.legend = NA,
                      inherit.aes = TRUE) {
-
-  if (!is.null(binwidth)) {
-    warn("`geom_bar()` no longer has a `binwidth` parameter. Please use `geom_histogram()` instead.")
-    return(geom_histogram(mapping = mapping, data = data,
-      position = position, width = width, binwidth = binwidth, ...,
-      na.rm = na.rm, show.legend = show.legend, inherit.aes = inherit.aes))
-  }
-
   layer(
     data = data,
     mapping = mapping,

R/geom-histogram.r

@@ -17,6 +17,10 @@
 #' one change at a time. You may need to look at a few options to uncover
 #' the full story behind your data.
 #'
+#' In addition to `geom_histogram`, you can create a histogram plot by using
+#' `scale_x_binned()` with [geom_bar()]. This method by default plots tick marks
+#' in between each bar.  .
+#'
 #' @eval rd_orientation()
 #'
 #' @section Aesthetics:
@@ -39,6 +43,12 @@
 #' ggplot(diamonds, aes(y = carat)) +
 #'   geom_histogram()
 #'
+#' # For histograms with tick marks between each bin, use `geom_bar` with
+#' # `scale_x_binned`.
+#' ggplot(diamonds, aes(carat)) +
+#'   geom_bar() +
+#'   scale_x_binned()
+#'
 #' # Rather than stacking histograms, it's easier to compare frequency
 #' # polygons
 #' ggplot(diamonds, aes(price, fill = cut)) +

R/geom-text.r

@@ -1,21 +1,28 @@
 #' Text
 #'
-#' `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
-#' and dodging text will not work by default, and axis limits are not
-#' automatically expanded to include all text. Obviously, labels do have
-#' height and width, but they are physical units, not data units. The amount of
-#' 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.
+#' Text geoms are useful for labeling plots. They can be used by themselves as
+#' scatterplots or in cobination with other geoms, for example, for labeling
+#' points or for annotating the height of bars. `geom_text()` adds only text
+#' to the plot. `geom_label()` draws a rectangle behind the text, making it
+#' easier to read.
+#'
+#' Note that when you resize a plot, text labels stay the same size, even
+#' though the size of the plot area changes. This happens because the "width"
+#' and "height" of a text element are 0. Obviously, text labels do have height
+#' and width, but they are physical units, not data units. For the same reason,
+#' stacking and dodging text will not work by default, and axis limits are not
+#' automatically expanded to include all text.
 #'
 #' `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 add labels at specified points use [annotate()] with
 #' `annotate(geom = "text", ...)` or `annotate(geom = "label", ...)`.
 #'
+#' To automatically position non-overlapping text labels see the
+#' \href{https://cran.r-project.org/package=ggrepel}{ggrepel}
+#' package.
+#'
 #' @eval rd_aesthetics("geom", "text")
 #' @section `geom_label()`:
 #' Currently `geom_label()` does not support the `angle` aesthetic and
@@ -36,8 +43,14 @@
 #'   displayed as described in `?plotmath`.
 #' @param nudge_x,nudge_y Horizontal and vertical adjustment to nudge labels by.
 #'   Useful for offsetting text from points, particularly on discrete scales.
+#'   Cannot be jointy specified with `position`.
+#' @param position Position adjustment, either as a string, or the result of
+#'  a call to a position adjustment function. Cannot be jointy specified with
+#'  `nudge_x` or `nudge_y`.
 #' @param check_overlap If `TRUE`, text that overlaps previous text in the
-#'   same layer will not be plotted.
+#'   same layer will not be plotted. `check_overlap` happens at draw time and in
+#'   the order of the data. Therefore data should be arranged by the label
+#'   column before calling `geom_label()` or `geom_text()`.
 #' @export
 #' @examples
 #' p <- ggplot(mtcars, aes(wt, mpg, label = rownames(mtcars)))

R/labeller.r

@@ -440,7 +440,7 @@ labeller <- function(..., .rows = NULL, .cols = NULL,
       labellers <- lapply(dots, as_labeller)
     } else {
       margin_labeller <- as_labeller(margin_labeller, default = .default,
-        multi_line = .multi_line)
+                                     multi_line = .multi_line)
 
       # Check that variable-specific labellers do not overlap with
       # margin-wide labeller
@@ -510,8 +510,8 @@ build_strip <- function(label_df, labeller, theme, horizontal) {
                                  theme, horizontal, clip = "on")
 
     grobs_bottom <- lapply(labels, element_render, theme = theme,
-                          element = "strip.text.x.bottom", margin_x = TRUE,
-                          margin_y = TRUE)
+                           element = "strip.text.x.bottom", margin_x = TRUE,
+                           margin_y = TRUE)
     grobs_bottom <- assemble_strips(matrix(grobs_bottom, ncol = ncol, nrow = nrow),
                                     theme, horizontal, clip = "on")
 

R/layout.R

@@ -296,18 +296,13 @@ scale_apply <- function(data, vars, method, scale_id, scales) {
     abort("`scale_id` must not be `NA`")
   }
 
-  scale_index <- unname(split(
-    seq_along(scale_id),
-    factor(scale_id, levels = seq_along(scales))
-  ))
+  scale_index <- split_with_index(seq_along(scale_id), scale_id, length(scales))
 
   lapply(vars, function(var) {
     pieces <- lapply(seq_along(scales), function(i) {
       scales[[i]][[method]](data[[var]][scale_index[[i]]])
     })
-    # Join pieces back together, if necessary
-    if (!is.null(pieces)) {
-      unlist(pieces)[order(unlist(scale_index))]
-    }
+    o <- order(unlist(scale_index))[seq_len(sum(lengths(pieces)))]
+    do.call("c", pieces)[o]
   })
 }

R/legend-draw.r

@@ -137,6 +137,8 @@ draw_key_path <- function(data, params, size) {
   segmentsGrob(0.1, 0.5, 0.9, 0.5,
     gp = gpar(
       col = alpha(data$colour %||% data$fill %||% "black", data$alpha),
+      fill = alpha(params$arrow.fill %||% data$colour
+                   %||% data$fill %||% "black", data$alpha),
       lwd = (data$size %||% 0.5) * .pt,
       lty = data$linetype %||% 1,
       lineend = "butt"