Save graphs with theme61 styles and defaults

Saves ggplot2 graphs made using theme61. Using save_e61() is required to ensure graphs are consistent with the e61 style and formatting.

Usage

save_e61(
  filename = NULL,
  ...,
  plot = last_plot(),
  plotlist = NULL,
  labs = list(title = NULL, subtitle = NULL, footnotes = NULL, sources = NULL),
  layout = list(ncol = 2, nrow = NULL, align = "v", axis = "none"),
  spacing = list(pad_width = 0, pad_height = 0, outer_width = NULL, outer_height = NULL,
    height_adj = NULL, rel_heights = NULL, title = 1, subtitle = 1),
  dim = list(height = NULL, width = NULL),
  format = c("svg", "pdf", "eps", "png", "jpg"),
  chart_type = NULL,
  auto_scale = TRUE,
  max_height = NULL,
  save_data = FALSE,
  print_info = FALSE,
  print_label_positions = FALSE,
  fast_labels = FALSE,
  spell_check = TRUE,
  preview = FALSE,
  base_size = 10,
  res = 1,
  bg_colour = "white",
  build_up = FALSE,
  build_up_n = NULL,
  return_plot_obj = FALSE,
  title = lifecycle::deprecated(),
  subtitle = lifecycle::deprecated(),
  footnotes = lifecycle::deprecated(),
  sources = lifecycle::deprecated(),
  ncol = lifecycle::deprecated(),
  nrow = lifecycle::deprecated(),
  align = lifecycle::deprecated(),
  axis = lifecycle::deprecated(),
  pad_width = lifecycle::deprecated(),
  pad_height = lifecycle::deprecated(),
  outer_width = lifecycle::deprecated(),
  outer_height = lifecycle::deprecated(),
  height_adj = lifecycle::deprecated(),
  rel_heights = lifecycle::deprecated(),
  spacing_adj = lifecycle::deprecated()
)

Arguments

filename

File name to create on disk. Providing the file format extension (e.g. .svg) is suggested when saving to a single file format. The file extension must be lowercase. If you want to save to multiple formats, do not include the extension, see the format argument for details.

...

(multi-panel specific) Plot objects to put on the panel.

plot

(single-panel specific) Name of the plot object to save. Defaults to the last plot displayed so usually you do not need to provide this argument explicitly.

plotlist

(multi-panel specific) List of plots to combine as an multi-panel and save. You can also enter the charts individually as arguments to the function.

labs

(multi-panel specific) A named list specifying the shared title, subtitle, footnotes and sources to place around the multi-panel figure. Defaults to NULL for each.

layout

(multi-panel specific) A named list specifying the panel grid: ncol, nrow, align and axis. See patchwork::plot_layout() for what align and axis do. Defaults to list(ncol = 2, nrow = NULL, align = "v", axis = "none").

spacing

(multi-panel specific) A named list controlling whitespace and relative sizing:

pad_width, pad_height: Numeric (mm). Adds horizontal/vertical whitespace to the sides of all graphs. If saving multiple charts this will add the same spacing to all charts. Defaults to no additional padding.
outer_width: Numeric (mm). Overrides the margin between the left/right edges of the figure and the outermost panels. Defaults to NULL, which uses the built-in margin (0mm). Set higher to add whitespace around the outer edge of the figure; unlike pad_width, this does not affect the gap between panels.
outer_height: Numeric (mm). Overrides the margin between the top/bottom edges of the figure (i.e. above the title and below the footnotes/sources) and the panels. Defaults to NULL, which uses the built-in margin (0mm). Set higher to add whitespace around the outer edge of the figure; unlike pad_height, this does not affect the gap between panel rows.
height_adj: Rescales the height of the multi-panel. The function sets sensible defaults but this provides you with manual control if you need it.
rel_heights: A numeric vector giving the relative proportions of each graph component (title, plots, footer).
title, subtitle: Rescales the size of the space given to the multi-panel title/subtitle. Use if you think the title looks too cramped on the chart. Both default to 1.

dim

An optional named list specifying the plot height and width. Defaults to NULL which means the graph dimensions will be calculated automatically.

format

A string vector of file formats to save as. Accepts "svg", "pdf", "eps", "png", "jpg". For example c("svg", "pdf") will save 2 files with the same name to the same location to SVG and PDF formats. If the file format is specified in filename or by the set_format option, then this argument is ignored.

chart_type

String, or vector of strings if saving multiple plots. Type of chart. This is used to set sensible chart widths based on the type of plot you are saving. Options are:

