Annotation functions for adding visual elements to forest plots.

Reference Lines

refline

Add a vertical reference line at a specific x-axis position. Commonly used to mark the null effect or clinically meaningful thresholds.

refline(x, label = NULL, style = "dashed", color = NULL,
               width = 1, opacity = 0.6)
Argument Description
x X-axis position for the line
label Optional text label for the line
style Line style: "solid", "dashed", or "dotted"
color Line color (uses theme default if NULL)
width Line width in pixels (default: 1)
opacity Line opacity from 0 to 1 (default: 0.6)

Examples:

# Basic null line
refline(1)

# Labeled threshold with custom styling
refline(0.5, label = "Clinically meaningful",
               style = "solid", width = 2, opacity = 0.8)

Custom Annotations

forest_annotation

Add a custom shape annotation to a specific study.

forest_annotation(
  study_id,
  shape = c("circle", "square", "triangle", "star"),
  position = c("after", "before", "overlay"),
  color = "#8b5cf6",
  size = 1.0
)
Argument Description
study_id Study identifier to annotate
shape Shape type: "circle", "square", "triangle", "star"
position Position relative to point: "before", "after", "overlay"
color Shape color (default: purple)
size Size multiplier (default: 1.0)

Examples

Adding Reference Lines

Code 
data <- data.frame(
  study = c("Study A", "Study B", "Study C"),
  hr = c(0.72, 0.85, 1.15),
  lower = c(0.55, 0.70, 0.90),
  upper = c(0.95, 1.03, 1.45)
)

forest_plot(data,
  point = "hr", lower = "lower", upper = "upper",
  label = "study",
  null_value = 1, scale = "log",
  annotations = list(
    refline(1, "No effect", style = "solid"),
    refline(0.75, "Clinically meaningful", style = "dashed")
  )
)

See Also