Forest plot for a fitted model

Draws a forest for a cams() fit using bayesmeta::forestplot.bayesmeta (single-block) or forestplot::forestplot() with the same conventions (multi-block): observed study estimates, optional grey shrinkage overlays, and Overall / Prediction / Combined summaries. An information fraction column shows each row's share of trial precision.

Thin adapter so forestplot::forestplot(fit, ...) reaches the same implementation as forestplot(). Prefer forestplot() for argument completion in the IDE.

Metafor-idiomatic entry point for a cams() fit. Delegates to forestplot() with the same arguments so CAMS options (type, group, …) share one implementation.

Usage

forestplot(
  x,
  reference = NULL,
  label = NULL,
  modifier = NULL,
  subgroup = NULL,
  trial = NULL,
  n_var = FALSE,
  contrast = "all",
  contrast_sep = "-",
  big_var = 100^2,
  pooled = NULL,
  model_names = "Model 1",
  include_shrinkage = TRUE,
  include_overall = TRUE,
  include_prediction = TRUE,
  include_combined = TRUE,
  ifrac = c("interaction", "overall"),
  xlab = NULL,
  group = "subgroup",
  show_annotations = TRUE,
  annotation_digits = 2,
  favours = NULL,
  show_ci_text = NULL,
  exponentiate = FALSE,
  col_right_heading = NULL,
  stroke = interactmeta_forest_stroke(),
  digits = 2,
  fill = "white",
  study_fill = NULL,
  study_colour = NULL,
  summary_fill = NULL,
  summary_colour = NULL,
  pointsize = interactmeta_forest_pointsize(),
  base_size = interactmeta_forest_base_size(),
  prob = 0.95,
  plot.margin = interactmeta_forestplot_margin(),
  xlim = NULL,
  xticks = NULL,
  grouping = NULL,
  panel.height = NULL,
  estimates_only = FALSE,
  type = c("modifiers", "interaction", "subgroups"),
  which_panel = NULL,
  ...
)

forestplot.interactmeta(x, ...)

forestplot.interactmeta_da(x, ...)

forestplot.interactmeta_ad(x, ...)

forestplot.interactmeta_swada(x, ...)

forestplot.interactmeta_conventional(x, ...)

forest.interactmeta_da(x, ...)

forest.interactmeta_ad(x, ...)

forest.interactmeta_swada(x, ...)

forest.interactmeta_conventional(x, ...)

forest.interactmeta(x, ...)

Arguments

x

A CAMS fit from cams().

reference, label, modifier, subgroup, trial, contrast, big_var, pooled

Ignored for CAMS fits; retained for back-compatibility.

n_var

Column name for per-study patient counts shown in an N column. Default FALSE (omit). Set to "n" or another column name to show sizes. When "n" is missing but treat.total and cont.total are present (2-by-2 event-count data), study size is taken as their sum.

contrast_sep

Separator between subgroup labels on interaction rows (default "-").

model_names

Optional character vector selecting marginal layers among "Shrinkage", "Overall", and "Prediction" (intersected with the include_* flags). Prefer include_shrinkage / include_overall / include_prediction for new code. When NULL or the default "Model 1", layers follow those flags alone.

include_shrinkage, include_overall, include_prediction, include_combined

Include shrinkage, overall-effect, prediction, and combined-population rows. All four layers default to TRUE. Grey shrinkage intervals appear alongside quoted estimates (bayesmeta style) in the active type block. Shrinkage is included by default for Bayesian fits only; frequentist (REML / ML) forests omit shrinkage rows. Set include_shrinkage = FALSE to omit them on Bayesian fits. For type = "modifiers", include_combined controls a trailing All section (Overall / Prediction for combined() at the reporting IF), not the subgroup panels. Switching off overall or prediction keeps blank placeholder rows so the figure height and spacing stay close to the full plot.

ifrac

