petit_plot: Save a plot to a file and automatically shrink it

In jmablog/tinieR: Shrink Image Filesizes with TinyPNG.com API

Save a plot to a file and automatically shrink it

Description

Save a plot to a file and automatically shrink it with tinify().

Usage

petit_plot(
  filename = "plot",
  path = NULL,
  device = "png",
  ragg = FALSE,
  keep_large = FALSE,
  suffix,
  quiet,
  return_path,
  key = NULL,
  ...
)

petit_ggplot(
  filename = "plot",
  path = NULL,
  plot = ggplot2::last_plot(),
  device = "png",
  keep_large = FALSE,
  suffix,
  quiet,
  return_path,
  key = NULL,
  ...
)

Arguments

filename	String, required. The name to give the output image file. Do not include a file extension.
path	String, optional. If NULL, defaults to the current working directory. The path to save the image file into, relative to the current working directly. Do not include the final trailing path separator.
device	String, optional. Defaults to "png". One of "png" or "jpg", to choose the output image file type. TinyPNG only supports png or jpg image types.
ragg	Boolean, optional. Defaults to FALSE. Whether to use the ragg package as the device backend to generate the image. Will error if ragg is not installed, but does not need to be loaded.
keep_large	Boolean, optional. Defaults to FALSE. Whether to keep the unshrunk original image file alongside the tiny version, or just keep the shrunk file.
suffix	String, optional. If keep_large is TRUE, the suffix to add to the shrunk file. Ignored if keep_large is FALSE.
quiet	Boolean, optional. If set to TRUE, tinify() displays no information messages as it shrinks files.
return_path	String or NULL, optional. One of "proj", "rel", "abs", or "all". If "proj", will return the file path of the newly tinified image file relative to the Rstudio project directory (looking for an .Rproj file). If no project can be identified, returns NA. If "rel", will return the file path of the newly tinified image file, relative to the current working directory at the time tinify() is called. If "abs", will return the absolute file path of the newly tinified image file. If "all", will return a named list with all file paths. If NULL (the default), no file path is returned.
key	String, optional. A string containing your TinyPNG API key. Not required if the API key is set using tinify_api(). Any other key provided as an argument will override the key set by tinify_api().
...	Additional plot options, passed directly to either png()/ragg::agg_png(), jpeg()/ragg::agg_jpeg(), or ggplot2::ggsave() depending on method used.
plot	Object, optional. The plot object to export. Defaults to the last plot modified or created (using ggplot2::last_plot()) if not provided.

Details

These are convenience functions to wrap saving either a base R plot with png() or jpeg() devices, or a ggplot object with ggplot2::ggsave(), before passing the resulting image file directly to tinify(). Can also make use of the ragg package for base plots if installed.

Value

If return_path = "proj", return_path = "rel", or return_path = "abs", a string with the project, relative, or absolute path to the newly tinified image file. If no project can be identified for return_path = "proj", returns NA. If return_path = "all", a named list with all file paths included as $project, $relative, and $absolute respectively. If return_path = NULL, no return value.

Using with base R plots

To save and shrink a base R plot, print the plot and call petit_plot() immediately after. Under the hood, this uses recordPlot() to capture and replay the last plot created within the chosen device with the applied options:

plot(mtcars$mpg, mtcars$drat)

petit_plot(filename = "mtcars")

Using with ggplot

To save and shrink a ggplot, either create, modify, or show the plot and call petit_plot() immediately after, in a similar process to base R plots:

ggplot(data = palmerpenguins::penguins,
       aes(flipper_length_mm, body_mass_g)) +
geom_point(aes(color = species))

petit_plot(filename = "penguins")

Or use petit_ggplot() to capture specifically the last ggplot created or modified:

ggplot(data = palmerpenguins::penguins,
       aes(flipper_length_mm, body_mass_g)) +
geom_point(aes(color = species))

petit_ggplot(filename = "penguins")

Or provide the plot object explicitly to petit_ggplot() with plot:

p <- ggplot(data = palmerpenguins::penguins,
            aes(flipper_length_mm, body_mass_g)) +
     geom_point(aes(color = species))

petit_ggplot(filename = "penguins", plot = p)

See Also

tinify()

tinify_key() to set an API key globally

tinify_defaults() to set default arguments that will be used if not provided explicitly

jmablog/tinieR documentation built on Aug. 22, 2022, 8:55 p.m.