meta: drapery – R documentation

Pricing

Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!

Get Started for Free

Documentation

drapery

Drapery plot

Description

Draw a drapery plot with (scaled) p-value curves for individual studies and meta-analysis estimates.

Usage

drapery(
  x,
  type = "zvalue",
  layout = "grayscale",
  study.results = TRUE,
  lty.study = 1,
  lwd.study = 1,
  col.study = "darkgray",
  labels,
  col.labels = "black",
  cex.labels = 0.7,
  subset.labels,
  srt.labels,
  comb.fixed = x$comb.fixed,
  comb.random = x$comb.random,
  lty.fixed = 1,
  lwd.fixed = max(3, lwd.study),
  col.fixed = "blue",
  lty.random = 1,
  lwd.random = lwd.fixed,
  col.random = "red",
  sign = NULL,
  lty.sign = 1,
  lwd.sign = 1,
  col.sign = "black",
  prediction = comb.random,
  col.predict = "lightblue",
  alpha = if (type == "zvalue") c(0.001, 0.01, 0.05, 0.1) else c(0.01, 0.05, 0.1),
  lty.alpha = 2,
  lwd.alpha = 1,
  col.alpha = "black",
  cex.alpha = 0.7,
  col.null.effect = "black",
  legend = TRUE,
  pos.legend = "topleft",
  bg = "white",
  bty = "o",
  backtransf = x$backtransf,
  xlab,
  ylab,
  xlim,
  ylim,
  lwd.max = 2.5,
  lwd.study.weight = if (comb.random) "random" else "fixed",
  at = NULL,
  n.grid = if (type == "zvalue") 10000 else 1000,
  mar = c(5.1, 4.1, 4.1, 4.1),
  plot = TRUE,
  ...
)

Arguments

`x`	An object of class `meta`.
`type`	A character string indicating whether to plot test statistics (`"zvalue"`) or p-values (`"pvalue"`), can be abbreviated.
`layout`	A character string for the line layout of individual studies: `"grayscale"`, `"equal"`, or `"linewidth"` (see Details), can be abbreviated.
`study.results`	A logical indicating whether results for individual studies should be shown in the figure.
`lty.study`	Line type for individual studies.
`lwd.study`	Line width for individual studies.
`col.study`	Colour of lines for individual studies.
`labels`	A logical or character string indicating whether study labels should be shown at the top of the drapery plot; either `FALSE`, `"id"`, or `"studlab"`; see Details.
`col.labels`	Colour of study labels.
`cex.labels`	The magnification for study labels.
`subset.labels`	A vector specifying which study labels should be shown in the drapery plot.
`srt.labels`	A numerical vector or single numeric (between 0 and 90) specifying the angle to rotate study labels; see Details.
`comb.fixed`	A logical indicating whether to show result for the fixed effect model.
`comb.random`	A logical indicating whether to show result for the random effects model.
`lty.fixed`	Line type for fixed effect meta-analysis.
`lwd.fixed`	Line width for fixed effect meta-analysis.
`col.fixed`	Colour of lines for fixed effect meta-analysis.
`lty.random`	Line type for random effects meta-analysis.
`lwd.random`	Line width for random effects meta-analysis.
`col.random`	Colour of lines for random effects meta-analysis.
`sign`	Significance level used to highlight significant values in curves.
`lty.sign`	Line type for significant values.
`lwd.sign`	Line width for significant values.
`col.sign`	Line colour for significant values.
`prediction`	A logical indicating whether to show prediction region.
`col.predict`	Colour of prediction region
`alpha`	Horizonal lines are printed for the specified alpha values.
`lty.alpha`	Line type of horizonal lines for alpha values.
`lwd.alpha`	Line width of horizonal lines for alpha values.
`col.alpha`	Colour of horizonal lines for alpha values.
`cex.alpha`	The magnification for the text of the alpha
`col.null.effect`	Colour of vertical line indicating null effect.
`legend`	A logical indicating whether a legend should be printed.
`pos.legend`	A character string with position of legend (see `legend`).
`bg`	Background colour of legend (see `legend`).
`bty`	Type of the box around the legend; either `"o"` or `"n"` (see `legend`).
`backtransf`	A logical indicating whether results should be back transformed on the x-axis. For example, if `backtransf = FALSE`, log odds ratios instead of odds ratios are shown on the x-axis.
`xlab`	A label for the x-axis.
`ylab`	A label for the y-axis.
`xlim`	The x limits (min, max) of the plot.
`ylim`	The y limits (min, max) of the plot (ignored if `type = "pvalue"`).
`lwd.max`	The maximum line width (only considered if argument `layout` is equal to `"linewidth"`).
`lwd.study.weight`	A character string indicating whether to determine line width for individual studies using weights from fixed effect (`"fixed"`) or random effects model (`"random"`), can be abbreviated (only considered if argument `layout` is equal to `"linewidth"`).
`at`	Points at which tick-marks are to be drawn on the x-axis.
`n.grid`	The number of grid points to calculate the p-value or test statistic functions.
`mar`	Physical plot margin, see `par`.
`plot`	A logical indicating whether to generate a figure.
`...`	Graphical arguments as in `par` may also be passed as arguments.

