% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/forestsave.R
\name{forestsave}
\alias{forestsave}
\title{Save a Forest Plot to File}
\usage{
forestsave(
  plot,
  file,
  width = NULL,
  height = NULL,
  units = NULL,
  dpi = 300,
  device = NULL,
  embed_fonts = FALSE,
  quiet = FALSE,
  ...
)
}
\arguments{
\item{plot}{A forest plot produced by \code{lmforest()}, \code{glmforest()},
\code{coxforest()}, \code{uniforest()}, \code{multiforest()}, or
\code{autoforest()}. Any \pkg{ggplot2} object is accepted, but one that
carries no recommended dimensions requires \code{width} and \code{height}
to be supplied.}

\item{file}{Character string giving the output path. The file extension
determines the format: \code{.pdf}, \code{.png}, \code{.tiff},
\code{.jpeg}, \code{.svg}, \code{.eps}, and the other formats
\code{ggplot2::ggsave()} supports.}

\item{width, height}{Numeric plot dimensions. Taken from the plot's
recommended dimensions when not supplied, and converted where these differ
from \code{units}.}

\item{units}{Character string giving the units for \code{width} and
\code{height}: \code{"in"} (inches), \code{"cm"}, or \code{"mm"}. Defaults
to the units the recommended dimensions were expressed in, and to
\code{"in"} where none were recorded.}

\item{dpi}{Numeric resolution in dots per inch for raster formats. Ignored
for vector formats. Default is \code{300}.}

\item{device}{Graphics device. Selected automatically when \code{NULL}: see
Details. Supply \code{"cairo"} to use the Cairo device for the output
format, which embeds fonts, or any device function or name recognized by
\code{ggplot2::ggsave()}.}

\item{embed_fonts}{Logical. Embed the fonts in a PDF after it is written,
using \code{grDevices::embedFonts()}. Requires Ghostscript, and applies
only to PDF output. Default is \code{FALSE}.}

\item{quiet}{Logical. Suppress the message reporting the dimensions used.
Default is \code{FALSE}.}

\item{...}{Additional arguments passed to \code{ggplot2::ggsave()}, such as
\code{bg} or \code{limitsize}.}
}
\value{
Invisibly returns \code{file}.
}
\description{
Writes a forest plot to file, sized by default from the recommendations the
plotting function computed from the plot's own content, and rendered through
a graphics device chosen to reproduce the fonts seen on screen.
}
\details{
Forest plots are sized by their content rather than by the page: a plot with
more variables, longer labels, or more factor levels requires a larger
canvas, and the plotting functions compute one and attach it to the returned
object as a \code{"rec_dims"} attribute. \code{forestsave()} reads that
attribute, so the following are equivalent:

\preformatted{
dims <- attr(p, "rec_dims")
ggplot2::ggsave("forest.pdf", p, width = dims$width,
                height = dims$height, units = dims$units)

forestsave(p, "forest.pdf")
}

\strong{Device selection.} Fonts are measured differently by different
graphics devices, so a figure written through one device may not reproduce
the spacing seen on screen or in the package documentation. Unless
\code{device} is supplied, \code{forestsave()} selects:

\describe{
  \item{PDF}{R's internal PDF device, \code{grDevices::pdf()}, reached by
    deferring to \code{ggplot2::ggsave()}. Cairo is not used by default:
    although it embeds fonts, its face selection can substitute an
    incorrect italic, which matters here because forest plot footers and
    statistical notation are set in italic. Pass \code{device = "cairo"}
    to use it where font embedding is required.}
  \item{PNG, TIFF, JPEG}{The corresponding \pkg{ragg} device where that
    package is installed, whose text metrics match those used to render the
    package vignettes. Falls back to the standard raster devices
    otherwise.}
  \item{Other formats}{Left to \code{ggplot2::ggsave()}.}
}

\strong{Font embedding.} R's PDF device draws on the standard fonts that every
PDF reader is required to provide, so its output is portable without
embedding. Embedding matters where the plot uses a font outside that set, and
where a publisher requires it. Setting \code{embed_fonts = TRUE} embeds the
fonts after the file is written, through \code{grDevices::embedFonts()}, which
requires a Ghostscript installation. This is offered as an alternative to
\code{device = "cairo"}, which embeds fonts as it draws but selects its own
italic face.

\code{device = "cairo"} is a shorthand of this package's own, resolving to
\code{grDevices::cairo_pdf()}, \code{grDevices::cairo_ps()}, or
\code{grDevices::svg()} according to the output format:
\preformatted{
forestsave(p, "forest.pdf", device = "cairo")
}
It applies to vector formats only, since raster output already uses the
\pkg{ragg} devices, which supersede Cairo's raster backends. Cairo is
absent from some installations even where \code{capabilities("cairo")}
reports otherwise, so the device is opened once before use and its
unavailability reported. Any other value of \code{device} is passed to
\code{ggplot2::ggsave()} unchanged.

The dimensions used are reported through a \code{message()} unless
\code{quiet = TRUE}, so that a figure written at an unexpected size is
apparent at the point it is written.
}
\examples{
data(clintrial)
data(clintrial_labels)

model <- stats::glm(readmission_30d ~ age + sex + stage,
                    data = clintrial, family = stats::binomial)

p <- glmforest(model, data = clintrial, labels = clintrial_labels)

# Example 1: Save at the recommended dimensions
forestsave(p, file.path(tempdir(), "forest.pdf"))

\donttest{

# Example 2: Raster output at publication resolution
forestsave(p, file.path(tempdir(), "forest.png"), dpi = 600)

# Example 3: Dimensions given explicitly, in any supported units
forestsave(p, file.path(tempdir(), "forest_sized.pdf"),
           width = 24, height = 16, units = "cm")

# Example 4: Embed fonts after writing, where Ghostscript is available
forestsave(p, file.path(tempdir(), "forest_embedded.pdf"),
           embed_fonts = TRUE)

}

}
\seealso{
\code{\link{autoforest}}, \code{\link{coxforest}},
  \code{\link{glmforest}}, \code{\link{lmforest}}, \code{\link{uniforest}},
  \code{\link{multiforest}} for producing forest plots;
  \code{\link{tablesave}} for exporting formatted tables

Other visualization functions:
\code{\link[=autoforest]{autoforest()}},
\code{\link[=coxforest]{coxforest()}},
\code{\link[=glmforest]{glmforest()}},
\code{\link[=lmforest]{lmforest()}},
\code{\link[=multiforest]{multiforest()}},
\code{\link[=recdims]{recdims()}},
\code{\link[=uniforest]{uniforest()}}
}
\concept{visualization functions}
