plot.cidprop: Plot density of prediction distribution highlighting areas of...

In meta: General Package for Meta-Analysis

Plot density of prediction distribution highlighting areas of clinically important benefit or harm

Description

Plot density of prediction distribution highlighting areas of clinically important benefit or harm

Usage

## S3 method for class 'cidprop'
plot(
  x,
  cid = NULL,
  cid.below.null = x$cid.below.null,
  cid.above.null = x$cid.above.null,
  label.cid = "",
  label.cid.below.null = x$label.cid.below.null,
  label.cid.above.null = x$label.cid.above.null,
  small.values = x$small.values,
  fill.cid.below.null = NULL,
  fill.cid.above.null = NULL,
  fill = "white",
  legend = FALSE,
  studies = TRUE,
  random = TRUE,
  col.diamond = gs("col.diamond"),
  col.diamond.lines = gs("col.diamond.lines"),
  prediction = TRUE,
  col.predict = gs("col.predict"),
  col.predict.lines = gs("col.predict.lines"),
  big.mark = gs("big.mark"),
  digits.cid = gs("digits.cid"),
  digits.percent = 1,
  digits.xaxis = gs("digits.forest"),
  xlab = NULL,
  ylab = NULL,
  xlim = NULL,
  ylim = NULL,
  labels.x = NULL,
  ...
)

Arguments

x	An object of class cidprop.
cid	A numeric value or vector specifying clinically important differences (CID) / decision thresholds used to calculate expected proportions of clinically important benefit or harm (see Details).
cid.below.null	A numeric value or vector specifying CID limits below the null effect (see Details).
cid.above.null	A numeric value or vector specifying CID limits above the null effect (see Details).
label.cid	A character string or vector specifying labels for clinically important differences. Must be of same length as argument cid.
label.cid.below.null	A character string or vector specifying labels for clinically important differences below the null effect. Must be of same length as argument cid.below.null (or cid).
label.cid.above.null	A character string or vector specifying labels for clinically important differences above the null effect. Must be of same length as argument cid.above.null (or cid).
small.values	A character string specifying whether small treatment effects indicate a beneficial ("desirable") or harmful ("undesirable"), can be abbreviated.
fill.cid.below.null	Background colour(s) for CID areas below null effect.
fill.cid.above.null	Background colour(s) for CID areas above null effect.
fill	Background colour for area between decision thresholds.
legend	A logical indicating whether to print a legend with expected proportions of beneficial, harmful, or not important effects.
studies	A logical indicating whether to print estimates of individual studies.
random	A logical indicating whether to show diamond of the random effects meta-analysis.
col.diamond	The colour of the diamond representing the results for the random effects model.
col.diamond.lines	The colour of the outer lines of the diamond representing the results of the random effects model.
prediction	A logical indicating whether to show the prediction interval.
col.predict	The colour of the prediction interval.
col.predict.lines	The colour of the outer lines of the prediction interval.
big.mark	A character used as thousands separator.
digits.cid	Minimal number of significant digits for decision thresholds, see print.default.
digits.percent	Minimal number of significant digits for expected proportions, printed as percentages, see print.default.
digits.xaxis	Minimal number of significant digits for labels on x-axis, see print.default.
xlab	Label on x-axis.
ylab	Label on y-axis.
xlim	Limits for x-axis.
ylim	Limits for y-axis.
labels.x	Predefined labels for tick marks on x-axis.
...	Additional arguments (ignored)

Details

This function plots the density of the prediction distribution highlighting areas of clinically important benefit or harm (Siemens et al., 2025).

Arguments cid, cid.below.null, cid.above.null, label.cid, label.cid.below.null, label.cid.above.null, and small.values are identical to the main arguments of R function cidprop which is called internally if any of these values has been provided by the user.

R packages ggpubr and gridExtra must be installed in order to add a legend to the plot with the CIDs, expected proportions of clinically benefit or harm, and the area colours (due to using R functions ggarrange and tableGrob). The data and colours shown in the legend are stored in the attribute 'data.cid' of the returned ggplot object (see Examples).

UTF-8 code for the less than or equal and greater than or equal signs are used in the legend. Accordingly, graphic devices with full UTF-8 support are required to save graphics, for example, cairo_pdf instead of pdf from R package grDevices.

Value

A ggplot object with additional class 'plot.cidprop'.

Author(s)

Guido Schwarzer [e-mail]

References

Siemens W, Borenstein M, Evrenoglou T, Meerpohl JJ, Schwarzer G (2025): Beyond prediction intervals in meta-analysis: reporting the expected proportion of comparable studies with clinically relevant benefit or harm. BMC Medical Research Methodology, 25, 275

See Also

cidprop

Examples

oldset <- settings.meta(digits.cid = 0)

m <- metagen(1:10 - 3, 1:10, sm = "MD")

pp1 <- cidprop(m, cid = 2)
pp1
plot(pp1, xlim = c(-4, 4))

pp2 <- cidprop(m, cid.below.null = 0.5, cid.above.null = 2)
pp2
plot(pp2, xlim = c(-4, 4))

pp3 <- cidprop(m, cid.below.null = 0.5, cid.above.null = 2,
  small.values = "u")
pp3
plot(pp3, xlim = c(-4, 4))

pp4 <- cidprop(m, cid = 1:2, label.cid = c("moderate", "large"))
pp4
plot(pp4, xlim = c(-4, 4))

pp5 <- cidprop(m, cid.below.null = -1.5, cid.above.null = 1:2,
  label.cid.below.null = "large",
  label.cid.above.null = c("moderate", "large"))
pp5
plpp5 <- plot(pp5, xlim = c(-4, 4))
plpp5
# Information on CIDs and colours
attr(plpp5, "data.cid")

## Not run: 
# R packages 'ggpubr' and 'gridExtra' must be available
if (requireNamespace("ggpubr", quietly = TRUE) &
    requireNamespace("gridExtra", quietly = TRUE)) {
  plot(pp1, xlim = c(-4, 4), legend = TRUE)
}

## End(Not run)

settings.meta(oldset)

meta documentation built on April 2, 2026, 5:07 p.m.