"normal": default, for normal charts;
"wide": for time series graphs;
"square": for scatter plots;
"custom": for saving a custom aspect ratio specified in the aspect_ratio argument in theme_e61().

auto_scale

Logical. Scale the y-axis automatically. Default is TRUE.

max_height

Numeric. The maximum height of your plot in cm. This is used to constrain the plot resizing algorithm in cases where you want to limit the height of your charts. Defaults to NULL which does not restrict the height.

save_data

Logical. Set to TRUE if you want to save a .csv with the same name as the graph that contains the data needed to recreate the graph (defaults to FALSE).

print_info

Logical. Set to TRUE if you want graph dimensions and other information printed to the console. Defaults to FALSE.

print_label_positions

(single-panel specific) Logical. Set to TRUE to print the final label/x/y of any auto-positioned plot_label() text to the console as copy-pasteable arguments, so you can pin the chosen positions (or hand-tweak just one or two) instead of leaving them to auto-position again next time. Defaults to FALSE.

fast_labels

(single-panel specific) Logical. Set to TRUE to skip the auto-positioning search for any plot_label() without an explicit x/y and use a cheap, render-free approximate position instead (near the label's own series, not collision-checked against other content). Much faster, at the cost of placement quality – intended for quick previews while iterating, not the version you'd actually publish. Explicit x/y positions are unaffected either way. Defaults to FALSE.

spell_check

Logical. Check spelling of words in the title and caption. Defaults to TRUE. Set to FALSE to turn off, or set the theme61.disable_spellcheck option to skip it session-wide (see set_t61_options). Words listed in inst/extdata/custom_dictionary.txt are skipped - add words to that file if they should not be flagged.

preview

Logical. Set to TRUE to show a preview of the graph in the Viewer pane but not save to disk. Defaults to FALSE.

base_size

Numeric. Chart font size. Default is 10.

res

Numeric. For saving to PNG only. Rescale the size of the saved PNG. E.g. res = 2 doubles the size of the saved graph.

bg_colour

Set the graph background colour. Accepts a colour name, hex code or theme61 colour object name. Defaults to "white". For graphs used in research note boxes, set the colour to e61_boxback.

build_up

(single-panel specific) Logical. Save a sequence of files that each reveal one more category/series than the last, with a _1, _2, ..., _N suffix added to filename. See Details. Defaults to FALSE.

build_up_n

(single-panel specific) Numeric. Only used by build_up for a single, ungrouped line or area series, where there's no existing category to step through and the x-axis instead needs to be divided into steps. Defaults to the number of unique x-values, capped at 10.

return_plot_obj

(multi-panel specific) Logical. If TRUE, skips saving entirely and returns the composed multi-panel plot object instead (e.g. to print it in the Plots pane, or use it in a Shiny app). Only supported for multi-panel graphs - for a single plot, just print the ggplot object directly. Defaults to FALSE. Note that the returned object's layout (text sizes, panel spacing) is computed for a fixed target size (dim, or the same defaults save_e61 would otherwise use) - it won't reflow if you resize the device afterwards.

title, subtitle, footnotes, sources

Use labs instead.

ncol, nrow, align, axis

Use layout instead.

pad_width, pad_height, outer_width, outer_height, height_adj, rel_heights, spacing_adj

Use spacing instead.

Value

Invisibly returns the file name.

Details

Use PDF in all notes and SVG in PowerPoint presentations. PDFs and SVGs are better as they are modern vector graphics file formats which can be scaled up and down in size without blurring or becoming pixelated. PNG should only be used when required for compatibility reasons.

build_up = TRUE saves a sequence of files (filename_1, filename_2, ..., filename_N) that each reveal one more category/series than the last, for stepping a chart across several PowerPoint slides. Categories not yet revealed are blanked (zeroed, or set to missing) rather than removed from the data, so the axes, scales and dimensions are identical across every step. Supported chart types:

bar/column charts (geom_col()/geom_bar()): reveals the x-axis categories left to right;
stacked area/ribbon charts (geom_area()/geom_ribbon()): reveals the stacked groups bottom to top;
grouped line/point charts (geom_line()/geom_path()/geom_point()/ geom_pointbar()): reveals one colour/fill group (e.g. one line) at a time;
a single, ungrouped line or area series: reveals progressively along the x-axis instead (see build_up_n).

plot_label() labels are also synced to the reveal sequence, if the label's colour matches the rendered colour of a category/group (the usual way to label a line/bar instead of using a legend) - a label whose colour doesn't match any category (e.g. a source note) is left alone.

build_up is not supported for multi-panel graphs, faceted graphs, preview = TRUE or return_plot_obj = TRUE.