% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/forest_reg.R
\name{forest_reg}
\alias{forest_reg}
\title{Draw a forest table from regression outputs}
\usage{
forest_reg(
  df = NULL,
  uni = NULL,
  multi = NULL,
  desc = NULL,
  theme = NULL,
  ci_col_width = 20,
  side = c("right", "left"),
  quiet = TRUE,
  effects = NULL,
  ticks_at = NULL,
  ticks_digits = NULL,
  xlim = NULL,
  style_strata = TRUE,
  strata_fill = "#EAF2F1",
  ...
)
}
\arguments{
\item{df}{Output of \code{forest_df()}. If \code{NULL}, it is built from
\code{uni}, \code{multi}, and \code{desc}.}

\item{uni, multi, desc}{Optional \code{gtregression} objects to pass through to
\code{forest_df()}.}

\item{theme}{Optional \code{forestploter::forest_theme()}. If \code{NULL},
\code{forestploter} defaults are used. You may pass colors and styling
either here or through \code{...}.}

\item{ci_col_width}{Numeric value, or one value per effect column,
controlling the blank spacer width used by \code{forestploter} for the
confidence-interval plot column(s). Values greater than 1 are interpreted
as approximate character counts. Values between 0 and 1 are accepted for
backward compatibility and converted to character counts.}

\item{side}{Character. For each effect, position of the plot relative to the effect-size text:
\code{"left"} = plot first then text; \code{"right"} = text first then plot.
The \code{Characteristic} column and descriptive columns remain on the left.}

\item{quiet}{Logical. Suppress forestploter warnings. Default = `TRUE`.}

\item{effects}{Optional effect labels passed to \code{forestploter::forest()}.}

\item{ticks_at}{Optional numeric vector, or list of numeric vectors for
multiple effect
columns, specifying x-axis tick positions. If \code{NULL},
\code{forestploter::forest()} chooses the default ticks.}

\item{ticks_digits}{Optional number of digits for x-axis tick labels.}

\item{xlim}{Optional numeric vector of length 2, or list of length-2 numeric
vectors for multiple
effect columns, specifying x-axis limits. If \code{NULL},
\code{forestploter::forest()} chooses the default limits.}

\item{style_strata}{Logical. Retained for older vertically grouped
stratified forest data. Current \code{forest_df()} stratified output places
strata side by side, so no stratum header rows are styled.}

\item{strata_fill}{Character. Fill color used for older styled stratum header
rows.}

\item{...}{Passed to \code{forestploter::forest()}. Common options include
\code{title} and \code{footnote}.}
}
\value{
A \code{gtregression_forest} object with elements:
\describe{
  \item{\code{plot}}{The forest plot object.}
  \item{\code{data}}{The plotting data sent to \code{forestploter::forest()}.}
  \item{\code{input_data}}{The original \code{forest_df()} data, including
  standard-error helper columns.}
  \item{\code{meta}}{Model metadata, including reference line and x-axis
  transformation.}
}
}
\description{
Wrapper around \code{forestploter::forest()} that works directly with
\code{forest_df()} output or with \code{gtregression} regression objects.
It can show descriptive columns and one or more model effect columns in a
table-style forest plot while leaving axis and interval drawing to
\pkg{forestploter}.
}
\examples{
birthwt_data <- data_birthwt |>
  transform(
    smoke = factor(smoke, levels = c(0, 1), labels = c("No", "Yes")),
    ht = factor(ht, levels = c(0, 1), labels = c("No", "Yes")),
    low = factor(low, levels = c(0, 1),
                 labels = c("Normal BW", "Low BW"))
  )

uni_or <- uni_reg(
  birthwt_data,
  outcome = "low",
  exposures = c("age", "lwt", "smoke", "ht"),
  approach = "logit"
)
multi_or <- multi_reg(
  birthwt_data,
  outcome = "low",
  exposures = c("smoke", "ht"),
  adjust_for = c("age", "lwt"),
  approach = "logit"
)

forest_reg(uni = uni_or, multi = multi_or)

# If axis labels overlap, set x-axis limits and tick marks.
forest_reg(
  uni = uni_or,
  multi = multi_or,
  xlim = list(c(0.25, 8), c(0.25, 12)),
  ticks_at = list(c(0.5, 1, 2, 4, 8), c(0.5, 1, 2, 4, 8))
)

# If the forest plot panel is too narrow or too wide, tune ci_col_width.
forest_reg(
  uni = uni_or,
  multi = multi_or,
  ci_col_width = c(18, 22)
)
}
