Forest plot to display the result of a meta-analysis

Description

Draws a forest plot in the active graphics window (using grid graphics system).

Usage

forest(x, ...)

## S3 method for class 'meta'
forest(x, sortvar, studlab=TRUE,
       comb.fixed=x$comb.fixed, comb.random=x$comb.random,
       overall=TRUE,
       text.fixed=if (x$level!=x$level.comb) paste("Fixed effect model (",
                    round(x$level.comb*100), "%-CI)", sep="")
                  else "Fixed effect model",
       text.random=if (x$level!=x$level.comb) paste("Random effects model (",
                    round(x$level.comb*100), "%-CI)", sep="")
                  else "Random effects model",
       lty.fixed=2, lty.random=3,
       prediction=x$prediction,
       text.predict=if (!(length(x$level.predict)==0) &&
                        x$level!=x$level.predict)
                     paste("Prediction interval (",
                           round(x$level.predict*100), "%)",
                     sep="") else "Prediction interval",
       bylab=x$bylab, print.byvar=x$print.byvar,
       text.fixed.w=text.fixed, text.random.w=text.random,
       bysort=FALSE,
       pooled.totals=comb.fixed|comb.random, pooled.events=FALSE,
       xlab="", xlab.pos=ref,
       smlab=NULL, smlab.pos=ref, xlim="symmetric",
       allstudies=TRUE,
       weight,
       pscale=1,
       ref=ifelse(backtransf & is.relative.effect(x$sm), 1, 0),
       layout="meta",
       leftcols=NULL, rightcols=NULL,
       leftlabs=NULL, rightlabs=NULL,
       lab.e=x$label.e, lab.c=x$label.c,
       lab.e.attach.to.col=NULL, lab.c.attach.to.col=NULL,
       label.right=x$label.right, label.left=x$label.left,
       lab.NA=".",
       lab.NA.effect="",
       lwd=1,
       at=NULL, label=TRUE,
       col.i="black", col.i.inside.square="white",
       col.square="gray", col.square.lines=col.square,
       col.diamond="gray",
       col.diamond.fixed=col.diamond, col.diamond.random=col.diamond,
       col.diamond.lines="black",
       col.diamond.fixed.lines=col.diamond.lines,
       col.diamond.random.lines=col.diamond.lines,
       col.predict="red", col.predict.lines="black",
       col.by="darkgray",
       print.I2=comb.fixed|comb.random, print.I2.ci=FALSE,
       print.tau2=comb.fixed|comb.random,
       print.Q=FALSE, print.pval.Q=comb.fixed|comb.random,
       hetstat=print.I2|print.tau2|print.Q|print.pval.Q,
       overall.hetstat=overall&hetstat,
       hetlab="Heterogeneity: ",
       text.I2 = "I-squared",
       text.tau2 = "tau-squared",
       test.overall=.settings$test.overall,
       test.overall.fixed=comb.fixed&overall&test.overall,
       test.overall.random=comb.random&overall&test.overall,
       label.test.overall.fixed=paste("Test for overall effect",
         if (comb.fixed & comb.random) " (fixed effect)", ": ", sep=""),
       label.test.overall.random=paste("Test for overall effect",
         if (comb.fixed & comb.random) " (random effects)", ": ", sep=""),
       test.subgroup=.settings$test.subgroup,
       test.subgroup.fixed=if (missing(test.subgroup)) FALSE else test.subgroup,
       test.subgroup.random=if (missing(test.subgroup)) !is.null(x$byvar)&
         comb.random&test.subgroup else test.subgroup,
       print.Q.subgroup=print.Q,
       label.test.subgroup.fixed="Test for subgroup differences (fixed effect): ",
       label.test.subgroup.random=paste("Test for subgroup differences",
        if (test.subgroup.fixed | comb.fixed) " (random effects)", ": ", sep=""),
       fontsize=12,
       fs.heading=fontsize,
       fs.fixed=fontsize, fs.random=fs.fixed, fs.predict=fs.fixed, fs.study=fontsize,
       fs.fixed.labels=fs.fixed, fs.random.labels=fs.random, fs.predict.labels=fs.predict,
       fs.study.labels=fs.study, fs.hetstat=fontsize-2,
       fs.test.overall=fs.hetstat, fs.test.subgroup=fs.hetstat, fs.axis=fontsize,
       fs.smlab=fontsize, fs.xlab=fontsize, fs.lr=fontsize,
       ff.heading="bold",
       ff.fixed="bold", ff.random=ff.fixed, ff.predict=ff.fixed, ff.study="plain",
       ff.fixed.labels=ff.fixed, ff.random.labels=ff.random, ff.predict.labels=ff.predict,
       ff.study.labels=ff.study, ff.hetstat="bold.italic",
       ff.test.overall=ff.hetstat, ff.test.subgroup=ff.hetstat, ff.axis="plain",
       ff.smlab="bold", ff.xlab="plain", ff.lr="plain",
       #
       squaresize=0.8,
       #
       plotwidth=grid::unit(6, "cm"),
       colgap=grid::unit(2, "mm"),
       colgap.left=colgap, colgap.right=colgap,
       colgap.forest=colgap,
       colgap.forest.left=colgap.forest, colgap.forest.right=colgap.forest,
       #
       just="right", just.studlab="left", just.addcols="center",
       #
       addspace=TRUE,
       #
       new=TRUE,
       #
       backtransf=x$backtransf,
       digits = .settings$digits.forest, digits.se = .settings$digits.se,
       digits.pval = .settings$digits.pval, digits.pval.Q = .settings$digits.pval.Q,
       digits.Q = .settings$digits.Q, digits.tau2 = .settings$digits.tau2,
       digits.I2 = .settings$digits.I2, digits.weight = .settings$digits.weight,

       ...)

