Merge branch 'master' of github.com:hadley/ggplot2

Author: hadley

NEWS.md

@@ -210,33 +210,69 @@ All defunct functions have been removed.
 
 ### Labelling
 
-* `facet_wrap()` gains a `labeller` option (@lionel-, #25).
-
-* The labeller API has been updated to offer more control when facetting over 
-  multiple factors (e.g. with formulae such as `~cyl + am`). Previously, a 
-  labeller function would take `variable` and `value` arguments and return a 
-  character vector. 
-  
-  Now, they take a data frame of character vectors and return a list. The input 
-  data frame has one column per factor facetted over. Each column in the 
-  returned list becomes one line in the strip label. See documentation for more
-  details. 
-  
-* Labellers offer the `multi_line` argument to control whether to display one 
-  or multiple lines. 
-  
-* Referring to `x` in backquoted expressions with `label_bquote()` is 
-  deprecated. You can now refer to the variable names instead. (@lionel-)
-
-* `label_bquote()` and `labeller()` now take `rows` and `cols` arguments. They 
-  allow rows and columns labels to have specific plotmath expressions or 
-  labellers.
-
-* New labeller `label_context()` which behaviour differently based on the 
-  on the number of factors facetted over. With a single factor, it displays 
-  only the values, just as before. But with multiple factors (e.g. with 
-  `~cyl + am`), the labels are dispatched to `label_both()` to display both the 
-  variables and the values and make the plot clearer. (@lionel-)
+The facet labelling system was updated with many new features and a
+more flexible interface (@lionel-). It now works consistently across
+grid and wrap facets. The most important user visible changes are:
+
+* `facet_wrap()` gains a `labeller` option (#25).
+
+* `facet_grid()` and `facet_wrap()` gain a `switch` argument to
+  display the facet titles near the axes. When switched, the labels
+  become axes subtitles. `switch` can be set to "x", "y" or "both"
+  (the latter only for grids) to control which margin is switched.
+
+The labellers (such as `label_value()` or `label_both()`) also get
+some new features:
+
+* They now offer the `multi_line` argument to control whether to
+  display composite facets (those specified as `~var1 + var2`) on one
+  or multiple lines.
+
+* In `label_bquote()` you now refer directly to the names of
+  variables. With this change, you can create math expressions that
+  depend on more than one variable. This math expression can be
+  specified either for the rows or the columns and you can also
+  provide different expressions to each margin.
+
+  As a consequence of these changes, referring to `x` in backquoted
+  expressions is deprecated.
+
+* Similarly to `label_bquote()`, `labeller()` now take `.rows` and
+  `.cols` arguments. In addition, it also takes `.default`.
+  `labeller()` is useful to customise how particular variables are
+  labelled. The three additional arguments specify how to label the
+  variables are not specifically mentioned, respectively for rows,
+  columns or both. This makes it especially easy to set up a
+  project-wide labeller dispatcher that can be reused across all your
+  plots. See the documentation for an example.
+
+* The new labeller `label_context()` adapts to the number of factors
+  facetted over. With a single factor, it displays only the values,
+  just as before. But with multiple factors in a composite margin
+  (e.g. with `~cyl + am`), the labels are passed over to
+  `label_both()`. This way the variables names are displayed with the
+  values to help identifying them.
+
+On the programming side, the labeller API has been rewritten in order
+to offer more control when facetting over multiple factors (e.g. with
+formulae such as `~cyl + am`). This also means that if you have
+written custom labellers, you will need to update them for this
+version of ggplot.
+
+* Previously, a labeller function would take `variable` and `value`
+  arguments and return a character vector. Now, they take a data frame
+  of character vectors and return a list. The input data frame has one
+  column per factor facetted over and each column in the returned list
+  becomes one line in the strip label. See documentation for more
+  details.
+
+* The labels received by a labeller now contain metadata: their margin
+  (in the "type" attribute) and whether they come from a wrap or a
+  grid facet (in the "facet" attribute).
+
+* Note that the new `as_labeller()` function operator provides an easy
+  way to transform an existing function to a labeller function. The
+  existing function just needs to take and return a character vector.
 
 ## Documentation
 
@@ -321,11 +357,6 @@ All defunct functions have been removed.
 * `facet_wrap()` and `facet_grid()` now allow you to use non-standard
   variable names by surrounding them with backticks (#1067).
 
-* `facet_grid()` and `facet_wrap()` gain a `switch` argument that
-  allows the facet titles to be displayed near the axes. They then act
-  as axes subtitles. Can be set to "x", "y" or "both" (the latter only
-  for grids) to control which label strips are switched. (@lionel-)
-
 * `facet_wrap()` more carefully checks its `nrow` and `ncol` arguments
   to ensure that they're specified correctly (@richierocks, #962)
 

R/facet-grid-.r

@@ -221,6 +221,9 @@ facet_grid <- function(facets, margins = FALSE, scales = "fixed", space = "fixed
     stop("Must specify at least one variable to facet by", call. = FALSE)
   }
 
+  # Check for deprecated labellers
+  labeller <- check_labeller(labeller)
+
   facet(
     rows = rows, cols = cols, margins = margins, shrink = shrink,
     free = free, space_free = space_free, labeller = labeller,

R/facet-labels.r

@@ -555,3 +555,21 @@ adjust_angle <- function(angle) {
     angle + 180
   }
 }
+
+# Check for old school labeller
+check_labeller <- function(labeller) {
+  labeller <- match.fun(labeller)
+  is_deprecated <- all(c("variable", "value") %in% names(formals(labeller)))
+
+  if (is_deprecated) {
+    old_labeller <- labeller
+    labeller <- function(labels) {
+      Map(old_labeller, names(labels), labels)
+    }
+    warning("The labeller API has been updated. Labellers taking `variable`",
+      "and `value` arguments are now deprecated. See labellers documentation.",
+      call. = FALSE)
+  }
+
+  labeller
+}

R/facet-wrap.r

@@ -93,6 +93,9 @@ facet_wrap <- function(facets, nrow = NULL, ncol = NULL, scales = "fixed",
     ncol <- sanitise_dim(ncol)
   }
 
+  # Check for deprecated labellers
+  labeller <- check_labeller(labeller)
+
   facet(
     facets = as.quoted(facets), free = free, shrink = shrink,
     as.table = as.table, switch = switch,

tests/testthat/test-facet-labels.r

@@ -133,3 +133,17 @@ test_that("as_labeller() deals with non-labellers", {
   p2 <- p + facet_wrap(~am, labeller = labeller(am = function(x) paste0(x, "-foo")))
   expect_equal(get_labels_matrix(p2), cbind(c("0-foo", "1-foo")))
 })
+
+test_that("old school labellers still work", {
+  my_labeller <- function(variable, value) {
+    paste0("var = ", as.character(value))
+  }
+
+  expect_warning(p <-
+    ggplot(mtcars, aes(disp, drat)) +
+    geom_point() +
+    facet_grid(~cyl, labeller = my_labeller))
+
+  expected_labels <- cbind(paste("var =", c(4, 6, 8)))
+  expect_identical(get_labels_matrix(p, "cols"), expected_labels)
+})

visual_test/lines.r

@@ -74,26 +74,26 @@ nzmap + geom_abline(intercept = 130, slope = -1) + coord_map()
 save_vtest("geom_abline: intercept=130, slope=-1 projection=mercator")
 
 
-nzmap + geom_hline(yintercept = -45) + coord_map(project = "cylindrical")
+nzmap + geom_hline(yintercept = -45) + coord_map(projection = "cylindrical")
 save_vtest("geom_hline: intercept=-45, projection=cylindrical")
 
-nzmap + geom_vline(xintercept = 172) + coord_map(project = "cylindrical")
+nzmap + geom_vline(xintercept = 172) + coord_map(projection = "cylindrical")
 save_vtest("geom_vline: intercept=172, projection=cylindrical")
 
-nzmap + geom_abline(intercept = 130, slope = -1) + coord_map(project = "cylindrical")
+nzmap + geom_abline(intercept = 130, slope = -1) + coord_map(projection = "cylindrical")
 save_vtest("geom_abline: intercept=130, slope=-1, projection=cylindrical")
 
 
 nzmap + geom_hline(yintercept = -45) +
-  coord_map(project = 'azequalarea', orientation = c(-36.92, 174.6, 0))
+  coord_map(projection = 'azequalarea', orientation = c(-36.92, 174.6, 0))
 save_vtest("geom_hline: intercept=-45, projection=azequalarea")
 
 nzmap + geom_vline(xintercept = 172) +
-  coord_map(project = 'azequalarea', orientation = c(-36.92, 174.6, 0))
+  coord_map(projection = 'azequalarea', orientation = c(-36.92, 174.6, 0))
 save_vtest("geom_vline: intercept=172, projection=azequalara")
 
 nzmap + geom_abline(intercept = 130, slope = -1) +
-  coord_map(project = 'azequalarea', orientation = c(-36.92, 174.6, 0))
+  coord_map(projection = 'azequalarea', orientation = c(-36.92, 174.6, 0))
 save_vtest("geom_abline: intercept=130, slope=-1, projection=azequalarea")
 
 end_vcontext()

visual_test/minor-breaks.r

@@ -11,7 +11,7 @@ save_vtest("manual minor breaks with coord_polar")
 
 set.seed(342)
 df <- data.frame(
-  date = seq(as.Date("2012-2-29"), len = 100, by = "1 day")[sample(100, 50)],
+  date = seq(as.Date("2012-2-29"), length.out = 100, by = "1 day")[sample(100, 50)],
   price = runif(50)
 )
 df <- df[order(df$date), ]

visual_test/violin.r

@@ -42,7 +42,7 @@ ggplot(dat, aes(x = as.numeric(1), y = y)) + geom_violin()
 save_vtest("continuous x axis, single group (center should be at 1.0)")
 
 
-ggplot(dat, aes(x=x, y=y)) + geom_violin(quantiles=c(0.25,0.5,0.75))
+ggplot(dat, aes(x=x, y=y)) + geom_violin(draw_quantiles=c(0.25,0.5,0.75))
 save_vtest("quantiles")
 
 dat2 <- data.frame(x = LETTERS[1:3], y = rnorm(90), g = letters[5:6])