Label, arrange, and save graphics

Save plot objects as .pdf file after labeling with Source graphic and Source code labels.

Usage

mrggsave(x, ...)

# S3 method for class 'ggplot'
mrggsave(
  x,
  ...,
  ypad = 2,
  arrange = FALSE,
  ncol = 1,
  onefile = TRUE,
  envir = parent.frame()
)

# S3 method for class 'ggmatrix'
mrggsave(
  x,
  ...,
  ypad = 4,
  arrange = FALSE,
  onefile = TRUE,
  envir = parent.frame()
)

# S3 method for class 'gList'
mrggsave(...)

# S3 method for class 'gtable'
mrggsave(...)

# S3 method for class 'trellis'
mrggsave(
  x,
  ...,
  ypad = 3,
  arrange = FALSE,
  ncol = 1,
  onefile = TRUE,
  envir = parent.frame()
)

# S3 method for class 'patchwork'
mrggsave(x, ..., envir = parent.frame())

# S3 method for class 'list'
mrggsave(x, ..., arrange = FALSE, use_names = FALSE, envir = parent.frame())

# S3 method for class 'gg'
mrggsave(x, ...)

# S3 method for class 'gTree'
mrggsave(x, ..., envir = parent.frame())

mrgglabel(...)

mrggsave_common(
  x,
  script = getOption("mrg.script", NULL),
  tag = NULL,
  width = 5,
  height = 5,
  stem = "Rplot",
  dir = getOption("mrggsave.dir", "../deliv/figure"),
  path.type = getOption("mrggsave.path.type", "proj"),
  prefix = NULL,
  onefile = TRUE,
  arrange = FALSE,
  .save = TRUE,
  ypad = 3,
  labsep = "\n",
  pre_label = NULL,
  post_label = NULL,
  fontsize = 7,
  textGrob.x = 0.01,
  textGrob.y = unit(0.1, "in"),
  just = c("left", "bottom"),
  dev = getOption("mrggsave.dev", "pdf"),
  res = getOption("mrggsave.res", 150),
  units = "in",
  position = getOption("mrggsave.position", "default"),
  labeller = getOption("mrggsave.label.fun", label.fun),
  envir = parent.frame(sys.nframe()),
  ...
)

Arguments

x: an object or list of objects of class gg.
...: other arguments passed to mrggsave_common and then on to pdf() and gridExtra::arrangeGrob().
ypad: integer number of newlines to separate annotation from x-axis title.
arrange: logical; if TRUE, arrange the ggplot objects on a single page with gridExtra::arrangeGrob().
ncol: passed to gridExtra::arrangeGrob().
onefile: passed to pdf().
envir: environment to be used for string interpolation in stem and tag.
use_names: if TRUE, the names from a list of plots will be used as the stems for output file names.
script: the name of the script generating the gg objects.
tag: if specified, stem is overwritten by pasting script and tag together.
width: passed to pdf(); should be less than 5 in. for portrait figure.
height: passed to pdf(); should be less than 7 in. for portrait figure.
stem: to form the name of the output .pdf file.
dir: output directory for .pdf file.
path.type: a character string indicating how the path to the image file should be rendered in the figure annotation; see format_path() for details.
prefix: gets prepended to the output file path in the Source graphic, label.
.save: logical; if FALSE, return the labeled objects.
labsep: character separator (or newline) for Source code and Source graphic labels.
pre_label: text to include before annotation; separate lines prior to Source code label; see details.
post_label: text to include after annotation; separate lines after Source graphic; see details.
fontsize: for Source graphic and Source code labels.
textGrob.x: passed to grid::textGrob() (as x).
textGrob.y: passed to textGrob (as y).
just: passed to grid::textGrob() (as just).
dev: one or more devices to use; can pass a character vector or a comma-separated string (e.g. c("pdf", "png") or "pdf,png"); passing "CairoPDF" will invoke Cairo-based pdf outputs via Cairo::CairoPDF() (see Details).
res: passed to png().
units: passed to png().
position: force the graphic annotation to locate to the left or right
labeller: a function that creates the plot annotation; the function should receive a single argument (x) which is an environment containing various items that might go into the label; pass NULL to omit the label on the plot.

Details

Methods are provided for ggplot output, lattice output, and ggmatrix objects (produced by GGally::ggpairs()). Either a single plot object or a list of objects can be passed in. If a list of objects are passed in, the plots may be written to a single file (default) or multiple files (if onefile is FALSE). Alternatively, ggplots and lattice plots can be arranged on a single page when arrange is TRUE. ggmatrix objects cannot be arranged. An error is generated if different object types are passed in a single list.

By default, the output file name is generated from the script name and the value in tag. For example, when the script is named vpc-figures and the tag is passed as by-dose-group, the output file name will be vpc-figures-by-dose-group.pdf. Alternatively, the user can specify the complete stem of the file name with the stem argument.

Output file names are generated by default with a hyphen (-) separator. This can be changed using the function output_file_sep(). To revert to previous behavior where the underscore was the separator, call mrggsave:::output_file_sep("_").

When .save is FALSE, mrggsave always returns a list of table grobs. If a single plot was passed, the return value in this case is a list of length 1.

mrgglabel() calls mrggsave() but returns the annotated plots as table grob instead of saving the plot.

pre_label and post_label are collapsed with newline if supplied by the user, allowing multiple lines to be added before or after the standard annotation.

Reproducible pdf output

Starting with R 4.5.0, pdf() accepts arguments timestamp, author and producer. These arguments are set by mrggsave_common() to sensible default values that encourage reproducibility of pdf outputs.

The timestamp argument defaults to FALSE; setting the mrggsave.timestamp option to TRUE lets pdf() generate and set the timestamp in the output file.
The author argument defaults to "mrggsave" and can be overridden through the mrggsave.author global option.
The producer argument defaults to FALSE and cannot be overridden at this time.

Because these arguments are set internally by mrggsave_common(), using pdf.options() will have no effect on the values passed to pdf(); users should use the mrggsave global options instead.

Cairo pdf output

Users can pass dev = "CairoPDF" to invoke Cairo-based pdf outputs via Cairo::CairoPDF(). Any formal argument can be passed through to the device call, but "back-end" arguments (passed through ...) cannot. By default, the author, create.date, and modify.date back-end arguments are set by mrggsave to enable reproducible outputs. These overrides can be tweaked or disabled via global options():

The author argument can be set via mrggsave.author; defaults to "mrggsave".
Both create.date and modify.date are controlled by the mrggsave.timestamp option; when the option is FALSE, both arguments are set to "", resulting in no timestamp getting written into the output; setting the mrggsave.timestamp option to TRUE lets Cairo::CairoPDF() create and set these dates in the pdf output file.

No other back-end arguments to Cairo::CairoPDF() are set by mrggsave and no other back-end arguments can be manipulated by the user.

Examples