Arguments

Details

A forest plot, also called confidence interval plot, is drawn in the active graphics window. Subgroup analyses are conducted and displayed in the plot if byvar is not missing.

The forest function is based on the grid graphics system. In order to print the forest plot, (i) resize the graphics window, (ii) either use dev.copy2eps or dev.copy2pdf.

Result of a test for overall effect or subgroup differences are printed if argument test.overall.fixed, test.overall.random, test.subgroup.fixed, or test.subgroup.random is TRUE; by default, these arguments are FALSE. R function settings.meta can be used to change this default for the entire R session by setting argument test.overall=TRUE or test.subgroup=TRUE.

Information from object x is utilised if argument weight is missing. Weights from the fixed effect model are used (weight="fixed") if argument x$comb.fixed is TRUE; weights from the random effects model are used (weight="random") if argument x$comb.random is TRUE and x$comb.fixed is FALSE.

The arguments leftcols and rightcols can be used to specify columns which are plotted on the left and right side of the forest plot, respectively. If argument rightcols is FALSE, no columns will be plotted on the right side. By default, i.e. if arguments leftcols and rightcols are NULL and layout="meta", the following default columns will be plotted.

By default, estimated treatment effect and corresponding confidence interval will be printed. Depending on arguments comb.fixed and comb.random, weights of the fixed effect and/or random effects model will be given too. For an object of class metacum or metainf only the estimated treatment effect with confidence interval are plotted.

Depending on the class of the meta-analysis object a different set of columns is printed on the left side of a forest plot.

The arguments leftlabs and rightlabs can be used to specify column headings which are plotted on left and right side of the forest plot, respectively. For certain columns predefined labels exist. If the arguments leftlabs and rightlabs are NULL, the following default labels will be used:

For additional columns the column name will be used as label. It is possible to only provide labels for new columns (see Examples). Otherwise the length of leftlabs and rightlabs must be the same as the number of printed columns. The value NA can be used to specify columns using the default labels (see Example).

If argument layout="revman5" (and arguments leftcols and rightcols are NULL) all columns mentioned above will be printed on the left side of the forest plot.

If arguments lab.e and lab.c are NULL, "Experimental" and "Control" are used as labels for experimental and control group, respectively.

The arguments pscale can be used to rescale proportions for objects of class metaprop, e.g. pscale=100 means that proportions are expressed per 100 observations. This is useful in situations with (very) low proportions. For pscale=100, column heading and x-axis label are changed to "Prop (in %)" and "Proportion (in %)", respectively.

A prediction interval for treatment effect of a new study (Higgins et al., 2009) is given in the forest plot if arguments prediction and comb.random are TRUE. For graphical presentation of prediction intervals the approach by Guddat et al. (2012) is used.

Note, in R package meta, version 3.0-0 the following arguments have been removed from R function forest.meta: byvar, level, level.comb, level.predict. This functionality is now provided by R function update.meta (or directly in R functions metabin, metacont, metagen, metacor, and metaprop).

Author(s)

Guido Schwarzer sc@imbi.uni-freiburg.de

References

Guddat C, Grouven U, Bender R, Skipka G 2012), A note on the graphical presentation of prediction intervals in random-effects meta-analyses. Systematic Reviews, 1, 34.

