Draw a ggplot2 forest plot — ggforestplot • ggforestplotR

Builds a forest plot from standardized coefficient data or directly from a fitted model.

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"),
  separate_groups = NULL,
  n = NULL,
  events = NULL,
  p.value = NULL,
  exponentiate = NULL,
  conf.level = 0.95,
  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",
  subgroup = NULL,
  p_method = c("overall", "level")
)

Arguments

data: Either a tidy coefficient data frame or a model object supported by broom::tidy().
term: Column name holding the model term identifiers.
estimate: Column name holding the point estimates.
conf.low: Column name holding the lower confidence bounds.
conf.high: Column name holding the upper confidence bounds.
label: Optional column name used for the displayed row labels.
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.
group: Optional column name used for color-grouping estimates. If this column is a factor, its levels control the group legend and vertical dodge order.
facet: Optional column name used to split rows into faceted plot sections. If this column is a factor, its levels control facet order.
facet_strip_position: Positioning for facet strip labels.
separate_groups: Optional column name used to identify labeled variable blocks that can be outlined with grid lines.
n: Optional column name holding sample sizes or other N labels for table helpers.
events: Optional column name holding event counts or event labels for table helpers.
p.value: Optional column name holding p-values.
exponentiate: Logical; if TRUE, transform the estimates and draw the axis on the log scale with the reference line at 1. For model objects, NULL uses the canonical scale when it can be inferred, such as hazard ratios for Cox models.
conf.level: Confidence level represented by model or data-frame interval columns. Defaults to 0.95.
sort_terms: How to sort rows: "none", "descending", or "ascending". Subgroup hierarchies require "none" so their source order is preserved.
point_size: Point size for coefficient markers.
point_shape: Shape used for coefficient markers.
linewidth: Line width for confidence intervals.
line_size: Deprecated. Use linewidth instead.
staple_width: Width of the terminal staples on confidence interval lines.
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 ci_arrows is TRUE.
ci_arrows: Logical; if TRUE, draw outward-facing arrows for confidence intervals truncated by ci_limits.
ci_arrow_length: Length of CI truncation arrows in inches.
ci_arrow_type: Arrowhead type for truncated confidence intervals. Passed to grid::arrow().
dodge_width: Horizontal dodging used for grouped estimates.
separate_lines: Logical; if TRUE, draw grid lines around each labeled block identified by separate_groups.
separator_line_linetype: Line type used for separator lines.
separator_line_colour: Colour used for separator lines.
separator_line_size: Line width used for separator lines.
striped_rows: Logical; if TRUE, shade alternating rows.
stripe_fill: Fill color used for shaded rows.
stripe_colour: Border color for shaded rows.
stripe_alpha: Transparency for shaded rows.
ref_line: Numeric x-value where the reference line is drawn, or NULL to hide it. When omitted, the value is taken from the forest_data metadata, such as 0 for additive effects and 1 for ratios.
ref_label: Optional label drawn alongside the reference line.
ref_linetype: Line type for the reference line.
ref_color: Color for the reference line.
subgroup: Optional column name defining hierarchical subgroup blocks. Missing or empty values identify ordinary standalone estimates. Each non-empty subgroup must form one contiguous block within a facet. This is a presentation-only mapping; subgroups and contrasts are not inferred. With the default p_method = "overall" forest-data metadata, the first nonmissing p-value for each subgroup and estimate group, when applicable, is displayed on its parent row and child p-value cells are suppressed. p_method = "level" retains p-values on child rows. For fitted models, first call tidy_forest_model() with subgroup, focal, and the desired p_method; direct model calls do not perform post-estimation subgroup inference inside the plotting layer.
p_method: Subgroup p-value placement for data-frame input. "overall" displays one p-value on each subgroup header; "level" displays p-values on the subgroup estimate rows. Fitted-model subgroup data inherit this choice from tidy_forest_model().

Value

A ggplot object. Use standard ggplot2 functions such as ggplot2::labs() for plot labels, and add composition helpers after styling the main plot.

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)