Examples of plotting automation (#5745)

* write docpage for plotting automation

* crosslink docs

* reoxygenate

* add pkgdown entry

Author: teunbrand

R/autolayer.R

@@ -8,7 +8,7 @@
 #' @param ... other arguments passed to specific methods
 #' @return a ggplot layer
 #' @export
-#' @seealso [autoplot()], [ggplot()] and [fortify()]
+#' @family plotting automation topics
 autolayer <- function(object, ...) {
   UseMethod("autolayer")
 }

R/autoplot.R

@@ -1,3 +1,115 @@
+#' Tailoring plots to particular data types
+#'
+#' @description
+#' There are three functions to make plotting particular data types easier:
+#' `autoplot()`, `autolayer()` and `fortify()`. These are S3 generics for which
+#' other packages can write methods to display classes of data. The three
+#' functions are complementary and allow different levels of customisation.
+#' Below we'll explore implementing this series of methods to automate plotting
+#' of some class.
+#'
+#' Let's suppose we are writing a packages that has a class called 'my_heatmap',
+#' that wraps a matrix and we'd like users to easily plot this heatmap.
+#'
+#' ```r
+#' my_heatmap <- function(...) {
+#'   m <- matrix(...)
+#'   class(m) <- c("my_heatmap", class(m))
+#'   m
+#' }
+#'
+#' my_data <- my_heatmap(volcano)
+#' ```
+#'
+#' # Automatic data shaping
+#'
+#' One of the things we have to do is ensure that the data is shaped in the long
+#' format so that it is compatible with ggplot2. This is the job of the
+#' `fortify()` function. Because 'my_heatmap' wraps a matrix, we can let the
+#' fortify method 'melt' the matrix to a long format. If your data is already
+#' based on a long-format `<data.frame>`, you can skip implementing a
+#' `fortify()` method.
+#'
+#' ```r
+#' fortify.my_heatmap <- function(model, ...) {
+#'   data.frame(
+#'     row = as.vector(row(model)),
+#'     col = as.vector(col(model)),
+#'     value = as.vector(model)
+#'   )
+#' }
+#'
+#' fortify(my_data)
+#' ```
+#'
+#' When you have implemented the `fortify()` method, it should be easier to
+#' construct a plot with the data than with the matrix.
+#'
+#' ```r
+#' ggplot(my_data, aes(x = col, y = row, fill = value)) +
+#'   geom_raster()
+#' ```
+#'
+#' # Automatic layers
+#'
+#' A next step in automating plotting of your data type is to write an
+#' `autolayer()` method. These are typically wrappers around geoms or stats
+#' that automatically set aesthetics or other parameters. If you haven't
+#' implemented a `fortify()` method for your data type, you might have to
+#' reshape the data in `autolayer()`.
+#'
+#' If you require multiple layers to display your data type, you can use an
+#' `autolayer()` method that constructs a list of layers, which can be added
+#' to a plot.
+#'
+#' ```r
+#' autolayer.my_heatmap <- function(object, ...) {
+#'   geom_raster(
+#'     mapping = aes(x = col, y = row, fill = value),
+#'     data = object,
+#'     ...,
+#'     inherit.aes = FALSE
+#'   )
+#' }
+#'
+#' ggplot() + autolayer(my_data)
+#' ```
+#'
+#' As a quick tip: if you define a mapping in `autolayer()`, you might want
+#' to set `inherit.aes = FALSE` to not have aesthetics set in other layers
+#' interfere with your layer.
+#'
+#' # Automatic plots
+#'
+#' The last step in automating plotting is to write an `autoplot()` method
+#' for your data type. The expectation is that these return a complete plot.
+#' In the example below, we're exploiting the `autolayer()` method that we
+#' have already written to make a complete plot.
+#'
+#' ```r
+#' autoplot.my_heatmap <- function(object, ..., option = "magma") {
+#'   ggplot() +
+#'     autolayer(my_data) +
+#'     scale_fill_viridis_c(option = option) +
+#'     theme_void()
+#' }
+#'
+#' autoplot(my_data)
+#' ```
+#'
+#' If you don't have a wish to implement a base R plotting method, you
+#' can set the plot method for your class to the autoplot method.
+#'
+#' ```r
+#' plot.my_heatmap <- autoplot.my_heatmap
+#' plot(my_data)
+#' ```
+#'
+#' @family plotting automation topics
+#'
+#' @name automatic_plotting
+NULL
+
 #' Create a complete ggplot appropriate to a particular data type
 #'
 #' `autoplot()` uses ggplot2 to draw a particular plot for an object of a
@@ -8,7 +120,7 @@
 #' @param ... other arguments passed to specific methods
 #' @return a ggplot object
 #' @export
-#' @seealso [autolayer()], [ggplot()] and [fortify()]
+#' @family plotting automation topics
 autoplot <- function(object, ...) {
   UseMethod("autoplot")
 }

R/fortify.R

@@ -4,6 +4,7 @@
 #' package, which implements a much wider range of methods. `fortify()`
 #' may be deprecated in the future.
 #'
+#' @family plotting automation topics
 #' @seealso [fortify.lm()]
 #' @param model model or other R object to convert to data frame
 #' @param data original dataset, if needed

_pkgdown.yml

@@ -244,6 +244,7 @@ reference:
   - autolayer
   - fortify
   - map_data
+  - automatic_plotting
 
 
 articles: