Supersede a few things (#6449)

* Use `coord_radial()` in examples

* move and merge docs to `coord_radial()`

* slap a superseded badge on `coord_polar()`

* supersede `expand_limits()`

* sprinkle `signal_stage("superseded")` all over

* mark `type` argument as superseded

* supersede `facet_wrap(as.table)`

* supersede `labs()` variants

* fix dumb mistake

Author: teunbrand

R/annotation-logticks.R

@@ -93,6 +93,8 @@ annotation_logticks <- function(base = 10, sides = "bl", outside = FALSE, scaled
   if (!is.null(color))
     colour <- color
 
+  lifecycle::signal_stage("superseded", "annotation_logticks()", "guide_axis_logticks()")
+
   if (lifecycle::is_present(size)) {
     deprecate_soft0("3.5.0", I("Using the `size` aesthetic in this geom"), I("`linewidth`"))
     linewidth <- linewidth %||% size

R/coord-flip.R

@@ -57,6 +57,7 @@
 #'   geom_area() +
 #'   coord_flip()
 coord_flip <- function(xlim = NULL, ylim = NULL, expand = TRUE, clip = "on") {
+  lifecycle::signal_stage("superseded", "coord_flip()")
   check_coord_limits(xlim)
   check_coord_limits(ylim)
   ggproto(NULL, CoordFlip,

R/coord-map.R

@@ -136,7 +136,7 @@ coord_map <- function(projection="mercator", ..., parameters = NULL, orientation
   } else {
     params <- parameters
   }
-
+  lifecycle::signal_stage("superseded", "coord_map()", "coord_sf()")
   check_coord_limits(xlim)
   check_coord_limits(ylim)
 

R/coord-polar.R

@@ -1,69 +1,9 @@
-#' Polar coordinates
-#'
-#' The polar coordinate system is most commonly used for pie charts, which
-#' are a stacked bar chart in polar coordinates. `coord_radial()` has extended
-#' options.
-#'
-#' @param theta variable to map angle to (`x` or `y`)
-#' @param start Offset of starting point from 12 o'clock in radians. Offset
-#'   is applied clockwise or anticlockwise depending on value of `direction`.
-#' @param direction 1, clockwise; -1, anticlockwise
-#' @param clip Should drawing be clipped to the extent of the plot panel? A
-#'   setting of `"on"` (the default) means yes, and a setting of `"off"`
-#'   means no. For details, please see [`coord_cartesian()`].
+#' @rdname coord_radial
 #' @export
-#' @seealso
-#' The `r link_book("polar coordinates section", "coord#polar-coordinates-with-coord_polar")`
-#' @examples
-#' # NOTE: Use these plots with caution - polar coordinates has
-#' # major perceptual problems.  The main point of these examples is
-#' # to demonstrate how these common plots can be described in the
-#' # grammar.  Use with EXTREME caution.
-#'
-#' # A pie chart = stacked bar chart + polar coordinates
-#' pie <- ggplot(mtcars, aes(x = factor(1), fill = factor(cyl))) +
-#'  geom_bar(width = 1)
-#' pie + coord_polar(theta = "y")
-#'
-#' \donttest{
-#'
-#' # A coxcomb plot = bar chart + polar coordinates
-#' cxc <- ggplot(mtcars, aes(x = factor(cyl))) +
-#'   geom_bar(width = 1, colour = "black")
-#' cxc + coord_polar()
-#' # A new type of plot?
-#' cxc + coord_polar(theta = "y")
-#'
-#' # The bullseye chart
-#' pie + coord_polar()
-#'
-#' # Hadley's favourite pie chart
-#' df <- data.frame(
-#'   variable = c("does not resemble", "resembles"),
-#'   value = c(20, 80)
-#' )
-#' ggplot(df, aes(x = "", y = value, fill = variable)) +
-#'   geom_col(width = 1) +
-#'   scale_fill_manual(values = c("red", "yellow")) +
-#'   coord_polar("y", start = pi / 3) +
-#'   labs(title = "Pac man")
-#'
-#' # Windrose + doughnut plot
-#' if (require("ggplot2movies")) {
-#' movies$rrating <- cut_interval(movies$rating, length = 1)
-#' movies$budgetq <- cut_number(movies$budget, 4)
-#'
-#' doh <- ggplot(movies, aes(x = rrating, fill = budgetq))
-#'
-#' # Wind rose
-#' doh + geom_bar(width = 1) + coord_polar()
-#' # Race track plot
-#' doh + geom_bar(width = 0.9, position = "fill") + coord_polar(theta = "y")
-#' }
-#' }
 coord_polar <- function(theta = "x", start = 0, direction = 1, clip = "on") {
   theta <- arg_match0(theta, c("x", "y"))
   r <- if (theta == "x") "y" else "x"
+  lifecycle::signal_stage("superseded", "coord_polar()", "coord_radial()")
 
   ggproto(NULL, CoordPolar,
     theta = theta,

R/coord-radial.R

@@ -1,6 +1,17 @@
-
-#' @rdname coord_polar
+#' Polar coordinates
+#'
+#' The polar coordinate system is most commonly used for pie charts, which
+#' are a stacked bar chart in polar coordinates. \cr
+#' `r lifecycle::badge("superseded")`: `coord_polar()` has been in favour of
+#' `coord_radial()`.
 #'
+#' @param theta variable to map angle to (`x` or `y`)
+#' @param start Offset of starting point from 12 o'clock in radians. Offset
+#'   is applied clockwise or anticlockwise depending on value of `direction`.
+#' @param direction 1, clockwise; -1, anticlockwise
+#' @param clip Should drawing be clipped to the extent of the plot panel? A
+#'   setting of `"on"` (the default) means yes, and a setting of `"off"`
+#'   means no. For details, please see [`coord_cartesian()`].
 #' @param end Position from 12 o'clock in radians where plot ends, to allow
 #'   for partial polar coordinates. The default, `NULL`, is set to
 #'   `start + 2 * pi`.
@@ -26,7 +37,7 @@
 #'   (default) keep directions as is. `"theta"` reverses the angle and `"r"`
 #'   reverses the radius. `"thetar"` reverses both the angle and the radius.
 #' @param r_axis_inside,rotate_angle `r lifecycle::badge("deprecated")`
-#'
+#' @export
 #' @note
 #' In `coord_radial()`, position guides can be defined by using
 #' `guides(r = ..., theta = ..., r.sec = ..., theta.sec = ...)`. Note that
@@ -35,8 +46,56 @@
 #' be used for the `theta` positions. Using the `theta.sec` position is only
 #' sensible when `inner.radius > 0`.
 #'
-#' @export
+#' @seealso
+#' The `r link_book("polar coordinates section", "coord#polar-coordinates-with-coord_polar")`
 #' @examples
+#' # NOTE: Use these plots with caution - polar coordinates has
+#' # major perceptual problems.  The main point of these examples is
+#' # to demonstrate how these common plots can be described in the
+#' # grammar.  Use with EXTREME caution.
+#'
+#' # A pie chart = stacked bar chart + polar coordinates
+#' pie <- ggplot(mtcars, aes(x = factor(1), fill = factor(cyl))) +
+#'  geom_bar(width = 1)
+#' pie + coord_radial(theta = "y", expand = FALSE)
+#'
+#' \donttest{
+#'
+#' # A coxcomb plot = bar chart + polar coordinates
+#' cxc <- ggplot(mtcars, aes(x = factor(cyl))) +
+#'   geom_bar(width = 1, colour = "black")
+#' cxc + coord_radial(expand = FALSE)
+#' # A new type of plot?
+#' cxc + coord_radial(theta = "y", expand = FALSE)
+#'
+#' # The bullseye chart
+#' pie + coord_radial(expand = FALSE)
+#'
+#' # Hadley's favourite pie chart
+#' df <- data.frame(
+#'   variable = c("does not resemble", "resembles"),
+#'   value = c(20, 80)
+#' )
+#' ggplot(df, aes(x = "", y = value, fill = variable)) +
+#'   geom_col(width = 1) +
+#'   scale_fill_manual(values = c("red", "yellow")) +
+#'   coord_radial("y", start = pi / 3, expand =  FALSE) +
+#'   labs(title = "Pac man")
+#'
+#' # Windrose + doughnut plot
+#' if (require("ggplot2movies")) {
+#' movies$rrating <- cut_interval(movies$rating, length = 1)
+#' movies$budgetq <- cut_number(movies$budget, 4)
+#'
+#' doh <- ggplot(movies, aes(x = rrating, fill = budgetq))
+#'
+#' # Wind rose
+#' doh + geom_bar(width = 1) + coord_radial(expand = FALSE)
+#' # Race track plot
+#' doh + geom_bar(width = 0.9, position = "fill") +
+#'   coord_radial(theta = "y", expand = FALSE)
+#' }
+#' }
 #' # A partial polar plot
 #' ggplot(mtcars, aes(disp, mpg)) +
 #'   geom_point() +
@@ -475,7 +534,7 @@ CoordRadial <- ggproto("CoordRadial", Coord,
   }
 )
 
-view_scales_polar <- function(scale, theta = "x", coord_limits = NULL, 
+view_scales_polar <- function(scale, theta = "x", coord_limits = NULL,
                               expand = TRUE) {
 
   aesthetic <- scale$aesthetics[1]

R/facet-wrap.R

@@ -45,6 +45,11 @@ NULL
 #'   the exterior axes get labels, and the interior axes get none. When
 #'   `"all_x"` or `"all_y"`, only draws the labels at the interior axes in the
 #'   x- or y-direction respectively.
+#' @param as.table `r lifecycle::badge("superseded")` The `as.table` argument
+#'   is now absorbed into the `dir` argument via the two letter options.
+#'   If `TRUE`, 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.
 #'
 #' @section Layer layout:
 #' The [`layer(layout)`][layer()] argument in context of `facet_wrap()` can take

R/labels.R

@@ -200,19 +200,26 @@ labs <- function(..., title = waiver(), subtitle = waiver(), caption = waiver(),
 
 #' @rdname labs
 #' @export
+#' @description
+#' `r lifecycle::badge("superseded")`: `xlab()`, `ylab()` and `ggtitle()` are
+#' superseded. It is recommended to use the `labs(x, y, title, subtitle)`
+#' arguments instead.
 xlab <- function(label) {
+  lifecycle::signal_stage("superseded", "xlab()", "labs(x)")
   labs(x = label)
 }
 
 #' @rdname labs
 #' @export
 ylab <- function(label) {
+  lifecycle::signal_stage("superseded", "ylab()", "labs(y)")
   labs(y = label)
 }
 
 #' @rdname labs
 #' @export
 ggtitle <- function(label, subtitle = waiver()) {
+  lifecycle::signal_stage("superseded", "ggtitle()", I("labs(title, subtitle)"))
   labs(title = label, subtitle = subtitle)
 }
 

R/limits.R

@@ -159,6 +159,9 @@ limits.POSIXlt <- function(lims, var, call = caller_env()) {
 
 #' Expand the plot limits, using data
 #'
+#' `r lifecycle::badge("superseded")`: It is recommended to pass a function to
+#' the `limits` argument in scales instead. For example:
+#' `scale_x_continuous(limits = ~range(.x, 0))` to include zero.\cr\cr
 #' Sometimes you may want to ensure limits include a single value, for all
 #' panels or all plots.  This function is a thin wrapper around
 #' [geom_blank()] that makes it easy to add such values.
@@ -181,6 +184,8 @@ limits.POSIXlt <- function(lims, var, call = caller_env()) {
 expand_limits <- function(...) {
   data <- list2(...)
 
+  lifecycle::signal_stage("superseded", "expand_limits()")
+
   # unpack data frame columns
   data_dfs <- vapply(data, is.data.frame, logical(1))
   data <- unlist(c(list(data[!data_dfs]), data[data_dfs]), recursive = FALSE)

R/scale-colour.R

@@ -7,21 +7,13 @@
 #' functions that assign discrete color bins to the continuous values
 #' instead of using a continuous color spectrum.
 #'
-#' All these colour scales use the [options()] mechanism to determine
-#' default settings. Continuous colour scales default to the values of the
-#' `ggplot2.continuous.colour` and `ggplot2.continuous.fill` options, and
-#' binned colour scales default to the values of the `ggplot2.binned.colour`
-#' and `ggplot2.binned.fill` options. These option values default to
-#' `"gradient"`, which means that the scale functions actually used are
-#' [scale_colour_gradient()]/[scale_fill_gradient()] for continuous scales and
-#' [scale_colour_steps()]/[scale_fill_steps()] for binned scales.
-#' Alternative option values are `"viridis"` or a different scale function.
-#' See description of the `type` argument for details.
-#'
-#' Note that the binned colour scales will use the settings of
-#' `ggplot2.continuous.colour` and `ggplot2.continuous.fill` as fallback,
-#' respectively, if `ggplot2.binned.colour` or `ggplot2.binned.fill` are
-#' not set.
+#' `r lifecycle::badge("superseded")`: The mechanism of setting defaults via
+#' [options()] is superseded by theme settings. The preferred method to change
+#' the default palette of scales is via the theme, for example:
+#' `theme(palette.colour.continuous = scales::pal_viridis())`. The
+#' `ggplot2.continuous.colour` and `ggplot2.continuous.fill` options could be
+#' used to set default continuous scales and `ggplot2.binned.colour` and
+#' `ggplot2.binned.fill` options to set default binned scales.
 #'
 #' These scale functions are meant to provide simple defaults. If
 #' you want to manually set the colors of a scale, consider using
@@ -35,7 +27,7 @@
 #'   * a palette function that when called with a numeric vector with values
 #'     between 0 and 1 returns the corresponding output values.
 #' @param ... Additional parameters passed on to the scale type
-#' @param type One of the following:
+#' @param type `r lifecycle::badge("superseded")` One of the following:
 #'   * "gradient" (the default)
 #'   * "viridis"
 #'   * A function that returns a continuous colour scale.
@@ -173,9 +165,7 @@ scale_fill_binned <- function(..., palette = NULL, aesthetics = "fill", guide =
 
 #' Discrete colour scales
 #'
-#' The default discrete colour scale. Defaults to [scale_fill_hue()]/[scale_fill_brewer()]
-#' unless `type` (which defaults to the `ggplot2.discrete.fill`/`ggplot2.discrete.colour` options)
-#' is specified.
+#' The default discrete colour scale.
 #'
 #' @param palette One of the following:
 #'   * `NULL` for the default palette stored in the theme.
@@ -185,7 +175,9 @@ scale_fill_binned <- function(..., palette = NULL, aesthetics = "fill", guide =
 #'     number of levels in the scale) returns the values that they should take.
 #' @param ... Additional parameters passed on to the scale type,
 #' @inheritParams discrete_scale
-#' @param type One of the following:
+#' @param type `r lifecycle::badge("superseded")` The preferred mechanism for
+#'   setting the default palette is by using the theme. For example:
+#'   `theme(palette.colour.discrete = "Okabe-Ito")`. One of the following:
 #'   * A character vector of color codes. The codes are used for a 'manual' color
 #'   scale as long as the number of codes exceeds the number of data levels
 #'   (if there are more levels than codes, [scale_colour_hue()]/[scale_fill_hue()]