plot.r4vn_meta: Plot an R4VN meta-analysis

In R4VN: Health Data Analysis and Publication-Ready Reporting

Plot an R4VN meta-analysis

Description

Draw forest, funnel, trim-and-fill, influence, cumulative, diagnostic, and meta-regression figures. Every figure can be drawn in the R/RStudio Plot pane or saved independently in a publication format.

Usage

## S3 method for class 'r4vn_meta'
plot(
  x,
  type = "forest",
  moderator = NULL,
  contour = FALSE,
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  xlab = NULL,
  ref = NULL,
  xlim = NULL,
  ticks = NULL,
  color = NULL,
  font_family = "sans",
  text_size = 0.82,
  axis_size = 0.9,
  title_size = 1.05,
  title_color = "black",
  subtitle_size = 0.9,
  subtitle_color = "gray30",
  caption_size = 0.75,
  caption_color = "gray40",
  margins = NULL,
  background = "white",
  point_color = NULL,
  point_bg = "white",
  ci_color = NULL,
  summary_color = NULL,
  summary_border = NULL,
  point_shape = NULL,
  point_size = NULL,
  line_type = 1,
  line_width = 1,
  ref_color = "gray40",
  ref_type = 2,
  ref_width = 1,
  show_weights = TRUE,
  show_prediction = FALSE,
  weight_title = "Weight",
  estimate_title = NULL,
  show_abcd = FALSE,
  abcd_titles = c("a", "b", "c", "d"),
  prediction_style = "bar",
  row_shade = "zebra",
  shade_color = "gray95",
  digits = NULL,
  study_order = NULL,
  header = NULL,
  annotate = TRUE,
  yaxis = "sei",
  ylab = NULL,
  contour_levels = c(90, 95, 99),
  contour_colors = c("#FEE2E2", "#FEF3C7", "#E5E7EB"),
  funnel_label = FALSE,
  funnel_legend = FALSE,
  bubble_ci = TRUE,
  bubble_pi = FALSE,
  bubble_shade = c("#DBEAFE", "#E5E7EB"),
  grid = FALSE,
  engine_args = list(),
  file = NULL,
  width = 1800,
  height = 1400,
  res = 180,
  ...
)

Arguments

x	An object created by tabmeta().
type	Plot type: "forest", "funnel", "trimfill", "baujat", "influence", "leaveout", "cumulative", "radial", "labbe", or "bubble".
moderator	Moderator for a bubble/meta-regression plot.
contour	Logical; create a contour-enhanced funnel plot.
title, subtitle, caption	Main title, subtitle, and figure caption.
xlab	Plot x-axis label.
ref	Reference line on the natural effect scale.
xlim, ticks	Optional effect-scale x limits and tick positions. A study estimate or confidence interval outside xlim is indicated by an arrow; its exact, unclipped value remains in the numerical estimate column.
color	Backward-compatible overall plotting color.
font_family, text_size, axis_size, title_size, title_color	Font family, study-label size, axis size, title size, and title color.
subtitle_size, subtitle_color, caption_size, caption_color	Subtitle and caption sizes and colors.
margins	Optional four-value base-graphics margin vector.
background	Figure background color.
point_color, point_bg, ci_color, summary_color, summary_border	Colors for study points, point fill, confidence intervals, pooled diamond, and its border.
point_shape, point_size	Point symbol and optional fixed point size.
line_type, line_width	Confidence-interval line type and width.
ref_color, ref_type, ref_width	Reference-line color, type, and width.
show_weights	Show study weights in a forest plot.
show_prediction	Show the prediction interval in the forest plot. Default FALSE; the prediction interval remains available in the numerical results when requested in tabmeta(). Set TRUE to draw it for a random-effects model.
weight_title, estimate_title	Headings for the separate weight and numerical estimate columns. estimate_title=NULL uses the effect measure and confidence level. Weight is placed to the right of the numerical estimate column.
show_abcd	Show the four original binary cells in separate forest columns. This is available when tabmeta() was called with a, b, c, and d.
abcd_titles	Four headings used when show_abcd=TRUE.
prediction_style	Prediction display: "line", "polygon", "bar", "shade", or "dist".
row_shade, shade_color	Forest-row shading style and color.
digits	Number of displayed decimals.
study_order	Optional forest ordering vector or metafor order keyword.
header	Forest headings; NULL uses R4VN headings.
annotate	Show effect and confidence-interval annotations.
yaxis, ylab	Funnel-plot y-axis definition and label.
contour_levels, contour_colors	Funnel contour levels and colors.
funnel_label	Label funnel points (FALSE, TRUE, "all", "out", or a number of extreme points).
funnel_legend	Funnel legend control, including a position such as "topright".
bubble_ci, bubble_pi, bubble_shade, grid	Meta-regression confidence and prediction bands, their shading colors, and grid display.
engine_args	Named list passed to the underlying metafor plotting method. This provides access to advanced engine-specific controls.
file	Optional output file. Supported extensions are PNG, JPEG, TIFF, PDF, and SVG.
width, height	Device width and height. Raster units are pixels.
res	Raster resolution.
...	Additional named arguments merged into engine_args.

Value

The meta-analysis object invisibly.

Examples

if (requireNamespace("metafor", quietly = TRUE)) {
  dat <- read.csv(system.file("extdata", "meta_example.csv", package = "R4VN"))
  m <- tabmeta(
    dat, study, effect = OR, lower = LCI, upper = UCI, or = TRUE,
    show = FALSE
  )

  # Journal-style forest plot in the Plot pane.
  plot(
    m, type = "forest", font_family = "sans",
    subtitle = "Random-effects model with 95% confidence intervals",
    caption = "Square size reflects study weight; diamond is pooled effect.",
    margins = c(5.5, 4.2, 5.0, 2.0),
    point_color = "#1F4E79", ci_color = "#5B9BD5",
    summary_color = "#C00000", summary_border = "#7F0000",
    row_shade = "zebra", shade_color = "#F5F7FA",
    show_weights = TRUE, weight_title = "Weight",
    estimate_title = "OR (95% CI)", show_prediction = FALSE,
    xlim = c(0.2, 2), ticks = c(0.25, 0.5, 1, 1.5, 2)
  )

  # Contour-enhanced funnel and trim-and-fill plots.
  plot(
    m, type = "funnel", contour = TRUE,
    point_shape = 21, point_color = "#1F4E79", point_bg = "#D9EAF7",
    contour_levels = c(90, 95, 99),
    contour_colors = c("#FFF2CC", "#FCE4D6", "#E2F0D9"),
    funnel_label = "out", funnel_legend = "topright"
  )
  if (!is.null(m$models$trimfill)) {
    plot(m, type = "trimfill", contour = TRUE)
  }

  # Save a 300-dpi TIFF independently.
  forest_file <- tempfile(fileext = ".tiff")
  plot(
    m, type = "forest", file = forest_file,
    width = 2400, height = 1800, res = 300,
    font_family = "sans", point_color = "#1F4E79",
    ci_color = "#5B9BD5", summary_color = "#C00000"
  )
  unlink(forest_file)

  # Advanced metafor controls.
  plot(m, type = "forest",
       engine_args = list(efac = c(1, 1.2), plim = c(0.6, 1.8)))
}

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