move and merge docs to coord_radial()

Author: teunbrand

R/coord-polar.R

@@ -1,67 +1,5 @@
-#' 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_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)
-#' }
-#' }
 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"

R/coord-radial.R

@@ -1,6 +1,16 @@
-
-#' @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. `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()`].
 #' @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 +36,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 +45,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 +533,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]