Allow separate expansion values for lower and upper range limits (v2) (#1805)

* Allow separate expansion values for lower and upper range limits.

The `expand` argument for `scale_*_continuous()` and `scale_*_discrete()`
now accepts separate expansion constants for the lower and upper range limits.

This is useful for creating bar charts where the bottom of the bars
are flush with the x axis but the bars still have some (automatically
calculated amount of) space above them:

```R
ggplot(mtcars) +
  geom_bar(aes(x = factor(cyl))) +
  scale_y_continuous(expand = c(0, 0, 0.1, 0))
```

It can also be useful for line charts, e.g. for counts over time,
where one wants to have a ’hard’ lower limit of y = 0, but leave the
upper limit unspecified (and perhaps differing between panels),
but with some extra space above the highest point on the line.
(With symmetrical limits, the extra space above the highest point
could cause the lower limit to be negative.)

The syntax for the multiplicative and additive expansion
constants has been changed from `c(m, a)` to
`c(m_lower, a_lower, m_uppper, a_upper)`. The old syntax will still
work, as length 2 vectors `c(m, a)` are expanded to `c(m, a, m, a)`
and length 3 vectors are expanded from `c(m1, a1, m2)` to
`c(m1, a2, m2, a1)`. (@huftis, #1669)

* Added `expand_scale()` function for easier generation of scale expansion
vectors.

Instead of having to manually specify an `expand` argument using
a somewhat confusing syntax (a vector of 2, 3 or 4 numeric values),
it’s now possible to use the user-friendly (and documented)
`expand_scale()` function.

This commit also cleans up the documentation related to the
`expand` argument, which was duplicated in several functions.

* Added UTF-8 character encoding declaration to DESCRIPTION.

The documentation for one of the functions had a no-breaking space,
(between a number and the word ‘units’), which caused R CMD check to
complain about ‘non-ASCII input and no declared encoding’.
This adds a character encoding declaration of UTF-8 to the DESCRIPTION
file to fix this problem.

* Fixed some style issues.

* Updated and regenerated documentation.

* Specify character encoding used for documentation.

* Minor grammar improvement in documentation.

* Don’t generate documentation for internal function expand_range4().

Author: huftis

DESCRIPTION

@@ -226,3 +226,4 @@ Collate:
 VignetteBuilder: knitr
 RoxygenNote: 6.0.1
 Roxygen: list(markdown = TRUE)
+Encoding: UTF-8

NAMESPACE

@@ -258,6 +258,7 @@ export(element_line)
 export(element_rect)
 export(element_text)
 export(expand_limits)
+export(expand_scale)
 export(facet_grid)
 export(facet_null)
 export(facet_wrap)

NEWS.md

@@ -63,6 +63,31 @@
 
 * `geom_smooth`'s message for `method="auto"` now reports the formula used,
   in addition to the name of the smoothing function (@davharris #1951).
+  
+* The `expand` argument for `scale_*_continuous()` and `scale_*_discrete()`
+  now accepts separate expansion values for the lower and upper range
+  limits. The expansion limits can be specified using the convenience
+  function `expand_scale()`.
+  
+  Separate expansion limits may be useful for bar charts, e.g. if one
+  wants to have the bottom of the bars being flush with the x axis but
+  still leave some (automatically calculated amount of) space above them:
+  
+    ```R
+    ggplot(mtcars) +
+        geom_bar(aes(x = factor(cyl))) +
+        scale_y_continuous(expand = expand_scale(mult = c(0, .1)))
+    ```
+  
+  It can also be useful for line charts, e.g. for counts over time,
+  where one wants to have a ’hard’ lower limit of y = 0 but leave the
+  upper limit unspecified (and perhaps differing between panels),
+  but with some extra space above the highest point on the line.
+  (With symmetrical limits, the extra space above the highest point
+  could in some cases cause the lower limit to be negative.)
+  
+  The old syntax for the `expand` argument will of course continue
+  to work. (@huftis, #1669)
 
 * `print.ggplot()` now returns the original ggplot object, instead of the output from `ggplot_build()`. Also, the object returned from `ggplot_build()` now has the class `"ggplot_built"`. (#2034)
 

R/coord-.r

@@ -114,7 +114,7 @@ Coord <- ggproto("Coord",
 #' @keywords internal
 is.Coord <- function(x) inherits(x, "Coord")
 
-expand_default <- function(scale, discrete = c(0, 0.6), continuous = c(0.05, 0)) {
+expand_default <- function(scale, discrete = c(0, 0.6, 0, 0.6), continuous = c(0.05, 0, 0.05, 0)) {
   scale$expand %|W|% if (scale$is_discrete()) discrete else continuous
 }
 

R/scale-.r

@@ -121,9 +121,9 @@ Scale <- ggproto("Scale", NULL,
   },
 
   # The physical size of the scale.
-  # This always returns a numeric vector of length 2, giving the physical
+  # This always returns a numeric vector of length 4, giving the physical
   # dimensions of a scale.
-  dimension = function(self, expand = c(0, 0)) {
+  dimension = function(self, expand = c(0, 0, 0, 0)) {
     stop("Not implemented", call. = FALSE)
   },
 
@@ -224,8 +224,8 @@ ScaleContinuous <- ggproto("ScaleContinuous", Scale,
     ifelse(!is.na(scaled), scaled, self$na.value)
   },
 
-  dimension = function(self, expand = c(0, 0)) {
-    expand_range(self$get_limits(), expand[1], expand[2])
+  dimension = function(self, expand = c(0, 0, 0, 0)) {
+    expand_range4(self$get_limits(), expand)
   },
 
   get_breaks = function(self, limits = self$get_limits()) {
@@ -397,8 +397,8 @@ ScaleDiscrete <- ggproto("ScaleDiscrete", Scale,
     }
   },
 
-  dimension = function(self, expand = c(0, 0)) {
-    expand_range(length(self$get_limits()), expand[1], expand[2])
+  dimension = function(self, expand = c(0, 0, 0, 0)) {
+    expand_range4(length(self$get_limits()), expand)
   },
 
   get_breaks = function(self, limits = self$get_limits()) {
@@ -532,11 +532,7 @@ ScaleDiscrete <- ggproto("ScaleDiscrete", Scale,
 #'   A function used to scale the input values to the range \eqn{[0, 1]}.
 #' @param oob Function that handles limits outside of the scale limits
 #'   (out of bounds). The default replaces out of bounds values with NA.
-#' @param expand A numeric vector of length two giving multiplicative and
-#'   additive expansion constants. These constants ensure that the data is
-#'   placed some distance away from the axes. The defaults are
-#'   `c(0.05, 0)` for continuous variables, and `c(0, 0.6)` for
-#'   discrete variables.
+#' @inheritParams scale_x_discrete
 #' @param na.value Missing values will be replaced with this value.
 #' @param trans Either the name of a transformation object, or the
 #'   object itself. Built-in transformations include "asn", "atanh",

R/scale-discrete-.r

@@ -7,9 +7,12 @@
 #' at integer positions).  This is what allows jittering to work.
 #'
 #' @inheritDotParams discrete_scale -expand -position
-#' @param expand a numeric vector of length two giving multiplicative and
-#'   additive expansion constants. These constants ensure that the data is
-#'   placed some distance away from the axes.
+#' @param expand Vector of range expansion constants used to add some
+#'   padding around the data, to ensure that they are placed some distance
+#'   away from the axes. Use the convenience function [expand_scale()]
+#'   to generate the values for the `expand` argument. The defaults are to
+#'   expand the scale by 5\% on each side for continuous variables, and by
+#'   0.6 units on each side for discrete variables.
 #' @param position The position of the axis. `left` or `right` for y
 #' axes, `top` or `bottom` for x axes
 #' @rdname scale_discrete
@@ -105,20 +108,20 @@ ScaleDiscretePosition <- ggproto("ScaleDiscretePosition", ScaleDiscrete,
     }
   },
 
-  dimension = function(self, expand = c(0, 0)) {
+  dimension = function(self, expand = c(0, 0, 0, 0)) {
     c_range <- self$range_c$range
     d_range <- self$get_limits()
 
     if (self$is_empty()) {
       c(0, 1)
     } else if (is.null(self$range$range)) { # only continuous
-      expand_range(c_range, expand[1], expand[2] , 1)
+      expand_range4(c_range, expand)
     } else if (is.null(c_range)) { # only discrete
-      expand_range(c(1, length(d_range)), expand[1], expand[2], 1)
+      expand_range4(c(1, length(d_range)), expand)
     } else { # both
       range(
-        expand_range(c_range, expand[1], 0 , 1),
-        expand_range(c(1, length(d_range)), 0, expand[2], 1)
+        c_range,
+        expand_range4(c(1, length(d_range)), expand)
       )
     }
   },

R/utilities.r

@@ -172,6 +172,77 @@ rescale01 <- function(x) {
   (x - rng[1]) / (rng[2] - rng[1])
 }
 
+#' Similar to expand_range(), but taking a vector ‘expand’
+#' of *four* expansion values, where the 1st and 2nd
+#' elements are used for the lower limit, and the 3rd and
+#' 4th elements are used for the upper limit).
+#'
+#' The ‘expand’ argument can also be of length 2,
+#' and the expansion values for the lower limit
+#' are then reused for the upper limit.
+#
+#' @noRd
+#' @keywords internal
+expand_range4 <- function(limits, expand) {
+   stopifnot(is.numeric(expand) && (length(expand) %in% c(2,4)))
+   # If only two expansion constants are given (i.e. the old syntax),
+   # reuse them to generate a four-element expansion vector
+   if (length(expand) == 2) { expand <- c(expand, expand) }
+
+   # Calculate separate range expansion for the lower and
+   # upper range limits, and then combine them into one vector
+   lower <- expand_range(limits, expand[1], expand[2])[1]
+   upper <- expand_range(limits, expand[3], expand[4])[2]
+   c(lower, upper)
+}
+
+#' Generate expansion vector for scales.
+#'
+#' This is a convenience function for generating scale expansion vectors
+#' for the \code{expand} argument of
+#' \code{\link[=scale_x_continuous]{scale_*_continuous}} and
+#' \code{\link[=scale_x_discrete]{scale_*_discrete}}.
+#' The expansions vectors are used to add some space between
+#' the data and the axes.
+#'
+#' @export
+#' @param mult vector of multiplicative range expansion factors.
+#'   If length 1, both the lower and upper limits of the scale
+#'   are expanded outwards by \code{mult}. If length 2, the lower limit
+#'   is expanded by \code{mult[1]} and the upper limit by \code{mult[2]}.
+#' @param add vector of additive range expansion constants.
+#'   If length 1, both the lower and upper limits of the scale
+#'   are expanded outwards by \code{add} units. If length 2, the
+#'   lower limit is expanded by \code{add[1]} and the upper
+#'   limit by \code{add[2]}.
+#' @examples
+#' # No space below the bars but 10% above them
+#' ggplot(mtcars) +
+#'   geom_bar(aes(x = factor(cyl))) +
+#'   scale_y_continuous(expand = expand_scale(mult = c(0, .1)))
+#'
+#' # Add 2 units of space on the left and right of the data
+#' ggplot(subset(diamonds, carat > 2), aes(cut, clarity)) +
+#'   geom_jitter() +
+#'   scale_x_discrete(expand = expand_scale(add = 2))
+#'
+#' # Reproduce the default range expansion used
+#' # when the ‘expand’ argument is not specified
+#' ggplot(subset(diamonds, carat > 2), aes(cut, price)) +
+#'   geom_jitter() +
+#'   scale_x_discrete(expand = expand_scale(add = .6)) +
+#'   scale_y_continuous(expand = expand_scale(mult = .05))
+expand_scale = function(mult = 0, add = 0) {
+  stopifnot(is.numeric(mult) && is.numeric(add))
+  stopifnot((length(mult) %in% 1:2) && (length(add) %in% 1:2))
+
+  mult <- rep(mult, length.out = 2)
+  add <- rep(add, length.out = 2)
+  c(mult[1], add[1], mult[2], add[2])
+}
+
+
+
 #' Give a deprecation error, warning, or message, depending on version number.
 #'
 #' Version numbers have the format <major>.<minor>.<subminor>, like 0.9.2.