% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/recdims.R
\name{recdims}
\alias{recdims}
\title{Recommended Figure Dimensions}
\usage{
recdims(x, units = NULL)
}
\arguments{
\item{x}{A forest plot produced by \code{lmforest()}, \code{glmforest()},
\code{coxforest()}, \code{uniforest()}, \code{multiforest()}, or
\code{autoforest()}.}

\item{units}{Character string giving the units the dimensions are returned
in: \code{"in"} (inches), \code{"cm"}, or \code{"mm"}. Defaults to the
units the plot was created in, so that the dimensions pass through
unconverted unless a change is requested.}
}
\value{
A named numeric vector with elements \code{width} and \code{height},
  expressed in \code{units}. The units are recorded on the result as a
  \code{"units"} attribute, so that a value carried between functions
  remains self-describing.
}
\description{
Returns the figure dimensions recommended for a forest plot, computed from
the plot's own content by the function that produced it.
}
\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. Each plotting function computes a suitable size and attaches it to
the object it returns, and \code{recdims()} reports it.

The values returned are those \code{forestsave()} applies, and are reported
exactly as computed rather than rounded, so that a figure written with
\code{forestsave()} and one written with \code{ggplot2::ggsave()} at these
dimensions are identical. Explicit use is therefore needed only where the
dimensions themselves are wanted, as when sizing a \pkg{knitr} chunk or
arranging several plots on one page.

Where \code{units} differs from the units the plot was created in, the
dimensions are converted. A plot produced before the units were recorded
carries none, and is treated as having been created in inches.
}
\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: Dimensions in the units the plot was created in
recdims(p)

# Example 2: Journals commonly specify figure widths in millimeters
recdims(p, units = "mm")

# Example 3: Sizing an output canvas from the individual elements
dims <- recdims(p)
dims[["width"]]
dims[["height"]]
attr(dims, "units")

}
\seealso{
\code{\link{forestsave}} for saving at these dimensions,
  \code{\link{autoforest}} for producing the plot

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