Doc tweaks for scales

Author: hadley

R/geom-linerange.r

@@ -12,7 +12,7 @@
 #' @seealso
 #'  \code{\link{stat_summary}} for examples of these guys in use,
 #'  \code{\link{geom_smooth}} for continuous analog,
-#'  \code{\link{geom_errorh}} for a horizontal error bar.
+#'  \code{\link{geom_errorbarh}} for a horizontal error bar.
 #' @export
 #' @inheritParams layer
 #' @inheritParams geom_point

R/guide-colorbar.r

@@ -1,4 +1,4 @@
-#' Continuous colour bar guide.
+#' Continuous colour bar guide
 #'
 #' Colour bar guide shows continuous color scales mapped onto values.
 #' Colour bar is available with \code{scale_fill} and \code{scale_colour}.

R/labels.r

@@ -2,6 +2,7 @@
 #'
 #' @param p plot to modify
 #' @param labels named list of new labels
+#' @keywords internal
 #' @export
 #' @examples
 #' p <- ggplot(mtcars, aes(mpg, wt)) + geom_point()
@@ -15,42 +16,37 @@ update_labels <- function(p, labels) {
   p
 }
 
-#' Change axis labels, legend titles, plot title/subtitle and below-plot
-#' caption.
+#' Modify axis, legend, and plot labels
+#'
+#' Good labels are critical for making your plots accessible to a wider
+#' audience. Ensure the axis and legend labels display the full variable name.
+#' Use the plot \code{title} and \code{subtitle} to explain the main findings.
+#' It's common to use the \code{caption} to provide information about the
+#' data source.
+#'
+#' You can also set axis and legend labels in the individual scales (using
+#' the first argument, the \code{name}. I recommend doing that if you're
+#' changing other scale options.
 #'
 #' @param label The text for the axis, plot title or caption below the plot.
 #' @param subtitle the text for the subtitle for the plot which will be
 #'        displayed below the title. Leave \code{NULL} for no subtitle.
-#' @param ... a list of new names in the form aesthetic = "new name"
+#' @param ... A list of new name-value pairs. The name should either be
+#'   an aesthetic, or one of "title", "subtitle", or "caption".
 #' @export
 #' @examples
-#' p <- ggplot(mtcars, aes(mpg, wt)) + geom_point()
-#' p + labs(title = "New plot title")
+#' p <- ggplot(mtcars, aes(mpg, wt, colour = cyl)) + geom_point()
+#' p + labs(colour = "Cylinders")
 #' p + labs(x = "New x label")
-#' p + xlab("New x label")
-#' p + ylab("New y label")
-#' p + ggtitle("New plot title")
 #'
-#' # Can add a subtitle to plots with either of the following
-#' p + ggtitle("New plot title", subtitle = "A subtitle")
+#' # The plot title appears at the top-left, with the subtitle
+#' # display in smaller text underneath it
+#' p + labs(title = "New plot title")
 #' p + labs(title = "New plot title", subtitle = "A subtitle")
 #'
-#' # Can add a plot caption underneath the whole plot (for sources, notes or
-#' # copyright), similar to the \code{sub} parameter in base R, with the
-#' # following
+#' # The caption appears in the bottom-right, and is often used for
+#' # sources, notes or copyright
 #' p + labs(caption = "(based on data from ...)")