Higgins JPT, Thompson SG, Spiegelhalter DJ (2009), A re-evaluation of random-effects meta-analysis. Journal of the Royal Statistical Society: Series A, 172, 137-159.

See Also

metabin, metacont, metagen

Examples

data(Olkin95)
meta1 <- metabin(event.e, n.e, event.c, n.c,
                 data=Olkin95, subset=c(41,47,51,59),
                 sm="RR", method="I",
                 studlab=paste(author, year))


#
# Do (symmetric) forest plot
#
forest(meta1)


#
# Forest plot specifying argument xlim
#
forest(meta1, xlim=c(0.01, 10))


#
# Add prediction interval to forest plot
#
forest(meta1, prediction=TRUE)


#
# Print results of test for overall effect
#
forest(meta1, test.overall.fixed=TRUE, test.overall.random=TRUE)


#
# Forest plot with 'classic' layout used in
# R package meta, version < 1.6-0
#
forest(meta1, col.square="black", hetstat=FALSE)


#
# Layout of forest plot similar to RevMan 5
#
forest(meta1, layout="revman5", comb.random=FALSE)


#
# Change set of columns printed on left side
# of forest plot
#
forest(meta1, comb.random=FALSE,
       leftcols="studlab")


#
# Do not print columns on right side of forest plot
#
forest(meta1, rightcols=FALSE)


#
# Change study label to "Author"
#
forest(meta1, comb.random=FALSE,
       leftlabs=c("Author", NA, NA, NA, NA))


#
# Just give effect estimate and 95% confidence interval
# on right side of forest plot
#
forest(meta1, rightcols=c("effect", "ci"))


#
# 1. Change order of columns on left side
# 2. Attach labels to columns 'event.e' and 'event.c'
#    instead of columns 'n.e' and 'n.c'
#
forest(meta1,
       leftcols=c("studlab", "n.e", "event.e", "n.c", "event.c"),
       lab.e.attach.to.col="event.e",
       lab.c.attach.to.col="event.c")


#
# Specify column labels only for newly created variables
# 'year' and 'author' (which are part of dataset Olkin95)
#
forest(meta1,
       leftcols=c("studlab", "event.e", "n.e", "event.c", "n.c",
                  "author", "year"),
       leftlabs=c("Author", "Year of Publ"))


#
# Center text in all columns
#
forest(meta1,
       leftcols=c("studlab", "event.e", "n.e", "event.c", "n.c",
                  "author", "year"),
       leftlabs=c("Author", "Year of Publ"), hetstat=FALSE,
       just="center", just.addcols="center", just.studlab="center")
## Not run: 
#
# Same result
#
forest(meta1,
       leftcols=c("studlab", "event.e", "n.e", "event.c", "n.c",
                  "author", "year"),
       leftlabs=c("Author", "Year of Publ"), hetstat=FALSE,
       just="c", just.addcols="c", just.studlab="c")

## End(Not run)

#
# Change some fontsizes and fontfaces
#
forest(meta1,
       fs.study=10, ff.study="italic",
       fs.study.label=11, ff.study.label="bold",
       fs.axis=5, ff.axis="italic",
       ff.smlab="bold.italic",
       ff.fixed="plain", ff.hetstat="plain")


#
# Change some colours
#
forest(meta1,
       col.diamond="green", col.diamond.lines="red",
       col.i=c("green", "blue", "red", "orange"),
       col.square="pink", col.square.lines="black")


#
# Sort by weight in fixed effect model
#
forest(meta1, sortvar=1/w.fixed, comb.random=FALSE)


#
# Sort by decreasing weight in fixed effect model
#
forest(meta1, sortvar=-1/w.fixed, comb.random=FALSE)


#
# Sort by size of treatment effect
#
forest(meta1, sortvar=TE, comb.random=FALSE)


#
# Sort by size of treatment effect
#
forest(meta1, sortvar=-TE, comb.random=FALSE)


#
# Sort by decreasing year of publication
#
forest(meta1, sortvar=-year, comb.random=FALSE)


#
# Sort studies by decreasing treatment effect within year subgroups
#
meta2 <- update(meta1, byvar=ifelse(year < 1987, "Before 1987", "1987 and later"),
                print.byvar=FALSE)
forest(meta2,
       sortvar=-TE, comb.random=FALSE)

#
# Print results of test for subgroup differences (random effects model)
#
forest(meta2,
       sortvar=-TE, comb.fixed=FALSE,
       test.subgroup.random=TRUE)

Results