In christyray/crthemes: A Standardized ggplot2 Theme for Visualizations

knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.width = 6,
  fig.asp = 2/3,
  out.width = "75%",
  dev = "ragg_png"
)

library(ggplot2)
library(crthemes)

Updated r format(Sys.time(), "%b %d, %Y") \ \ The default theme_cr() is designed for a 6" by 4" figure with font size of 12 pt. The plot_scale and font_scale arguments of theme_cr() can be used to change the scaling of the plot features and the font for larger or smaller outputs.

Note that none of the code in this vignette is run, and the plots are not displayed. If it were run, the saved plot output would be too large to render within a vignette.

plot_scale

plot_scale changes the size of lines, rectangles, geoms, and font and the spacing of plot features. It has a default value of 1, which corresponds to a 6" by 4" figure. Larger values will increase the size of the plot features multiplicatively, and smaller values will decrease the size of plot features in the same way.

The plot size is set with crsave(), as described below.

# p represents a ggplot object

# Default size
p + theme_cr(plot_scale = 1)

# Larger plot
p + theme_cr(plot_scale = 1.5)

font_scale

font_scale determines how the font should be sized relative to the rest of the plot. With the default value of 1, the font will be scaled according to the plot_scale value. For example, a plot_scale value of 2 and a font_scale value of 1 will give a font size of 24, corresponding to the increased size of the plot from plot_scale.

Changing the font_scale value will make the font larger or smaller compared to the plot features. This can be helpful for making font bigger on a small figure where legibility is more important than the size of the data on the figure.

# Smaller plot with font twice as large as the default for that plot size
p + theme_cr(plot_scale = 0.5, font_scale = 2)

# Normal plot size with smaller font
p + theme_cr(plot_scale = 1, font_scale = 0.75)

crsave()

The plot_scale and font_scale arguments of theme_cr() are designed to be used alongside the crsave() function to finesse the size of plot components and the final rendered image size. crsave() is a wrapper for ggsave() with my preferred graphics devices specified as defaults.

The scaling argument

Saving rendered images at the desired size and resolution is a tricky business in T. This tidyverse blog post goes into more detail about the different approaches to plot scaling and the pros and cons of each approach. It also explains the methodology behind the scaling argument in the ragg graphics devices from the ragg package.

The crsave() function accepts a scaling argument that it then passes to the ragg graphics devices if they are being used (the default behavior). The size of every printed component in the image (e.g., points, lines, text, etc.) is essentially then multiplied by this scaling factor to scale up or down the image.

The scaling argument allows the image to either (1) be resized up or down without changing the relative sizes of the individual plot components, or (2) scale up or down the components of the figure relative to the image size.

To resize the image without changing the relative sizes of the plot components, set the scaling factor to the amount the image should be scaled by, and multiply the width of the image by that same factor. For example, to double the size of a 6" x 4" figure without changing the general appearance of the data, set scaling = 2 and width = 12.

To scale the image components relative to the image size, set the scaling factor to the amount the components should be scaled by without changing the size of the image width. scaling > 1 will increase the size of the figure components, and scaling < 1 will decrease their size.

# Save the plot object in p with the default settings, defaults to PNG
crsave(p)

# Scale up the plot to a 12" by 8" figure
crsave(p, path = "figure.png", width = 12, scaling = 2)

Overall Figure Sizing and Scaling

The most straightforward approach to create figures that are scaled correctly is to first create the figure in R with the plot_scale argument of theme_cr() set to 1. With the initial figure creation, determine if any individual aspects of the plot need to be resized relative to the other plot components, and adjust those aspects with the geom_*(), scale_*(), and theme() functions as needed. If the size of the text overall needs adjustment, use the font_scale argument of theme_cr().

After figure is created and the individual components are sized correctly relative to each other in R, the figure can be exported with the crsave() function. The next step is to determine the width and aspect ratio for the figure that appears best with the size of the figure components. The approach here is to iteratively tweak the width and ratio arguments of crsave() until the desired figure appearance is reached.

If the figure is being used alongside previously generated figures and needs to match the relative size of the components in those images, the plot_scale() argument of theme_cr() can be used to adjust the size of most of the plot components accordingly. This is easiest to use for small adjustments; for any substantial changes in the image scale, use the scaling argument of crsave().

The scaling argument of crsave() is primarily for resizing an existing figure that has already been formatted to the desired appearance. It applies a scaling factor to the entire image, so the scaling argument can be used along with the width argument to quickly upscale a figure from a presentation to be the correct size for a poster or downscale a figure to make a thumbnail for a website.

Image Width and Aspect Ratio

The aspect ratio of the plot is set with the ratio argument, given as the ratio of the figure width to the figure height. The height of the plot is calculated from the width value and the ratio. The units argument determines what units are used for the image height and width and can be given any unit supported by grid::unit().

# Save the plot as a 4" by 4" figure
crsave(p, path = "figure.png", width = 4, ratio = 1)

# Save the plot as a 5 cm by 10 cm figure
crsave(p, path = "figure.png", width = 5, ratio = 0.5, units = "cm")

Other Arguments

crsave() will name the figure file based on the path argument or based on the name of the plot_object if no path is given. It will set the graphics device based on the device argument, or it will use the file extension from path or the type argument to select a default graphics device (recommended).

dpi sets the resolution of the plot in pixels per inch and is passed directly to ggsave. Any other arguments for ggsave or the specific graphics device being used can also be provided to crsave(), and they will be passed through to the relevant function.

# Save p as "figure.png"
crsave(p, path = "figure.png")

# Save p as a TIFF file
crsave(p, path = "figure.tiff")

# Decrease the resolution for display on screens
crsave(p, path = "figure.jpg", dpi = 72)

Font Considerations

For png, jpg, and tiff figures, the font is handled through ragg and systemfonts, and it should work correctly when these packages are installed. See the specifics on the ragg package for more information.

For pdf and eps figures, a cairo-safe font must be used instead of the default theme fonts. This can be accomplished with theme_cr(cairo = TRUE, font = safefont) where safefont is the name of a system font that work with cairographics (which fonts will work is system-dependent).

For svg figures, the font will need to be available on the viewer's computer for it to render properly. There are ways to embed web fonts in the figure itself, but that will have to be handled outside the crsave() function. For more information, see the specifics on the svglite package.

# Use a cairo-safe font for pdf and eps output
p + theme_cr(cairo = TRUE, font = "Helvetica")
crsave(p, path = "figure.pdf")

christyray/crthemes documentation built on April 14, 2023, 11:18 p.m.