% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ggforestplot.R
\name{ggforestplot}
\alias{ggforestplot}
\title{Draw a ggplot2 forest plot}
\usage{
ggforestplot(
  data,
  term = "term",
  estimate = "estimate",
  conf.low = "conf.low",
  conf.high = "conf.high",
  label = term,
  term_labels = NULL,
  group = NULL,
  facet = NULL,
  facet_strip_position = c("left", "right"),
  grouping = NULL,
  grouping_strip_position = NULL,
  separate_groups = NULL,
  n = NULL,
  events = NULL,
  p.value = NULL,
  exponentiate = NULL,
  sort_terms = c("none", "descending", "ascending"),
  point_size = 2.3,
  point_shape = 19,
  linewidth = 0.5,
  line_size = NULL,
  staple_width = 0.2,
  ci_limits = NULL,
  ci_arrows = TRUE,
  ci_arrow_length = 0.08,
  ci_arrow_type = c("closed", "open"),
  dodge_width = 0.6,
  separate_lines = FALSE,
  separator_line_linetype = 2,
  separator_line_colour = "black",
  separator_line_size = 0.4,
  striped_rows = FALSE,
  stripe_fill = "grey95",
  stripe_colour = NA,
  stripe_alpha = 1,
  ref_line = NULL,
  ref_label = NULL,
  ref_linetype = 2,
  ref_color = "grey60"
)
}
\arguments{
\item{data}{Either a tidy coefficient data frame or a model object
supported by \code{\link[broom:tidy]{broom::tidy()}}.}

\item{term}{Column name holding the model term identifiers.}

\item{estimate}{Column name holding the point estimates.}

\item{conf.low}{Column name holding the lower confidence bounds.}

\item{conf.high}{Column name holding the upper confidence bounds.}

\item{label}{Optional column name used for the displayed row labels.}

\item{term_labels}{Optional named vector used to relabel displayed terms.
Names should match values in the term column and values are the labels to
display.}

\item{group}{Optional column name used for color-grouping estimates.}

\item{facet}{Optional column name used to split rows into faceted plot
sections. If this column is a factor, its levels control facet order.}

\item{facet_strip_position}{Positioning for facet strip labels.}

\item{grouping}{Deprecated. Use \code{facet} instead.}

\item{grouping_strip_position}{Deprecated. Use \code{facet_strip_position}
instead.}

\item{separate_groups}{Optional column name used to identify labeled
variable blocks that can be outlined with grid lines.}

\item{n}{Optional column name holding sample sizes or other N labels for
table helpers.}

\item{events}{Optional column name holding event counts or event labels for
table helpers.}

\item{p.value}{Optional column name holding p-values.}

\item{exponentiate}{Logical; if \code{TRUE}, transform the estimates and draw the
axis on the log scale with the reference line at 1. For model objects,
\code{NULL} uses the canonical scale when it can be inferred, such as hazard
ratios for Cox models.}

\item{sort_terms}{How to sort rows: \code{"none"}, \code{"descending"}, or
\code{"ascending"}.}

\item{point_size}{Point size for coefficient markers.}

\item{point_shape}{Shape used for coefficient markers.}

\item{linewidth}{Line width for confidence intervals.}

\item{line_size}{Deprecated. Use \code{linewidth} instead.}

\item{staple_width}{Width of the terminal staples on confidence interval
lines.}

\item{ci_limits}{Optional numeric vector of length 2 used to truncate
displayed confidence intervals. Intervals extending beyond these limits
are clipped to the boundary and marked with arrows when \code{ci_arrows} is
\code{TRUE}.}

\item{ci_arrows}{Logical; if \code{TRUE}, draw outward-facing arrows for
confidence intervals truncated by \code{ci_limits}.}

\item{ci_arrow_length}{Length of CI truncation arrows in inches.}

\item{ci_arrow_type}{Arrowhead type for truncated confidence intervals.
Passed to \code{\link[grid:arrow]{grid::arrow()}}.}

\item{dodge_width}{Horizontal dodging used for grouped estimates.}

\item{separate_lines}{Logical; if \code{TRUE}, draw grid lines
around each labeled block identified by \code{separate_groups}.}

\item{separator_line_linetype}{Line type used for separator lines.}

\item{separator_line_colour}{Colour used for separator lines.}

\item{separator_line_size}{Line width used for separator lines.}

\item{striped_rows}{Logical; if \code{TRUE}, shade alternating rows.}

\item{stripe_fill}{Fill color used for shaded rows.}

\item{stripe_colour}{Border color for shaded rows.}

\item{stripe_alpha}{Transparency for shaded rows.}

\item{ref_line}{Numeric x-value where the reference line is drawn, or
\code{NULL} to hide it. When omitted, defaults to \code{0} for additive effects and
\code{1} for exponentiated effects.}

\item{ref_label}{Optional label drawn alongside the reference line.}

\item{ref_linetype}{Line type for the reference line.}

\item{ref_color}{Color for the reference line.}
}
\value{
A \code{ggplot} object. Use standard \code{ggplot2} functions such as
\code{\link[ggplot2:labs]{ggplot2::labs()}} for plot labels, and add composition helpers after
styling the main plot.
}
\description{
Builds a forest plot from standardized coefficient data or directly from a
fitted model.
}
\examples{
coefs <- data.frame(
  term = c("Age", "BMI", "Treatment"),
  estimate = c(0.10, -0.08, 0.34),
  conf.low = c(0.02, -0.16, 0.12),
  conf.high = c(0.18, 0.00, 0.56)
)

ggforestplot(coefs)

ggforestplot(coefs, striped_rows = TRUE, point_shape = 17)
}