Details

The concept of a p-value function, also called confidence curve, goes back to Birnbaum (1961). A drapery plot, showing p-value functions (or a scaled version based on the corresponding test statistics) for individual studies as well as meta-analysis estimates, is drawn in the active graphics window. Furthermore, a prediction region for a single future study is shown as a shaded area. In contrast to a forest plot, a drapery plot does not provide information for a single confidence level however for any confidence level.

Argument type can be used to either show p-value functions (Birnbaum, 1961) or a scaled version (Infanger, 2019) with test statistics (default).

Argument layout determines how curves for individual studies are presented:

darker gray tones with increasing precision (layout = "grayscale")
thicker lines with increasing precision (layout = "linewidth")
equal lines (layout = "equal")

Argument labels determines how curves of individual studies are labelled:

number of the study in the (unsorted) forest plot / printout of a meta-analysis (labels = "id")
study labels provided by argument studlab in meta-analysis functions (labels = "studlab")
no study labels (labels = FALSE)

By default, study labels are used (labels = "studlab") if no label has more than three characters; otherwise IDs are used (labels = "id"). The connection between IDs and study labels (among other information) is part of a data frame which is invisibly returned (if argument study.results = TRUE).

Argument srt.labels can be used to change the rotation of IDs or study labels. By default, study labels are rotated by +/- 45 degrees if at least one study label has more than three characters; otherwise labels are not rotated.

If labels = "studlab", labels are rotated by -45 degrees for studies with a treatment estimate below the fixed effect estimate and otherwise by 45 degrees.

Author(s)

Gerta Rücker sc@imbi.uni-freiburg.de, Guido Schwarzer sc@imbi.uni-freiburg.de

References

Birnbaum A (1961): Confidence Curves: An Omnibus Technique for Estimation and Testing Statistical Hypotheses. Journal of the American Statistical Association, 56, 246–9

Infanger D and Schmidt-Trucksäss A (2019): P value functions: An underused method to present research results and to promote quantitative reasoning Statistics in Medicine, 38, 4189–97

Examples

data("lungcancer")
m1 <- metainc(d.smokers, py.smokers,
              d.nonsmokers, py.nonsmokers,
              data = lungcancer, studlab = study)

# Drapery plot
#
drapery(m1, xlim = c(0.5, 50))

## Not run: 
data(Fleiss1993bin)
m2 <- metabin(d.asp, n.asp, d.plac, n.plac,
         data = Fleiss1993bin, studlab = paste(study, year),
         sm = "OR", comb.random = FALSE)

# Produce drapery plot and print data frame with connection between
# IDs and study labels
#
(drapery(m2))

# For studies with a significant effect (p < 0.05), show
# study labels and print labels and lines in red
#
drapery(m2,
        labels = "studlab", subset.labels = pval < 0.05,
        srt.labels = 0, col.labels = "red",
        col.study = ifelse(pval < 0.05, "red", "darkgray"))

## End(Not run)