Label, arrange, and save graphics

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

mrggsave(x, ...)

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

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

# S3 method for gList
mrggsave(...)

# S3 method for gtable
mrggsave(...)

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

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

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

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

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

mrgglabel(..., draw = FALSE, .save = FALSE)

mrggsave_common(
  x,
  script = getOption("mrg.script", NULL),
  tag = NULL,
  width = 5,
  height = 5,
  stem = "Rplot",
  dir = getOption("mrggsave.dir", "../deliv/figure"),
  prefix = NULL,
  onefile = TRUE,
  arrange = FALSE,
  draw = 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 = 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
draw	if `TRUE`, the plot is drawn using `draw_newpage()`
.save	logical; if `FALSE`, return the labeled objects
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
prefix	gets prepended to the output file path in the Source graphic, label
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"`)
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() and neither draws nor saves the plot, but returns the annotated plots as table grob.

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.

Examples

data(Theoph)
require(ggplot2)
#> Loading required package: ggplot2

x <- runif(1000,10,100)
y <- 0.3*x + rnorm(length(x),0,20)
data <- data.frame(x = x, y = y)

Script <- "example.R"

# NOTE: see default value for dir argument, which should be appropriate
# for project work

# Changing it here only for the example
options(mrggsave.dir = tempdir())


p1 <- ggplot(data=Theoph) +
  geom_line(aes(x=Time, y=conc, group=Subject))

p2 <- ggplot(data=Theoph) +
  geom_line(aes(x=Time, y=conc)) +
  facet_wrap(~Subject)

mrggsave(p1, Script, "_plot1")

if (FALSE) {
mrggsave(p2, Script, "_plot2")
}

mrggsave(list(p1,p2), Script, "both_plots")

if (FALSE) {
mrggsave(list(p1,p2), Script, "separate_files", onefile=FALSE)
}

mrggsave(p1, Script, "different_shape", width=10, height=4)

if (FALSE) {
mrggsave(list(p1,p2), Script, "onepage", arrange=TRUE, ncol=2)

stopifnot(require(GGally))

p3 <- ggpairs(data)

mrggsave(p3, Script, "ggally_plot")
}

Arguments

Details

See also

Examples