geom_forestpoint: Forest plot points with precision-weighted squares and summary diamonds

Description

geom_forestpoint() draws the central markers in a forest plot: non-summary rows are rendered as squares whose area is controlled by the ggplot2 size aesthetic (typically proportional to precision), while summary rows are rendered as diamonds whose width reflects the confidence interval and whose height is derived from that width and bounded by row spacing.

Usage

geom_forestpoint(
  mapping = NULL,
  data = NULL,
  stat = "identity",
  position = "identity",
  ...,
  diamond_aspect = 1,
  diamond_row_frac = 0.4,
  diamond_min_frac = 0.06,
  na.rm = FALSE,
  show.legend = NA,
  inherit.aes = TRUE
)

Value

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

Arguments

mapping: Set of aesthetic mappings created by ggplot2::aes().
data: The data to be displayed in this layer. If NULL, the data are inherited from the plot data as specified in the call to ggplot2::ggplot().
stat: Statistical transformation to use. Defaults to "identity".
position: Position adjustment. Defaults to "identity".
...: Additional arguments passed to the underlying GeomForestPoint ggproto object (e.g., color, fill, linewidth).
diamond_aspect: Numeric. Controls how strongly the diamond height increases with confidence interval width. Larger values produce taller diamonds.
diamond_row_frac: Numeric in (0, 1). Maximum fraction of the vertical row spacing that the diamond half-height may occupy, preventing overlap with adjacent rows.
diamond_min_frac: Numeric in (0, 1). Minimum fraction of the row spacing used as the diamond half-height, ensuring visibility for very narrow confidence intervals.
na.rm: Logical. If TRUE, silently removes missing values.
show.legend: Logical or NA. Whether this layer should be included in the legend.
inherit.aes: Logical. If FALSE, the layer does not inherit aesthetic mappings from the parent plot.

Details

This geom is designed to work with standard ggplot2 scales (e.g., scale_size_area()) and pairs naturally with geom_linerange() for confidence intervals and geom_foreststripe() for background striping.

For non-summary rows, the square side length is derived from the ggplot2 size aesthetic (in mm units), so users can control point sizing using standard size scales such as ggplot2::scale_size_area().

For summary rows, the diamond width is determined by the supplied confidence interval (xmin/xmax), and the height is computed as a bounded function of that width. The diamond height does not use the size aesthetic.