-#'
-#' # This should work independently of other functions that modify the
-#' # the scale names
-#' p + ylab("New y label") + ylim(2, 4)
-#' p + ylim(2, 4) + ylab("New y label")
-#'
-#' # The labs function also modifies legend labels
-#' p <- ggplot(mtcars, aes(mpg, wt, colour = cyl)) + geom_point()
-#' p + labs(colour = "Cylinders")
-#'
-#' # Can also pass in a list, if that is more convenient
-#' p + labs(list(title = "Title", subtitle = "Subtitle", x = "X", y = "Y"))
 labs <- function(...) {
   args <- list(...)
   if (is.list(args[[1]])) args <- args[[1]]

R/limits.r

@@ -1,34 +1,51 @@
-#' Convenience functions to set the axis limits.
+#' Set scale limits
 #'
-#' Observations not in this range will be dropped completely and
-#' not passed to any other layers.  If a NA value is substituted for one of the
-#' limits that limit is automatically calculated.
+#' This is a shortcut for supplying the \code{limits} argument to the
+#' individual scales. Note that, by default, any values outside the limits
+#' will be replaced with \code{NA}.
 #'
-#' @param ... If numeric, will create a continuous scale, if factor or
-#'   character, will create a discrete scale.  For \code{lims}, every
-#'   argument must be named.
+#' @param ... A name-value pair. The name must be an aesthetic, and the value
+#'   must be either a length-2 numeric, a character, a factor, or a date/time.
+#'
+#'   A numeric value will create a continuous scale. If the larger value
+#'   comes first, the scale will be reversed. You can leave one value as
+#'   \code{NA} to compute from the range of the data.
+#'
+#'   A character or factor value will create a discrete scale.
+#'
+#'   A date-time value will create a continuous date/time scale.
 #' @seealso For changing x or y axis limits \strong{without} dropping data
-#'   observations, see \code{\link{coord_cartesian}}.
+#'   observations, see \code{\link{coord_cartesian}}. To expand the range of
+#'   a plot to always include certain values, see \code{\link{expand_limits}}.
 #' @export
 #' @examples
-#' # xlim
-#' xlim(15, 20)
-#' xlim(20, 15)
-#' xlim(c(10, 20))
-#' xlim("a", "b", "c")
-#'
+#' # Zoom into a specified area
 #' ggplot(mtcars, aes(mpg, wt)) +
 #'   geom_point() +
 #'   xlim(15, 20)
+#'
+#' # reverse scale
+#' ggplot(mtcars, aes(mpg, wt)) +
+#'   geom_point() +
+#'   xlim(20, 15)
+#'
 #' # with automatic lower limit
 #' ggplot(mtcars, aes(mpg, wt)) +
 #'   geom_point() +
 #'   xlim(NA, 20)
 #'
-#' # Change both xlim and ylim
-#' ggplot(mtcars, aes(mpg, wt)) +
+#' # You can also supply limits that are larger than the data.
+#' # This is useful if you want to match scales across different plots
+#' small <- subset(mtcars, cyl == 4)
+#' big <- subset(mtcars, cyl > 4)
+#'
+#' ggplot(small, aes(mpg, wt, colour = factor(cyl))) +
+#'   geom_point() +
+#'   lims(colour = c("4", "6", "8"))
+#'
+#' ggplot(big, aes(mpg, wt, colour = factor(cyl))) +
 #'   geom_point() +
-#'   lims(x = c(10, 20), y = c(3, 5))
+#'   lims(colour = c("4", "6", "8"))
 lims <- function(...) {
   args <- list(...)
 
@@ -104,9 +121,9 @@ limits.POSIXlt <- function(lims, var) {
   make_scale("datetime", var, limits = as.POSIXct(lims))
 }
 
-#' Expand the plot limits with data.
+#' Expand the plot limits, using data
 #'
-#. Sometimes you may want to ensure limits include a single value, for all
+#' Sometimes you may want to ensure limits include a single value, for all
 #' panels or all plots.  This function is a thin wrapper around
 #' \code{\link{geom_blank}} that makes it easy to add such values.
 #'

R/scale-alpha.r

@@ -1,24 +1,23 @@
-#' Alpha scales.
+#' Alpha transparency scales
 #'
+#' Alpha-transparency scales are not tremendously useful, but can be a
+#' convenient way to visually down-weight less important observations.
 #' \code{scale_alpha} is an alias for \code{scale_alpha_continuous} since
 #' that is the most common use of alpha, and it saves a bit of typing.
 #'
 #' @param ... Other arguments passed on to \code{\link{continuous_scale}}
 #'   or \code{\link{discrete_scale}} as appropriate, to control name, limits,
 #'   breaks, labels and so forth.
-#' @param range range of output alpha values.  Should lie between 0 and 1.
+#' @param range Output range of alpha values. Must lie between 0 and 1.
+#' @family colour scales
 #' @export
 #' @examples
-#' (p <- ggplot(mtcars, aes(mpg, cyl)) +
-#'   geom_point(aes(alpha = cyl)))
-#' p + scale_alpha("cylinders")
-#' p + scale_alpha("number\nof\ncylinders")
+#' p <- ggplot(mpg, aes(displ, hwy)) +
+#'   geom_point(aes(alpha = year))
 #'
+#' p
+#' p + scale_alpha("cylinders")
 #' p + scale_alpha(range = c(0.4, 0.8))
-#'
-#' (p <- ggplot(mtcars, aes(mpg, cyl)) +
-#'   geom_point(aes(alpha = factor(cyl))))
-#' p + scale_alpha_discrete(range = c(0.4, 0.8))
 scale_alpha <- function(..., range = c(0.1, 1)) {
   continuous_scale("alpha", "alpha_c", rescale_pal(range), ...)
 }

R/scale-brewer.r

@@ -1,14 +1,19 @@
 #' Sequential, diverging and qualitative colour scales from colorbrewer.org
 #'
-#' ColorBrewer provides sequential, diverging and qualitative colour schemes
-#' which are particularly suited and tested to display discrete values (levels
-#' of a factor) on a map. ggplot2 can use those colours in discrete scales. It
-#' also allows to smoothly interpolate 6 colours from any palette to a
-#' continuous scale (6 colours per palette gives nice gradients; more results in
-#' more saturated colours which do not look as good). However, the original
-#' colour schemes (particularly the qualitative ones) were not intended for this
-#' and the perceptual result is left to the appreciation of the user.
-#' See \url{http://colorbrewer2.org} for more information.
+#' @description
+#' The \code{brewer} scales provides sequential, diverging and qualitative
+#' colour schemes from ColorBrewer. These are particularly well suited to
+#' display discrete values on a map. See \url{http://colorbrewer2.org} for
+#' more information.
+#'
+#' @note
+#' The \code{distiller} scales extends brewer to continuous scales by smoothly
+#' interpolate 6 colours from any palette to a continuous scale.
+#'
+#' @details
+#' The \code{brewer} scales were carefully designed and tested on discrete data.
+#' They were not designed to be extended to continuous data, but results often
+#' look good. Your mileage may vary.
 #'
 #' @section Palettes:
 #' The following palettes are available for use with these scales:
@@ -23,19 +28,16 @@
 #' @inheritParams scale_colour_hue
 #' @inheritParams scale_colour_gradient
 #' @inheritParams scales::gradient_n_pal
-#' @seealso Other colour scales:
-#'   \code{\link{scale_colour_gradient}},
-#'   \code{\link{scale_colour_grey}},
-#'   \code{\link{scale_colour_hue}}
+#' @family colour scales
 #' @rdname scale_brewer
 #' @export
 #' @examples
 #' dsamp <- diamonds[sample(nrow(diamonds), 1000), ]
 #' (d <- ggplot(dsamp, aes(carat, price)) +
 #'   geom_point(aes(colour = clarity)))
+#' d + scale_colour_brewer()
 #'
 #' # Change scale label
-#' d + scale_colour_brewer()
 #' d + scale_colour_brewer("Diamond\nclarity")
 #'
 #' # Select brewer palette to use, see ?scales::brewer_pal for more details

R/scale-continuous.r

@@ -1,78 +1,70 @@
-#' Continuous position scales (x & y).
+#' Position scales for continuous data (x & y)
 #'
-#' \code{scale_x_continuous} and \code{scale_y_continuous} are the key functions.
-#' The others, \code{scale_x_log10}, \code{scale_y_sqrt} etc, are aliases
-#' that set the \code{trans} argument to commonly used transformations.
+#' \code{scale_x_continuous} and \code{scale_y_continuous} are the default
+#' scales for continuous x and y aesthetics. There are three variants
+#' that set the \code{trans} argument for commonly used transformations:
+#' \code{scale_*_log10}, \code{scale_*_sqrt} and \code{scale_*_reverse}.
+#'
+#' For simple manipulation of labels and limits, you may wish to use
+#' \code{\link{labs}()} and \code{\link{lims}()} instead.
 #'
 #' @inheritParams continuous_scale
-#' @seealso \code{\link{scale_date}} for date/time position scales.
+#' @family position scales
 #' @param ... Other arguments passed on to \code{scale_(x|y)_continuous}
 #' @examples
-#' \donttest{
-#' if (require(ggplot2movies)) {
-#' m <- ggplot(subset(movies, votes > 1000), aes(rating, votes)) +
-#'   geom_point(na.rm = TRUE)
-#' m
+#' p1 <- ggplot(mpg, aes(displ, hwy)) +
+#'   geom_point()
+#' p1
 #'
 #' # Manipulating the default position scales lets you:
-#'
 #' #  * change the axis labels
-#' m + scale_y_continuous("number of votes")
-#' m + scale_y_continuous(quote(votes ^ alpha))
+#' p1 +
+#'   scale_x_continuous("Engine displacement (L)") +
+#'   scale_y_continuous("Highway MPG")
+#'
+#' # You can also use the short-cut labs().
+#' # Use NULL to suppress axis labels
+#' p1 + labs(x = NULL, y = NULL)
 #'
 #' #  * modify the axis limits
-#' m + scale_y_continuous(limits = c(0, 5000))
-#' m + scale_y_continuous(limits = c(1000, 10000))
-#' m + scale_x_continuous(limits = c(7, 8))
+#' p1 + scale_x_continuous(limits = c(2, 6))
+#' p1 + scale_x_continuous(limits = c(0, 10))
 #'
-#' # you can also use the short hand functions xlim and ylim
-#' m + ylim(0, 5000)
-#' m + ylim(1000, 10000)
-#' m + xlim(7, 8)
+#' # you can also use the short hand functions `xlim()` and `ylim()`
+#' p1 + xlim(2, 6)
 #'
 #' #  * choose where the ticks appear
-#' m + scale_x_continuous(breaks = 1:10)
-#' m + scale_x_continuous(breaks = c(1,3,7,9))
-#'
-#' #  * manually label the ticks
-#' m + scale_x_continuous(breaks = c(2,5,8), labels = c("two", "five", "eight"))
-#' m + scale_x_continuous(breaks = c(2,5,8), labels = c("horrible", "ok", "awesome"))
-#' m + scale_x_continuous(breaks = c(2,5,8), labels = expression(Alpha, Beta, Omega))
+#' p1 + scale_x_continuous(breaks = c(2, 4, 6))
 #'
-#' # There are a few built in transformation that you can use:
-#' m + scale_y_log10()
-#' m + scale_y_sqrt()
-#' m + scale_y_reverse()
-#' # You can also create your own and supply them to the trans argument.
-#' # See ?scales::trans_new
+#' #  * add what labels they have
+#' p1 + scale_x_continuous(
+#'   breaks = c(2, 4, 6),
+#'   label = c("two", "four", "six")
+#' )
 #'
-#' # You can control the formatting of the labels with the formatter
-#' # argument.  Some common formats are built into the scales package:
+#' # Typically you'll pass a function to the `labels` argument.
+#' # Some common formats are built into the scales package:
 #' df <- data.frame(
 #'   x = rnorm(10) * 100000,
 #'   y = seq(0, 1, length.out = 10)
 #' )
-#' p <- ggplot(df, aes(x, y)) + geom_point()
-#' p + scale_y_continuous(labels = scales::percent)
-#' p + scale_y_continuous(labels = scales::dollar)
-#' p + scale_x_continuous(labels = scales::comma)
+#' p2 <- ggplot(df, aes(x, y)) + geom_point()
+#' p2 + scale_y_continuous(labels = scales::percent)
+#' p2 + scale_y_continuous(labels = scales::dollar)
+#' p2 + scale_x_continuous(labels = scales::comma)
+#'
+#' # You can also override the default linear mapping by using a
+#' # transformation. There are three shortcuts:
+#' p1 + scale_y_log10()
+#' p1 + scale_y_sqrt()
+#' p1 + scale_y_reverse()
+#'
+#' # Or you can supply a transformation in the `trans` argument:
+#' p1 + scale_y_continuous(trans = scales::reciprocal_trans())
 #'
-#' # Other shortcut functions
-#' ggplot(movies, aes(rating, votes)) +
-#'   geom_point() +
-#'   ylim(1e4, 5e4)
-#' #   * axis labels
-#' ggplot(movies, aes(rating, votes)) +
-#'   geom_point() +
-#'   labs(x = "My x axis", y = "My y axis")
-#' #   * log scaling
-#' ggplot(movies, aes(rating, votes)) +
-#'   geom_point() +
-#'   scale_x_log10() +
-#'   scale_y_log10()
-#' }
-#' }
+#' # You can also create your own. See ?scales::trans_new
 #' @name scale_continuous
+#' @aliases NULL
 NULL
 
 #' @rdname scale_continuous