fmt_ggplot.Rd

% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/format_data.R
\name{fmt_ggplot}
\alias{fmt_ggplot}
\title{Format ggplot cells}
\usage{
fmt_ggplot(data, columns, rows = NULL, height = 100,
  aspect_ratio = 1)
}
\arguments{
\item{data}{A table object that is created using the \code{\link[=gt]{gt()}} function.}

\item{columns}{The columns to format. Can either be a series of column names
provided in \code{\link[=vars]{vars()}}, a vector of column indices, or a helper function
focused on selections. The select helper functions are: \code{\link[=starts_with]{starts_with()}},
\code{\link[=ends_with]{ends_with()}}, \code{\link[=contains]{contains()}}, \code{\link[=matches]{matches()}}, \code{\link[=one_of]{one_of()}}, and \code{\link[=everything]{everything()}}.}

\item{rows}{Optional rows to format. Not providing any value results in all
rows in \code{columns} being formatted. Can either be a vector of row captions
provided \code{\link[=c]{c()}}, a vector of row indices, or a helper function focused on
selections. The select helper functions are: \code{\link[=starts_with]{starts_with()}},
\code{\link[=ends_with]{ends_with()}}, \code{\link[=contains]{contains()}}, \code{\link[=matches]{matches()}}, \code{\link[=one_of]{one_of()}}, and \code{\link[=everything]{everything()}}.
We can also use expressions to filter down to the rows we need (e.g.,
\code{[colname_1] > 100 & [colname_2] < 50}).}

\item{height}{The absolute height (px) of the image in the table cell.}

\item{aspect_ratio}{The plot's final aspect ratio. Where the height of the
plot is fixed using the \code{height} argument, the \code{aspect_ratio}
will either compress (\code{aspect_ratio} < \code{1.0}) or expand
(\code{aspect_ratio} > \code{1.0}) the plot horizontally. The default value
of \code{1.0} will neither compress nor expand the plot.}
}
\value{
an object of class \code{gt_tbl}.
}
\description{
It's possible to include \pkg{ggplot2} plots within a list column of the
input table data. The common pattern toward obtaining these plots is through
mutation of a list column containing all the \code{data} required for a plot
(e.g., \code{<data> \%>\% dplyr::group_by(<var>) \%>\% tidyr::nest(.key = plot) \%>\% dplyr::mutate(plot = purrr::map(plot, <ggplot code>))}). While \pkg{gt} will
automatically format columns containing \pkg{ggplot2} plots, using the
\code{fmt_ggplot()} function allows us to specify specific \code{rows} and set options
for the plots' \code{height} and \code{aspect_ratio}.
}
\details{
Targeting of values is done through \code{columns} and additionally by \code{rows} (if
nothing is provided for \code{rows} then entire columns are selected). A number of
helper functions exist to make targeting more effective. Conditional
formatting is possible by providing a conditional expression to the \code{rows}
argument. See the Arguments section for more information on this.
}