xplot_forest: Default xpose forest plot function

In xpose.xtras: Extra Functionality for the 'xpose' Package

Default xpose forest plot function

Description

Manually generate a forest-style plot (point + interval per category) from an xpdb object. This is a generic, low-level renderer in the same spirit as xplot_boxplot()/xpose::xplot_scatter(): it has no built-in knowledge of covariate associations, prm_cov(), or any other specific data source – it just draws a point + interval (and, per type, a reference guide line) from whatever mapping/pre-fetched opt data it's given. See cov_forest() for the covariate-association-specific wrapper that prepares that mapping from prm_cov() and calls this function to render it.

Usage

xplot_forest(
  xpdb,
  mapping = NULL,
  type = "pi",
  region = NULL,
  orientation = "y",
  xscale = "continuous",
  yscale = "discrete",
  title = NULL,
  subtitle = NULL,
  caption = NULL,
  tag = NULL,
  plot_name = "forest",
  gg_theme,
  xp_theme,
  opt,
  violin_opt,
  quiet,
  ...
)

Arguments

xpdb	<xp_xtras> or <xpose_data> object
mapping	ggplot2 style mapping. Expected aesthetics: x/y (the point) and xmin/xmax (the interval), or the mirrored roles when orientation = "x". For the violin layer (type includes "v"), also needs violin_x/violin_y (prefixed, since this layer's data – from violin_opt – has a different shape than the rest and can't share the plain x/y mapping; see xpose::xp_geoms()'s ⁠{name}_{aes}⁠ convention for per-layer aesthetic overrides).
type	See Details.
region	<numeric(2)> c(low, high) bounds for the shaded "no relevant effect" region (type includes "r"), eg c(0.8, 1.25) for a bioequivalence-style band. NULL (default) falls back to c(0.8, 1.25) whenever "r" is requested; has no effect otherwise.
orientation	Defaults to 'y' (categories on the y-axis, values on the x-axis – the conventional forest-plot layout).
xscale	Defaults to 'continuous'.
yscale	Defaults to 'discrete'.
title	Plot title
subtitle	Plot subtitle
caption	Plot caption
tag	Plot tag
plot_name	Metadata name of plot
gg_theme	As in xpose
xp_theme	As in xpose
opt	Processing options for fetched data (one row per category).
violin_opt	Processing options for the violin layer's data (one row per draw), only used/required when type includes "v". Fetched separately from opt (a distinct xpose::fetch_data() call, noted via cli::cli_inform() unless quiet = TRUE) because the two layers need different data shapes.
quiet	Silence extra debugging output
...	Any additional aesthetics, or overrides for the reference line (eg vline_xintercept = 1 for a ratio-style forest plot; defaults to 0 like the rest of the package's guide lines, see xp_xtra_theme()).

Details

For type-based customization of plots:

• p point (from geom_point) – the effect estimate

• i interval (from geom_linerange) – the confidence/credible interval

• l reference line through the theme's vline_xintercept/ hline_yintercept (0 by default; a ratio-style forest plot will typically override this to 1, see cov_forest())

• v violin/density (from geom_violin), showing the distribution behind an interval (eg simulation draws) – requires violin_opt and a violin_x/violin_y mapping, see above

• r shaded reference region (from geom_rect) spanning region (default c(0.8, 1.25)), eg a bioequivalence-style "no relevant effect" band; drawn behind every other layer

Value

The desired plot

xpose.xtras documentation built on Sept. 1, 2026, 5:08 p.m.