drapery: Drapery plot

View source: R/drapery.R

draperyR Documentation

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,
  common = x$common,
  random = x$random,
  lty.common = 1,
  lwd.common = max(3, lwd.study),
  col.common = "blue",
  lty.random = 1,
  lwd.random = lwd.common,
  col.random = "red",
  sign = NULL,
  lty.sign = 1,
  lwd.sign = 1,
  col.sign = "black",
  prediction = 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 (random) "random" else "common",
  at = NULL,
  n.grid = if (type == "zvalue") 10000 else 1000,
  mar = c(5.1, 4.1, 4.1, 4.1),
  plot = TRUE,
  warn.deprecated = gs("warn.deprecated"),
  fixed,
  lwd.fixed,
  lty.fixed,
  col.fixed,
  ...
)

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.

common

A logical indicating whether to show result for the common effect model.

random

A logical indicating whether to show result for the random effects model.

lty.common

Line type for common effect meta-analysis.

lwd.common

Line width for common effect meta-analysis.

col.common

Colour of lines for common 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 common effect ("common") 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.

warn.deprecated

A logical indicating whether warnings should be printed if deprecated arguments are used.

fixed

Deprecated argument (replaced by 'common').

lwd.fixed

Deprecated argument (replaced by 'lwd.common').

lty.fixed

Deprecated argument (replaced by 'lty.common').

col.fixed

Deprecated argument (replaced by 'col.common').

...

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 common 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

See Also

forest, radial

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", 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)


meta documentation built on Sept. 18, 2022, 1:06 a.m.