% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/add_forest_table.R
\name{add_forest_table}
\alias{add_forest_table}
\title{Add a summary table to a forest plot}
\usage{
add_forest_table(
  plot = NULL,
  position = c("left", "right"),
  columns = NULL,
  term_header = "Term",
  n_header = "N",
  events_header = "Events",
  estimate_label = NULL,
  p_header = "P-value",
  column_labels = NULL,
  digits = NULL,
  estimate_digits = NULL,
  interval_digits = NULL,
  p_digits = NULL,
  estimate_fmt = NULL,
  ci_fmt = NULL,
  text_size = NULL,
  header_text_size = NULL,
  header_fontface = "bold",
  header_family = NULL,
  striped_rows = NULL,
  stripe_fill = NULL,
  stripe_colour = NULL,
  stripe_alpha = NULL,
  grid_lines = FALSE,
  grid_line_colour = "black",
  grid_line_size = 0.3,
  grid_line_linetype = 1
)
}
\arguments{
\item{plot}{A plot created by \code{\link[=ggforestplot]{ggforestplot()}}. Leave as \code{NULL} to use
\code{+ add_forest_table(...)} syntax.}

\item{position}{Whether to place the table on the left or right of the
forest plot.}

\item{columns}{Optional explicit columns to display in the side table, in
the order they should appear. Accepts built-in names such as \code{"term"},
\code{"n"}, \code{"events"}, \code{"estimate"}, \code{"ci"}, and \code{"p"}, arbitrary original
dataframe columns, or numeric positions in the supplied data. \code{"conf.low"}
and \code{"conf.high"} are accepted as aliases for \code{"ci"}.}

\item{term_header}{Header text for the term column.}

\item{n_header}{Header text for the \code{N} column.}

\item{events_header}{Header text for the \code{Events} column.}

\item{estimate_label}{Header label for the estimate column. Defaults to the
model-derived label when available.}

\item{p_header}{Header text for the p-value column.}

\item{column_labels}{Optional named vector used to relabel table column
headers. Names should match values supplied to \code{columns} after column
resolution, such as \code{"term"}, \code{"estimate"}, \code{"ci"}, \code{"p"}, or an arbitrary
original dataframe column.}

\item{digits}{Deprecated. Number of digits used when formatting estimates
and p-values. Defaults to \code{2}. Use \code{estimate_digits}, \code{interval_digits},
and \code{p_digits} for separate control.}

\item{estimate_digits}{Number of digits used for point estimates.}

\item{interval_digits}{Number of digits used for confidence interval bounds.}

\item{p_digits}{Number of digits used for p-values.}

\item{estimate_fmt}{Format string for the estimate column. Use
\code{{estimate}}, \code{{conf.low}}, and \code{{conf.high}} as placeholders. The
shorthand \verb{\{conf.low, conf.high\}} is also supported. Defaults to
\code{"{estimate} ({conf.low}, {conf.high})"}, or \code{"{estimate}"} when
\code{columns} includes \code{"ci"}.}

\item{ci_fmt}{Format string for the confidence interval column when
\code{columns} includes \code{"ci"}. Use \code{{conf.low}} and \code{{conf.high}} as
placeholders. The shorthand \verb{\{conf.low, conf.high\}} is also supported.
Defaults to \code{"({conf.low}, {conf.high})"}.}

\item{text_size}{Text size for table contents. Defaults to \code{3.2}.}

\item{header_text_size}{Header text size for table column labels. Defaults
to \code{11}.}

\item{header_fontface}{Font face used for table column labels. Defaults to
\code{"bold"}.}

\item{header_family}{Optional font family used for table column labels.}

\item{striped_rows}{Whether to draw alternating row stripes behind the
table. Defaults to the stripe setting used in \code{\link[=ggforestplot]{ggforestplot()}}.}

\item{stripe_fill}{Fill colour used for striped rows. Defaults to the
stripe fill used in \code{\link[=ggforestplot]{ggforestplot()}}.}

\item{stripe_colour}{Outline colour for striped rows. Defaults to the
stripe outline used in \code{\link[=ggforestplot]{ggforestplot()}}.}

\item{stripe_alpha}{Transparency for striped rows. Defaults to the stripe
alpha used in \code{\link[=ggforestplot]{ggforestplot()}}.}

\item{grid_lines}{Whether to draw black horizontal grid lines in the table.}

\item{grid_line_colour}{Colour used for the table grid lines.}

\item{grid_line_size}{Line width used for the table grid lines.}

\item{grid_line_linetype}{Line type used for the table grid lines.}
}
\value{
A patchwork-composed plot containing the forest plot and side
table, or a ggplot add-on object when \code{plot = NULL}.
}
\description{
Compose a summary table onto a forest plot.
}
\examples{
coefs <- data.frame(
  term = c("Age", "BMI", "Treatment"),
  estimate = c(0.3, -0.2, 0.4),
  conf.low = c(0.1, -0.4, 0.2),
  conf.high = c(0.5, 0.0, 0.6),
  sample_size = c(120, 115, 98),
  p_value = c(0.012, 0.031, 0.004)
)

p <- ggforestplot(coefs, n = "sample_size", p.value = "p_value")
add_forest_table(
  p,
  position = "left",
  columns = c("term", "n", "estimate", "p"),
  estimate_label = "Beta"
)

ggforestplot(coefs, n = "sample_size", p.value = "p_value") +
  add_forest_table(
    position = "right",
    columns = c("term", "n", "estimate", "p"),
    estimate_label = "Beta"
  )
}
