Skip to content

Commit 152d1d5

Browse files
authored
Update coord_flip() docs (#5150)
* Update `coord_flip()` docs * Communicate `coord_flip()` as superseded
1 parent 5f2011f commit 152d1d5

File tree

3 files changed

+69
-31
lines changed

3 files changed

+69
-31
lines changed

NEWS.md

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
# ggplot2 (development version)
22

3+
* `coord_flip()` has been marked as superseded. The recommended alternative is
4+
to swap the `x` and `y` aesthetic and/or using the `orientation` argument in
5+
a layer (@teunbrand, #5130).
36
* `stat_align()` is now applied per panel instead of globally, preventing issues
47
when facets have different ranges (@teunbrand, #5227).
58
* A stacking bug in `stat_align()` was fixed (@teunbrand, #5176).

R/coord-flip.R

Lines changed: 33 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,48 @@
11
#' Cartesian coordinates with x and y flipped
22
#'
3-
#' Flip cartesian coordinates so that horizontal becomes vertical, and
4-
#' vertical, horizontal. This is primarily useful for converting geoms and
5-
#' statistics which display y conditional on x, to x conditional on y.
3+
#' @description
4+
#' `r lifecycle::badge("superseded")`
5+
#'
6+
#' This function is superseded because in many cases, `coord_flip()` can easily
7+
#' be replaced by swapping the x and y aesthetics, or optionally setting the
8+
#' `orientation` argument in geom and stat layers.
9+
#'
10+
#' `coord_flip()` is useful for geoms and statistics that do not support
11+
#' the `orientation` setting, and converting the display of y conditional on x,
12+
#' to x conditional on y.
613
#'
714
#' @export
815
#' @inheritParams coord_cartesian
916
#' @examples
10-
#' # Very useful for creating boxplots, and other interval
11-
#' # geoms in the horizontal instead of vertical position.
17+
#' # The preferred method of creating horizontal instead of vertical boxplots
18+
#' ggplot(diamonds, aes(price, cut)) +
19+
#' geom_boxplot()
1220
#'
21+
#' # Using `coord_flip()` to make the same plot
1322
#' ggplot(diamonds, aes(cut, price)) +
1423
#' geom_boxplot() +
1524
#' coord_flip()
1625
#'
17-
#' h <- ggplot(diamonds, aes(carat)) +
18-
#' geom_histogram()
19-
#' h
20-
#' h + coord_flip()
21-
#' h + coord_flip() + scale_x_reverse()
26+
#' # With swapped aesthetics, the y-scale controls the left axis
27+
#' ggplot(diamonds, aes(y = carat)) +
28+
#' geom_histogram() +
29+
#' scale_y_reverse()
30+
#'
31+
#' # In `coord_flip()`, the x-scale controls the left axis
32+
#' ggplot(diamonds, aes(carat)) +
33+
#' geom_histogram() +
34+
#' coord_flip() +
35+
#' scale_x_reverse()
2236
#'
23-
#' # You can also use it to flip line and area plots:
24-
#' df <- data.frame(x = 1:5, y = (1:5) ^ 2)
25-
#' ggplot(df, aes(x, y)) +
26-
#' geom_area()
27-
#' last_plot() + coord_flip()
37+
#' # In line and area plots, swapped aesthetics require an explicit orientation
38+
#' df <- data.frame(a = 1:5, b = (1:5) ^ 2)
39+
#' ggplot(df, aes(b, a)) +
40+
#' geom_area(orientation = "y")
41+
#'
42+
#' # The same plot with `coord_flip()`
43+
#' ggplot(df, aes(a, b)) +
44+
#' geom_area() +
45+
#' coord_flip()
2846
coord_flip <- function(xlim = NULL, ylim = NULL, expand = TRUE, clip = "on") {
2947
ggproto(NULL, CoordFlip,
3048
limits = list(x = xlim, y = ylim),

man/coord_flip.Rd

Lines changed: 33 additions & 16 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)