diff --git a/R/facet-grid-.R b/R/facet-grid-.R index 784e394885..22fbcce050 100644 --- a/R/facet-grid-.R +++ b/R/facet-grid-.R @@ -39,11 +39,9 @@ NULL #' @param as.table If `TRUE`, the default, the facets are laid out like #' a table with highest values at the bottom-right. If `FALSE`, the #' facets are laid out like a plot with the highest value at the top-right. -#' @param switch By default, the labels are displayed on the top and -#' right of the plot. If `"x"`, the top labels will be -#' displayed to the bottom. If `"y"`, the right-hand side -#' labels will be displayed to the left. Can also be set to -#' `"both"`. +#' @param strip.position One or more of `"top"`, `"right"`, `"bottom"` and +#' `"left"`, indicating where strips should be placed. When `NULL` (default), +#' strips are placed on the top and on the right. #' @param shrink If `TRUE`, will shrink scales to fit output of #' statistics, not raw data. If `FALSE`, will be range of raw data #' before statistical summary. @@ -57,6 +55,8 @@ NULL #' default). If `TRUE`, margins are included for all faceting #' variables. If specified as a character vector, it is the names of #' variables for which margins are to be created. +#' @param switch `r lifecycle::badge("deprecated")` Please use +#' `strip.position` instead. #' @param facets `r lifecycle::badge("deprecated")` Please use `rows` #' and `cols` instead. #' @param axes Determines which axes will be drawn. When `"margins"` @@ -129,9 +129,9 @@ NULL facet_grid <- function(rows = NULL, cols = NULL, scales = "fixed", space = "fixed", shrink = TRUE, labeller = "label_value", as.table = TRUE, - switch = NULL, drop = TRUE, margins = FALSE, + strip.position = NULL, drop = TRUE, margins = FALSE, axes = "margins", axis.labels = "all", - facets = deprecated()) { + facets = deprecated(), switch = deprecated()) { # `facets` is deprecated and renamed to `rows` if (lifecycle::is_present(facets)) { deprecate_warn0("2.2.0", "facet_grid(facets)", "facet_grid(rows)") @@ -170,8 +170,21 @@ facet_grid <- function(rows = NULL, cols = NULL, scales = "fixed", y = !draw_axes$y || any(axis_labels %in% c("all_y", "all")) ) - if (!is.null(switch)) { - arg_match0(switch, c("both", "x", "y")) + if (lifecycle::is_present(switch)) { + deprecate_soft0("3.6.0", "facet_grid(switch)", "facet_grid(strip.position)") + switch <- arg_match0(switch, c("both", "x", "y")) + strip.position <- strip.position %||% + base::switch(switch, both = c("bottom", "left"), x = "bottom", y = "left") + } + check_character(strip.position, allow_null = TRUE) + if (!is.waive(strip.position) && !all(strip.position %in% .trbl)) { + cli::cli_abort("{.arg strip.position} can only contain {.or {.val {(.trbl)}}}.") + } + if (!any(c("top", "bottom") %in% strip.position)) { + strip.position <- c(strip.position, "top") + } + if (!any(c("left", "right") %in% strip.position)) { + strip.position <- c(strip.position, "right") } facets_list <- grid_as_facets_list(rows, cols) @@ -183,7 +196,7 @@ facet_grid <- function(rows = NULL, cols = NULL, scales = "fixed", shrink = shrink, params = list(rows = facets_list$rows, cols = facets_list$cols, margins = margins, free = free, space_free = space_free, labeller = labeller, - as.table = as.table, switch = switch, drop = drop, + as.table = as.table, drop = drop, strip.position = strip.position, draw_axes = draw_axes, axis_labels = axis_labels) ) } @@ -396,17 +409,17 @@ FacetGrid <- ggproto("FacetGrid", Facet, padding <- convertUnit(calc_element("strip.switch.pad.grid", theme), "cm") - switch_x <- !is.null(params$switch) && params$switch %in% c("both", "x") inside_x <- (calc_element("strip.placement.x", theme) %||% "inside") == "inside" shift_x <- if (inside_x) 1 else 2 - if (switch_x) { + if ("bottom" %in% params$strip.position) { space <- if (!inside_x & table_has_grob(table, "axis-b")) padding table <- seam_table( table, strips$x$bottom, side = "bottom", name = "strip-b", shift = shift_x, z = 2, clip = "off", spacing = space ) - } else { + } + if ("top" %in% params$strip.position) { space <- if (!inside_x & table_has_grob(table, "axis-t")) padding table <- seam_table( table, strips$x$top, side = "top", name = "strip-t", @@ -414,17 +427,17 @@ FacetGrid <- ggproto("FacetGrid", Facet, ) } - switch_y <- !is.null(params$switch) && params$switch %in% c("both", "y") inside_y <- (calc_element("strip.placement.y", theme) %||% "inside") == "inside" shift_y <- if (inside_y) 1 else 2 - if (switch_y) { + if ("left" %in% params$strip.position) { space <- if (!inside_y & table_has_grob(table, "axis-l")) padding table <- seam_table( table, strips$y$left, side = "left", name = "strip-l", shift = shift_y, z = 2, clip = "off", spacing = space ) - } else { + } + if ("right" %in% params$strip.position) { space <- if (!inside_y & table_has_grob(table, "axis-r")) padding table <- seam_table( table, strips$y$right, side = "right", name = "strip-r", diff --git a/man/facet_grid.Rd b/man/facet_grid.Rd index e0a3cd1e1b..701d5770bf 100644 --- a/man/facet_grid.Rd +++ b/man/facet_grid.Rd @@ -12,12 +12,13 @@ facet_grid( shrink = TRUE, labeller = "label_value", as.table = TRUE, - switch = NULL, + strip.position = NULL, drop = TRUE, margins = FALSE, axes = "margins", axis.labels = "all", - facets = deprecated() + facets = deprecated(), + switch = deprecated() ) } \arguments{ @@ -61,11 +62,9 @@ check it for more details and pointers to other options.} a table with highest values at the bottom-right. If \code{FALSE}, the facets are laid out like a plot with the highest value at the top-right.} -\item{switch}{By default, the labels are displayed on the top and -right of the plot. If \code{"x"}, the top labels will be -displayed to the bottom. If \code{"y"}, the right-hand side -labels will be displayed to the left. Can also be set to -\code{"both"}.} +\item{strip.position}{One or more of \code{"top"}, \code{"right"}, \code{"bottom"} and +\code{"left"}, indicating where strips should be placed. When \code{NULL} (default), +strips are placed on the top and on the right.} \item{drop}{If \code{TRUE}, the default, all factor levels not used in the data will automatically be dropped. If \code{FALSE}, all factor levels @@ -93,6 +92,9 @@ respectively.} \item{facets}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Please use \code{rows} and \code{cols} instead.} + +\item{switch}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Please use +\code{strip.position} instead.} } \description{ \code{facet_grid()} forms a matrix of panels defined by row and column diff --git a/man/facet_wrap.Rd b/man/facet_wrap.Rd index 66716f5c5f..9c97ac2509 100644 --- a/man/facet_wrap.Rd +++ b/man/facet_wrap.Rd @@ -62,11 +62,8 @@ check it for more details and pointers to other options.} a table with highest values at the bottom-right. If \code{FALSE}, the facets are laid out like a plot with the highest value at the top-right.} -\item{switch}{By default, the labels are displayed on the top and -right of the plot. If \code{"x"}, the top labels will be -displayed to the bottom. If \code{"y"}, the right-hand side -labels will be displayed to the left. Can also be set to -\code{"both"}.} +\item{switch}{\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Please use +\code{strip.position} instead.} \item{drop}{If \code{TRUE}, the default, all factor levels not used in the data will automatically be dropped. If \code{FALSE}, all factor levels diff --git a/tests/testthat/_snaps/facet-strips.md b/tests/testthat/_snaps/facet-strips.md index e6a72d047c..8ec10ffc7d 100644 --- a/tests/testthat/_snaps/facet-strips.md +++ b/tests/testthat/_snaps/facet-strips.md @@ -1,4 +1,4 @@ # facet_grid() warns about bad switch input - `switch` must be one of "both", "x", or "y", not "z". + `strip.position` can only contain "top", "right", "bottom", or "left". diff --git a/tests/testthat/test-facet-strips.R b/tests/testthat/test-facet-strips.R index d13f8d500c..3eccbed95c 100644 --- a/tests/testthat/test-facet-strips.R +++ b/tests/testthat/test-facet-strips.R @@ -82,7 +82,7 @@ test_that("facet_grid() builds correct output", { }) test_that("facet_grid() switches to 'x'", { - grid_x <- p + facet_grid(am ~ cyl, switch = "x") + grid_x <- p + facet_grid(am ~ cyl, strip.position = "bottom") grid_x_expected <- list( t = c(6, 6, 6, 3, 5), @@ -95,7 +95,7 @@ test_that("facet_grid() switches to 'x'", { }) test_that("facet_grid() switches to 'y'", { - grid_y <- p + facet_grid(am ~ cyl, switch = "y") + grid_y <- p + facet_grid(am ~ cyl, strip.position = "left") grid_y_expected <- list( t = c(3, 3, 3, 4, 6), @@ -108,7 +108,7 @@ test_that("facet_grid() switches to 'y'", { }) test_that("facet_grid() switches to both 'x' and 'y'", { - grid_xy <- p + facet_grid(am ~ cyl, switch = "both") + grid_xy <- p + facet_grid(am ~ cyl, strip.position = c("bottom", "left")) grid_xy_expected <- list( t = c(6, 6, 6, 3, 5), @@ -121,7 +121,7 @@ test_that("facet_grid() switches to both 'x' and 'y'", { }) test_that("facet_grid() warns about bad switch input", { - expect_snapshot_error(facet_grid(am ~ cyl, switch = "z")) + expect_snapshot_error(facet_grid(am ~ cyl, strip.position = "z")) }) test_that("strips can be removed", { @@ -165,7 +165,7 @@ test_that("padding is only added if axis is present", { # Inverse should be true when strips are switched p <- ggplot(data = mpg, aes(x = displ, y = hwy)) + - facet_grid(year ~ drv, switch = "both") + + facet_grid(year ~ drv, strip.position = c("bottom", "left")) + theme( strip.placement = "outside", strip.switch.pad.grid = unit(10, "mm") @@ -186,7 +186,7 @@ test_that("padding is only added if axis is present", { }) test_that("y strip labels are rotated when strips are switched", { - switched <- p + facet_grid(am ~ cyl, switch = "both") + switched <- p + facet_grid(am ~ cyl, strip.position = c("bottom", "left")) expect_doppelganger("switched facet strips", switched) })