How the overall information fraction ω is pooled via ifrac() for annotations and for Overall / Prediction / Combined diamonds: "interaction" (default; τ_γ and subgroup sampling variances) or "overall" (τ and design SEs). Shrinkage greys are the trial-specific CAMS reconstructions from shrinkage() (shrunken \(m_j,g_j\) inverted at each trial's own \(\pi_j\)); they are not population fitted values. Observed trial rows remain at each trial's own π_j.

xlab

Character; x-axis title. Default is "Effect (log scale)" when exponentiate = FALSE, or "Effect" when exponentiate = TRUE (ratio-scale ticks via xlog = TRUE).

group

How to nest trial rows. "subgroup" (default) groups by subgroup level with trial names as row labels; "trial" groups by trial with subgroup names as row labels.

show_annotations

If TRUE (default), annotate under the x-axis with overall information-fraction quantiles and heterogeneity credibility intervals.

annotation_digits

Decimal places in annotation text (default 2).

favours

Optional length-2 character labels placed under the x-axis (left / right of the null). Default is c("Control", "Experimental") for type = "modifiers". For type = "interaction", the default names the reference and non-reference subgroups (same left/right roles), and the IF column header is IF (non-reference subgroup). Set to FALSE to suppress favours.

show_ci_text

Logical; show estimate and CI text. Default TRUE.

exponentiate

Logical; if TRUE, show estimates on the ratio scale.

col_right_heading

Column heading for the effect column.

study_fill, study_colour

Optional overrides for study-row colours.

base_size, pointsize, digits, stroke, fill, summary_fill, summary_colour, which_panel

Plotting options passed through to the bayesmeta / forestplot renderer.

prob

Coverage probability for confidence intervals (default 0.95).

plot.margin, panel.height

Unused (kept for compatibility).

xlim, xticks

Optional axis limits and tick positions on the displayed effect scale. When both are NULL (default) and exponentiate = FALSE, limits follow bayesmeta::forestplot.bayesmeta / forestplot::forestplot defaults (clip = c(-Inf, Inf), automatic ticks). When exponentiate = TRUE, a strictly positive clip and power-of-two ticks are chosen automatically (forestplot's log axis cannot include 0). When xlim is supplied, values are rounded outward onto a nice grid (and xticks are filled if omitted).

grouping

Optional vector of subheadings for row labels.

estimates_only

If TRUE, drop observed trial rows (keep shrinkage / summary diamonds) and omit the IF and study-size columns.

type

Which forest block(s) to draw. One of:

"modifiers" (default): one section per modifier level (reference and non-reference), each with Overall and Prediction when enabled; optional trailing All summaries when include_combined = TRUE
"interaction": Interaction block only (Overall + Prediction)

Other features (favours, annotations, include_shrinkage, …) apply within the selected type.

...

Passed to forestplot() (CAMS options and/or forestplot presentation args).

Value

For a CAMS or construction fit, a interactmeta_forestplot object with attributes "panels", "panel.height" (when set), and "base_size". Drawing is deferred to print.interactmeta_forestplot() / forestplot_draw() (so fp <- forestplot(fit) does not draw; a top-level forestplot(fit) does). Otherwise whatever forestplot::forestplot() returns.

A interactmeta_forestplot object (see forestplot()).

Details

For non-interactmeta input (e.g. metafor::escalc), arguments are forwarded to forestplot::forestplot(), which dispatches to bayesmeta::forestplot.escalc when bayesmeta is loaded (interactmeta loads it on attach).

By default (type = "modifiers") the plot shows modifier-level panels (each with Overall and Prediction), with overall-IF notes under the x-axis. Use type = "interaction" for the interaction block only. type = "subgroups" is deprecated (same as "modifiers").

Aesthetics vs content

Marker colours, blue summary diamonds / prediction bars, headers, favours, IF column headings, and default typography (base_size / pointsize) are fixed CAMS chrome (same for every type). Only which blocks appear changes with type. Pass typography_auto = TRUE in ... to re-fit fonts to the device and row count. Axis scaling and other forestplot::forestplot() knobs default to bayesmeta-compatible behaviour unless you override them (xlim, xticks, or ...).

bayesmeta::forestplot.escalc — study-only forest from escalc()
bayesmeta::forestplot.bayesmeta — fitted bayesmeta object
metafor::forest on a CAMS fit — forest.interactmeta delegates here
forestplot::forestplot — underlying S3 generic (forestplot::forestplot(fit) still dispatches to the CAMS method)

Examples

if (FALSE) { # \dontrun{
e <- escalc(measure = "IRR", yi = edss$yi, vi = edss$vi, data = edss)
forestplot(e)                          # → forestplot.escalc
fit <- cams(e, reference = "Lower")
forestplot(fit, exponentiate = TRUE, type = "modifiers")
forest(fit, exponentiate = TRUE)       # same via metafor::forest
} # }
if (FALSE) { # \dontrun{
fit <- cams(escalc(measure = "IRR", yi = edss$yi, vi = edss$vi, data = edss),
            reference = "Lower")
forest(fit, exponentiate = TRUE)
} # }