gforest: Forest plot

In R4VN: Health Data Analysis and Publication-Ready Reporting

Forest plot

Description

Draws estimates and confidence intervals on a linear or logarithmic scale. It is suitable for odds ratios, risk ratios, prevalence ratios, hazard ratios, and regression coefficients.

Usage

gforest(
  data = NULL,
  estimate,
  lower,
  upper,
  label,
  reference = 1,
  log = TRUE,
  sort = FALSE,
  digits = 2,
  xtitle = NULL,
  title = NULL,
  subtitle = NULL,
  note = NULL,
  color = NULL,
  palette = "journal",
  point_size = 1.1,
  line_width = 2,
  reference_color = "gray50",
  reference_lty = 2,
  reference_lwd = 1,
  theme = "journal",
  size = 11,
  file = NULL,
  width = 7,
  height = 5,
  dpi = 300,
  show = TRUE,
  bg = "white"
)

Arguments

data	A data frame.
estimate	Point estimate variable.
lower, upper	Lower and upper confidence-limit variables.
label	Row-label variable.
reference	Reference value, commonly 1 for ratios and 0 for coefficients.
log	Use a logarithmic horizontal axis.
sort	Sort by estimate: FALSE, TRUE, "ascending", or "descending".
digits	Number of displayed digits.
xtitle	Horizontal-axis title.
title, subtitle, note	Main title, subtitle, and note.
color	Point and interval color.
palette	Color palette used when color = NULL.
point_size	Point-size multiplier.
line_width	Confidence-interval line width.
reference_color, reference_lty, reference_lwd	Color, line type, and width of the vertical reference line.
theme, size, file, width, height, dpi, show, bg	See gbar().

Value

An object of class r4vn_graph; its data component contains plotted rows.

Examples

d <- data.frame(
  term = c("Smoking", "Obesity", "Male"),
  or = c(1.8, 2.4, 1.2),
  lower = c(1.2, 1.5, 0.8),
  upper = c(2.7, 3.8, 1.8)
)
gforest(d, estimate = or, lower = lower, upper = upper, label = term)

# Extended usage examples

# Ratio measures use reference = 1 and a logarithmic axis
d <- data.frame(
  term = c("Smoking", "Obesity", "Male"),
  estimate = c(1.80, 2.40, 1.20),
  lower = c(1.20, 1.50, 0.80),
  upper = c(2.70, 3.80, 1.80)
)
gforest(d, estimate, lower, upper, term, show = FALSE)
gforest(d, estimate, lower, upper, term,
        sort = "descending", title = "Adjusted odds ratios", show = FALSE)

# Regression coefficients use reference = 0 and a linear axis
beta <- data.frame(term = c("Age", "BMI", "Male"),
                   estimate = c(0.12, 0.34, -0.18),
                   lower = c(0.04, 0.10, -0.45),
                   upper = c(0.20, 0.58, 0.09))
gforest(beta, estimate, lower, upper, term,
        reference = 0, log = FALSE, xtitle = "Regression coefficient",
        show = FALSE)

# Export directly to a graphics file
gforest(d, estimate, lower, upper, term,
        file = tempfile(fileext = ".png"), show = FALSE)

R4VN documentation built on Sept. 30, 2026, 5:13 p.m.