geom_foresttable: Render a forest-plot table panel as a ggplot2 layer

In VizTest: Optimal Confidence Intervals for Visual Testing

Render a forest-plot table panel as a ggplot2 layer

Description

geom_foresttable() builds a “table” panel for forest plots by expanding the input data to long form (one row per forest row × table column) and drawing formatted cell text at fixed x positions. Column headers are typically added with scale_x_foresttable() (top axis tick labels), which makes the table align cleanly with a forest plot when composing with patchwork.

Usage

geom_foresttable(
  mapping = NULL,
  data = NULL,
  position = "identity",
  ...,
  cols,
  fmt = NULL,
  fmt_default = as.character,
  col_gap = 1,
  col_align = "left",
  col_nudge = 0,
  na.rm = FALSE,
  show.legend = FALSE,
  inherit.aes = TRUE
)

Arguments

mapping	Set of aesthetic mappings created by ggplot2::aes(). If not supplied, the layer will map x, label, and hjust internally so users generally only need to map y.
data	The data to be displayed in this layer. If NULL, the layer inherits the plot data. If a data frame is provided, it is expanded to long form immediately. If a function is provided, it is used as-is (advanced).
position	Position adjustment. Defaults to "identity".
...	Additional arguments passed to the underlying text geom (GeomForestTableText, which inherits from ggplot2::GeomText), such as colour, family, or fontface.
cols	Character vector of column names to print in the table. Must be non-empty.
fmt	Optional named list of formatting functions. Each function should take a single value and return a length-1 character (or coercible) result. Names should correspond to entries of cols.
fmt_default	Default formatting function used for columns not present in fmt. Defaults to base::as.character().
col_gap	Numeric. Spacing between adjacent table columns on the x axis.
col_align	Character vector of alignments for each column in cols. Each entry must be one of "left", "center", or "right". Length 1 is recycled to length(cols).
col_nudge	Numeric vector of per-column horizontal nudges (in x-axis units) applied to the column positions. Length 1 is recycled to length(cols).
na.rm	Logical. If TRUE, silently removes missing values.
show.legend	Logical. Whether this layer should be included in legends. Defaults to FALSE.
inherit.aes	Logical. If FALSE, the layer does not inherit aesthetic mappings from the parent plot.

Details

The cols argument controls which columns are printed. Formatting can be customized via fmt, a named list of functions (one per column) that convert cell values to character strings.

geom_foresttable() uses ggplot2's feature where the data argument may be a function: when data = NULL, this layer supplies a data function that receives the plot data and expands it to long form while preserving all original columns (including faceting variables and the y mapping). This makes the geom compatible with faceting and grouping while keeping the user-facing API simple.

Column positions are computed as seq_along(cols) * col_gap + col_nudge. Horizontal justification is determined by col_align (left/center/right).

Value

A ggplot2 layer object that can be added to a plot.

See Also

scale_x_foresttable(), gg_forest()

Examples

# geom_foresttable() is designed to be used as part of gg_forest().
# See ?gg_forest for a complete runnable example.

VizTest documentation built on Aug. 28, 2026, 9:06 a.m.