Arrange and save CMAP ggplot chart

Place a ggplot into a frame defined by CMAP design standards. It will align your title and caption to the left, add a horizontal line on top, and make other adjustments. It can show you the final plot and/or export it as a raster or vector file. This function will not apply CMAP design standards to the plot itself: use with theme_cmap() for that. This function uses ragg drivers in R and for raster exports, svg for svg, and cairo_pdf for PDFs.

finalize_plot(
  plot = NULL,
  title = "",
  caption = "",
  width = 670/72,
  height = 400/72,
  sidebar_width = NULL,
  caption_align = 0,
  mode = c("plot"),
  filename = NULL,
  overwrite = FALSE,
  ppi = 300,
  fill_bg = "white",
  fill_canvas = "gray90",
  overrides = list(),
  inherit = c("tc", "t", "c", "none"),
  legend_shift = TRUE,
  debug = FALSE,
  use_cmap_aes = TRUE,
  caption_valign,
  title_width,
  ...
)

Arguments

plot

ggplot object, the variable name of the plot you have created that you want to finalize. If null (the default), the most recent plot will be retrieved via ggplot2::last_plot().

title, caption

Char, the text you want to appear in the title and caption blocks. If empty, any non-Null values from plot will be retrieved. These blocks take html formatting, so manual text breaks can be created with <br> and formatting can be changed with <span>.

width, height

Numeric, the dimensions for the output image, including the title. Units in inches, which interacts with ppi to define the pixel dimensions of raster outputs. Default is 9.31 inches wide (670/72) and 5.56 inches tall (400/72), to match Comms specification for web graphics.

sidebar_width

Numeric, the width in inches for the sidebar. If unspecified, use 25 percent of the total output width (per Comms guidance). If set to 0, the title, if present, is moved above the topline and the caption, if present, is moved to below the plot.

caption_align

Numeric, alignment of the caption text. When the caption is in the title column (when sidebar_width > 0), 0 (the default) aligns text to bottom; 1 aligns top. When the caption is located below the plot, 0 aligns left and 1 aligns right. 0.5 aligns center.

mode

Vector, the action(s) to be taken with the plot. View in R with plot, the default. Save using any of the following: png, tiff, jpeg, svg, pdf, ps. Run multiple simultaneous outputs with a vector, e.g. c("plot", "png", "pdf").

filename

Char, the file path and name you want the plot to be saved to. You may specify an extension to use. If you don't, the correct extension will be added for you.

overwrite

Bool, set to TRUE if you would like the function to overwrite existing files by the same name. The default is FALSE.

ppi

Numeric, the resolution of exported images (pixels per inch). Default = 300.

fill_bg, fill_canvas

Char, strings that represent colors R can interpret. They are used to fill behind and around the finished plot, respectively.

overrides

Named list, overrides the default drawing attributes defined in cmapplot_globals$consts which are drawn by finalize_plot. Units are in bigpts (1/72 of an inch).

inherit

Char, a string of characters that represent which elements of the underlying ggplot object the function should attempt to inherit if not specified in this function. If left as default, the function will attempt to replace blank titles and captions with those from the underlying plot object. Acceptable values are "t" (inherit title only), "c" (inherit caption only), "tc" (the default, inherit both title and caption), and "none" (inherit nothing).

legend_shift

Bool, TRUE, the default, attempts to align the legend all the way left (on top of the y axis labels) per CMAP design standards. FALSE maintains the alignment used in the original plot.

debug

Bool, TRUE enables outlines around components of finalized plot. Defaults to FALSE.

use_cmap_aes

Bool, TRUE, the default, temporarily implements CMAP default aesthetic settings for geoms (see apply_cmap_default_aes) for the present plot.

caption_valign

This is deprecated as of cmapplot 1.1.0 and will be removed in future releases. Replace with caption_align argument.

title_width

This is deprecated as of cmapplot 1.1.1 and will be removed in future releases. Replace with sidebar_width argument.

...

Pass additional arguments to ggplot2's theme function to override any elements of the plot's theme when drawing.

Value

This function invisibly returns the finished graphic as a gTree object. If stored (e.g. g <- finalize_plot(...)), the gTree can be drawn later with grid (e.g. grid::grid.draw(g)).

Examples

if (FALSE) { # \dontrun{
econ_plot <- ggplot(data = cluster_jobchange,
                    mapping = aes(
                      y = reorder(name, jobchange),
                      x = jobchange,
                      fill = category)) +
  geom_col() +
  theme_cmap(gridlines = "v", vline = 0) +
  scale_x_continuous(labels = scales::comma)

finalize_plot(econ_plot,
               "Cluster-level employment changes in the Chicago MSA, 2001-17",
               "Source: Chicago Metropolitan Agency for Planning analysis",
               mode = "plot",
               height = 6,
               width = 8,
               sidebar_width = 2.5,
               overrides = list(margin_plot_r = 30))

transit_plot <- transit_ridership %>%
  mutate(system = case_when(
    system == "cta_bus" ~ "CTA (Bus)",
    system == "cta_rail" ~ "CTA (Rail)",
    system == "metra" ~ "Metra",
    system == "pace" ~ "Pace",
    system == "pace_ada" ~ "Paratransit"
  )) %>%
  ggplot(aes(x = year, y = ridership, color = system)) +
  geom_line() +
  theme_cmap(legend.max.columns = 3)

finalize_plot(transit_plot,
              "Transit ridership in the RTA region over time, 1980-2019
              (in millions)",
              "Source: Chicago Metropolitan Agency for Planning
              analysis of data from the Regional Transportation Authority",
              mode=c("plot", "pdf"),
              filename = "foo")
} # }