Improve theme docs

Author: hadley

NEWS.md

@@ -111,7 +111,8 @@ There were also a number of other smaller changes
 ## Themes
 
 * The `theme()` constructor now has named arguments rather than ellipsis. This 
-  should make autocomplete substantially more useful.
+  should make autocomplete substantially more useful. The documentation has
+  been considerably improved.
 
 * Built-in themes are more visually homogeneous, and match `theme_grey` better.
   (@jiho, #1679)

R/theme.r

@@ -65,21 +65,12 @@ print.theme <- function(x, ...) utils::str(x)
 
 #' Set theme elements
 #'
-#'
-#' Use this function to modify theme settings.
-#'
 #' Theme elements can inherit properties from other theme elements.
 #' For example, \code{axis.title.x} inherits from \code{axis.title},
 #' which in turn inherits from \code{text}. All text elements inherit
 #' directly or indirectly from \code{text}; all lines inherit from
 #' \code{line}, and all rectangular objects inherit from \code{rect}.
 #'
-#' For more examples of modifying properties using inheritance, see
-#' \code{\link{+.gg}} and \code{\link{\%+replace\%}}.
-#'
-#' To see a graphical representation of the inheritance tree, see the
-#' last example below.
-#'
 #' @param line all line elements (\code{element_line})
 #' @param rect all rectangular elements (\code{element_rect})
 #' @param text all text elements (\code{element_text})
@@ -225,150 +216,102 @@ print.theme <- function(x, ...) utils::str(x)
 #'   differently when added to a ggplot object. Also, when setting
 #'   \code{complete = TRUE} all elements will be set to inherit from blank
 #'   elements.
-#' @param validate TRUE to run validate_element, FALSE to bypass checks.
-#'
-#' @seealso \code{\link{+.gg}}
-#' @seealso \code{\link{\%+replace\%}}
-#' @seealso \code{\link{rel}}
-#' @seealso \code{\link{element_blank}}
-#' @seealso \code{\link{element_line}}
-#' @seealso \code{\link{element_rect}}
-#' @seealso \code{\link{element_text}}
+#' @param validate \code{TRUE} to run validate_element, \code{FALSE} to bypass checks.
+#'
+#' @seealso
+#'   \code{\link{+.gg}} and \code{\link{\%+replace\%}},
+#'   \code{\link{rel}} for details of relative sizing,
+#'   \code{\link{element_blank}}, \code{\link{element_line}},
+#'   \code{\link{element_rect}}, and \code{\link{element_text}} for
+#'   details of the specific theme elements.
 #' @export
 #' @examples
-#' \donttest{
-#' p <- ggplot(mtcars, aes(mpg, wt)) +
-#'   geom_point()
-#' p
-#' p + theme(panel.background = element_rect(colour = "pink"))
-#' p + theme_bw()
+#' p1 <- ggplot(mtcars, aes(wt, mpg)) +
+#'   geom_point() +
+#'   labs(title = "Fuel economy declines as weight increases")
+#' p1
+#'
+#' # Plot ---------------------------------------------------------------------
+#' p1 + theme(plot.title = element_text(size = rel(2)))
+#' p1 + theme(plot.background = element_rect(fill = "green"))
+#'
+#' # Panels --------------------------------------------------------------------
+#'
+#' p1 + theme(panel.background = element_rect(fill = "white", colour = "grey50"))
+#' p1 + theme(panel.border = element_rect(linetype = "dashed", fill = NA))
+#' p1 + theme(panel.grid.major = element_line(colour = "black"))
+#' p1 + theme(
+#'   panel.grid.major.y = element_blank(),
+#'   panel.grid.minor.y = element_blank()
+#' )
+#'
+#' # Put gridlines on top of data
+#' p1 + theme(
+#'   panel.background = element_rect(fill = NA),
+#'   panel.grid.major = element_line(colour = "grey50"),
+#'   panel.ontop = TRUE
+#' )
+#'
+#' # Axes ----------------------------------------------------------------------
+#' p1 + theme(axis.line = element_line(size = 3, colour = "grey80"))
+#' p1 + theme(axis.text = element_text(colour = "blue"))
+#' p1 + theme(axis.ticks = element_line(size = 2))
+#' p1 + theme(axis.ticks.length = unit(.25, "cm"))
+#' p1 + theme(axis.title.y = element_text(size = rel(1.5), angle = 90))
 #'
-#' # Scatter plot of gas mileage by vehicle weight
-#' p <- ggplot(mtcars, aes(wt, mpg)) +
-#'   geom_point()
-#' # Calculate slope and intercept of line of best fit
-#' coef(lm(mpg ~ wt, data = mtcars))
-#' p + geom_abline(intercept = 37, slope = -5)
-#' # Calculate correlation coefficient
-#' with(mtcars, cor(wt, mpg, use = "everything", method = "pearson"))
-#' #annotate the plot
-#' p + geom_abline(intercept = 37, slope = -5) +
-#' geom_text(data = data.frame(), aes(4.5, 30, label = "Pearson-R = -.87"))
-#'
-#' # Change the axis labels
-#' # Original plot
-#' p
-#' p + labs(x = "Vehicle Weight", y = "Miles per Gallon")
-#' # Or
-#' p + labs(x = "Vehicle Weight", y = "Miles per Gallon")
-#'
-#' # Change title appearance
-#' p <- p + labs(title = "Vehicle Weight-Gas Mileage Relationship")
-#' # Set title to twice the base font size
-#' p + theme(plot.title = element_text(size = rel(2)))
-#' p + theme(plot.title = element_text(size = rel(2), colour = "blue"))
-#'
-#' # Add a subtitle and adjust bottom margin
-#' p + labs(title = "Vehicle Weight-Gas Mileage Relationship",
-#'          subtitle = "You need to wrap long subtitleson manually") +
-#'     theme(plot.subtitle = element_text(margin = margin(b = 20)))
-#'
-#' # Changing plot look with themes
-#' DF <- data.frame(x = rnorm(400))
-#' m <- ggplot(DF, aes(x = x)) +
-#'   geom_histogram()
-#' # Default is theme_grey()
-#' m
-#' # Compare with
-#' m + theme_bw()
-#'
-#' # Manipulate Axis Attributes
-#' m + theme(axis.line = element_line(size = 3, colour = "red", linetype = "dotted"))
-#' m + theme(axis.text = element_text(colour = "blue"))
-#' m + theme(axis.text.y = element_blank())
-#' m + theme(axis.ticks = element_line(size = 2))
-#' m + theme(axis.title.y = element_text(size = rel(1.5), angle = 90))
-#' m + theme(axis.title.x = element_blank())
-#' m + theme(axis.ticks.length = unit(.85, "cm"))
-#'
-#' # Legend Attributes
-#' z <- ggplot(mtcars, aes(wt, mpg)) +
-#'   geom_point(aes(colour = factor(cyl)))
-#' z
-#' z + theme(legend.position = "none")
-#' z + theme(legend.position = "bottom")
-#' # Or use relative coordinates between 0 and 1
-#' z + theme(legend.position = c(.5, .5))
-#' # Add a border to the whole legend
-#' z + theme(legend.background = element_rect(colour = "black"))
-#' # Legend margin controls extra space around outside of legend:
-#' z + theme(legend.background = element_rect(),
-#'           legend.margin = margin(1, 1, 1, 1, "cm"))
-#' z + theme(legend.background = element_rect(),
-#'           legend.margin = margin(0, 0, 0, 0, "cm"))
-#' # Legend spacing pushes legends apart
-#' z + theme(legend.background = element_rect(),
-#'           legend.margin = margin(1, 1, 1, 1, "cm"),
-#'           legend.spacing = unit(1, "cm"))
-#' # A border and background can also be added around the whole legend area
-#' z + theme(legend.box.background = element_rect(),
-#'           legend.box.margin = margin(5, 5, 5, 5, "mm"))
-#' # The distance from the plot area can be set with legend.box.spacing
-#' z + theme(legend.box.spacing = unit(3, "cm"))
+#' \donttest{
+#' # Legend --------------------------------------------------------------------
+#' p2 <- ggplot(mtcars, aes(wt, mpg)) +
+#'   geom_point(aes(colour = factor(cyl), shape = factor(vs))) +
+#'   labs(
+#'     x = "Weight (1000 lbs)",
+#'     y = "Fuel economy (mpg)",
+#'     colour = "Cylinders",
+#'     shape = "Transmission"
+#'    )
+#' p2
+#'
+#' # Position
+#' p2 + theme(legend.position = "none")
+#' p2 + theme(legend.justification = "top")
+#'
+#' p2 + theme(legend.position = "bottom")
+#' p2 + theme(
+#'   legend.position = "bottom",
+#'   legend.box = "horizontal",
+#'   legend.justification = "left"
+#' )
+#' # Or place inside the plot using relative coordinates between 0 and 1
+#' p2 + theme(
+#'   legend.justification = c("right", "top"),
+#'   legend.box.just = "right",
+#'   legend.position = c(.95, .95),
+#'   legend.margin = margin(6, 6, 6, 6)
+#' )
+#'
+#' # The legend.box properties work similarly for the space around
+#' # all the legends
+#' p2 + theme(
+#'   legend.box.background = element_rect(),
+#'   legend.box.margin = margin(6, 6, 6, 6)
+#' )
+#'
+#' # You can also control the display of the keys
 #' # and the justifaction related to the plot area can be set
-#' z + theme(legend.justification = "bottom")
-#' # Or to just the keys
-#' z + theme(legend.key = element_rect(colour = "black"))
-#' z + theme(legend.key = element_rect(fill = "yellow"))
-#' z + theme(legend.key.size = unit(2.5, "cm"))
-#' z + theme(legend.text = element_text(size = 20, colour = "red", angle = 45))
-#' z + theme(legend.title = element_text(face = "italic"))
-#'
-#' # To change the title of the legend use the name argument
-#' # in one of the scale options
-#' z + scale_colour_brewer(name = "My Legend")
-#' z + scale_colour_grey(name = "Number of \nCylinders")
-#'
-#' # Panel and Plot Attributes
-#' z + theme(panel.background = element_rect(fill = "black"))
-#' z + theme(panel.border = element_rect(linetype = "dashed", colour = "black"))
-#' z + theme(panel.grid.major = element_line(colour = "blue"))
-#' z + theme(panel.grid.minor = element_line(colour = "red", linetype = "dotted"))
-#' z + theme(panel.grid.major = element_line(size = 2))
-#' z + theme(panel.grid.major.y = element_blank(),
-#'           panel.grid.minor.y = element_blank())
-#' z + theme(plot.background = element_rect())
-#' z + theme(plot.background = element_rect(fill = "green"))
-#'
-#' # Faceting Attributes
-#' set.seed(4940)
-#' dsmall <- diamonds[sample(nrow(diamonds), 1000), ]
-#' k <- ggplot(dsmall, aes(carat, ..density..)) +
-#'   geom_histogram(binwidth = 0.2) +
-#'   facet_grid(. ~ cut)
-#' k + theme(strip.background = element_rect(colour = "purple", fill = "pink",
-#'                                           size = 3, linetype = "dashed"))
-#' k + theme(strip.text.x = element_text(colour = "red", angle = 45, size = 10,
-#'                                       hjust = 0.5, vjust = 0.5))
-#' k + theme(panel.spacing = unit(5, "lines"))
-#' k + theme(panel.spacing.y = unit(0, "lines"))
-#'
-#' # Put gridlines on top
-#' meanprice <- tapply(diamonds$price, diamonds$cut, mean)
-#' cut <- factor(levels(diamonds$cut), levels = levels(diamonds$cut))
-#' df <- data.frame(meanprice, cut)
-#' g <- ggplot(df, aes(cut, meanprice)) + geom_bar(stat = "identity")
-#' g + geom_bar(stat = "identity") +
-#'     theme(panel.background = element_blank(),
-#'           panel.grid.major.x = element_blank(),
-#'           panel.grid.minor.x = element_blank(),
-#'           panel.grid.minor.y = element_blank(),
-#'           panel.ontop = TRUE)
-#'
-#' # Modify a theme and save it
-#' mytheme <- theme_grey() + theme(plot.title = element_text(colour = "red"))
-#' p + mytheme
+#' p2 + theme(legend.key = element_rect(fill = "white", colour = "black"))
+#' p2 + theme(legend.text = element_text(size = 8, colour = "red"))
+#' p2 + theme(legend.title = element_text(face = "bold"))
+#'
+#' # Strips --------------------------------------------------------------------
+#'
+#' p3 <- ggplot(mtcars, aes(wt, mpg)) +
+#'   geom_point() +
+#'   facet_wrap(~ cyl)
+#' p3
 #'
+#' p3 + theme(strip.background = element_rect(colour = "black", fill = "white"))
+#' p3 + theme(strip.text.x = element_text(colour = "white", face = "bold"))
+#' p3 + theme(panel.spacing = unit(1, "lines"))
 #' }
 theme <- function(line,
                   rect,