Export Plot Objects to Image Files

Exports plot objects (ggplot2, base plots, lattice, plotly, etc.) from named lists or multiple lists to individual image files. The function automatically detects various plot objects within the input, creates appropriately named image files, and handles various edge cases including file name length restrictions, duplicate plots, invalid characters, and different plot formats. Each plot object becomes a separate image file in the specified format. The function can accept either a single named list or multiple lists, and will create separate folders or file naming schemes for each list when multiple folder names are provided.

perform_ExportPlots2Image(
  results,
  folder_name = "Plots_Export",
  file_prefix = "Plot",
  image_format = "png",
  width = 15,
  height = 12,
  dpi = 300,
  include_timestamp = TRUE,
  overwrite = TRUE,
  use_plot_titles = TRUE,
  max_plots = 100,
  quality = 95,
  transparent = FALSE
)

Arguments

results

Either a named list containing plot objects, or multiple lists that can be passed as: results = list1, or results = c(list1, list2), or results = list(list1, list2, list3). Supported plot types include ggplot2 objects, base R plots (as recorded plots), lattice plots, plotly objects, and other plot classes.

folder_name

Character string specifying the folder name where the plot files will be saved. The folder will be created if it doesn't exist. Default is "Plots_Export".

file_prefix

Character vector specifying the base prefix(es) for plot filenames. If a single prefix is provided, it will be used for all lists. If multiple prefixes are provided, each list will get its own prefix. Default is "Plot".

image_format

Character string specifying the output image format. Supported formats include "png", "jpg", "jpeg", "pdf", "svg", "tiff", "bmp". Default is "png".

width

Numeric value specifying the width of the output images in inches. Default is 15.

height

Numeric value specifying the height of the output images in inches. Default is 12.

dpi

Numeric value specifying the resolution (dots per inch) for raster formats. Default is 300.

include_timestamp

Logical indicating whether to include a timestamp in the filename(s). Default is TRUE.

overwrite

Logical indicating whether to overwrite existing files. If FALSE and file exists, an error will be thrown. Default is TRUE.

use_plot_titles

Logical indicating whether to use plot titles as filenames when available (sanitized for file system compatibility). Default is TRUE.

max_plots

Integer specifying maximum number of plots to export per execution. Default is 100.

quality

Numeric value between 0 and 100 specifying the quality for JPEG format. Ignored for other formats. Default is 95.

transparent

Logical indicating whether to use transparent background for PNG format. Default is TRUE.

Value

Invisibly returns a character vector of full paths to the created image files.

Details

The function performs the following operations:

• Validates and processes input parameters (single list or multiple lists)

• Processes multiple lists and creates separate naming schemes when multiple prefixes provided

• Detects and filters various types of plot objects (ggplot2, base plots, lattice, plotly, etc.)

• Handles duplicate plots by comparing plot objects and adding unique identifiers

• Sanitizes filenames to comply with file system naming conventions

• Exports plots with specified format, dimensions, and quality settings

• Provides comprehensive error handling and progress reporting

Supported Plot Types:

• ggplot2 objects (class "gg" and "ggplot")

• Base R recorded plots (class "recordedplot")

• Lattice plots (class "trellis")

• Plotly objects (class "plotly")

• Grid graphics (class "grob" and "gTree")

• Custom plot objects with print methods

Duplicate Detection:

• Compares plot objects using content hashing for ggplot2 and lattice

• Uses object structure comparison for other plot types

• Automatically appends numeric suffixes to duplicate plots

• Preserves all plots while ensuring unique filenames

File naming follows the pattern: prefix_plot_name/title_timestamp.format Names are automatically sanitized to remove invalid characters and ensure compatibility across different operating systems.

Dependencies

Requires ggplot2 for ggplot object detection and export. Optional packages include lattice, plotly, grid, and format-specific packages.

See also

ggsave, png, pdf, trellis.device

Author

John Lennon L. Calorio

Examples

if (FALSE) { # \dontrun{
library(ggplot2)

# Create sample plots
plot1 <- ggplot(mtcars, aes(x = mpg, y = hp)) + geom_point() + ggtitle("MPG vs HP")
plot2 <- ggplot(iris, aes(x = Sepal.Length, y = Sepal.Width, color = Species)) +
         geom_point() + ggtitle("Iris Sepal Analysis")
plot3 <- ggplot(mtcars, aes(x = mpg, y = hp)) + geom_point() + ggtitle("MPG vs HP") # Duplicate

list1 <- list(
  scatter_plot = plot1,
  iris_analysis = plot2,
  duplicate_plot = plot3,
  not_a_plot = "This will be ignored"
)

# Method 1: Basic usage
perform_ExportPlots2Image(results = list1)

# Method 2: Custom format and dimensions
perform_ExportPlots2Image(
  results = list1,
  folder_name = "My_Plots",
  file_prefix = "Analysis",
  image_format = "pdf",
  width = 12,
  height = 10,
  dpi = 600
)

# Method 3: Multiple lists with different prefixes
list2 <- list(summary_plot = plot1)
perform_ExportPlots2Image(
  results = c(list1, list2),
  file_prefix = c("Primary", "Secondary"),
  image_format = "png",
  use_plot_titles = TRUE,
  transparent = FALSE
)
} # }