build_plot {ggbuildr}

Incrementally build and save layers of a ggplot object into numbered files

Description

build_plot save a ggplot object incrementally, adding geom layers in the order specified with a list in the build_order argument.

Usage

build_plot(plot, filepath = NULL, build_order, subdir = "builds",
  ext = tools::file_ext(filepath), build_ext = ext, save_full = TRUE,
  save_rds = FALSE, preserve_order = TRUE, ...)

Arguments

plot

ggplot object. The final plot to build towards.

filepath

character string specifying where to save the plot, with or without extensions. If the filepath is given without extension, the ext and/or build_ext arguments must be specified. Non-existing paths are created automatically. If not specified (or set to NULL), plots are printed.

build_order

list of numerical vectors. The order in which to build each layer of the plot, where the first (lowest) layer is 1. Multiple layers can be built at a single increment by specifying the list element as a vector of two or more values.

subdir

character string. Specifies where to save the incremental builds, as opposed to the final, full plot. (default: "builds")

ext

character string. Extension for the full plot. Also used as extension for builds if build_ext is not specified

build_ext

(Optional) character string. If specified, the incremental builds will be saved in this format (e.g., one could save the final plot as a pdf, but save the incremental builds as a png which might be easier to add to slides.)

save_full

logical. Whether or not to save the full plot (default: TRUE)

save_rds

logical. Whether or not to save the full ggplot object as an rds file with the same filepath. (default: FALSE)

preserve_order

logical. Whether or not to keep the original order of the layers. Only relevant if the specified build_order is not monotonically increasing.

...

other arguments, passed to ggsave (e.g. width/height)

Details

The graphic device is either automatically detected from the filepath, or can be set explicitly with ext. By default, the final, complete plot is saved in filepath, and the incremental builds are saved in a subdirectory specified with subdir, "builds" by default. Sometimes, it's useful to also keep the full ggplot object as an rds file for future edits, which can be done by setting the save_rds argument to TRUE.

Value

Saves plots to specified path.

Examples

X <- rnorm(20)
Y <- X + rnorm(20)

set.seed(1)
pd <- data.frame(X, Y)
p <- ggplot(pd, aes(X, Y)) +
  geom_smooth() +
  geom_point()

# Plot smooth, and then point
build_plot(p, build_order = list(1, 2))

# Plot point, and then smooth, but preserve order (i.e, keep points on top)
build_plot(p, build_order = list(2, 1))

# Plot point, and then smooth, and draw smooth layer on top of point
build_plot(p, build_order = list(2, 1), preserve_order = FALSE)