forest: Forest plot to display the result of a meta-analysis

Description Usage Arguments Details Author(s) References See Also Examples

View source: R/forest.R

Description

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

Usage

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
forest(x, ...)

## S3 method for class 'meta'
forest(x, sortvar, studlab=TRUE,
       layout=gs("layout"),
       comb.fixed=x$comb.fixed, comb.random=x$comb.random,
       overall=TRUE,
       text.fixed=NULL,
       text.random=NULL,
       lty.fixed=2, lty.random=3, col.fixed="black", col.random="black",
       prediction=x$prediction,
       text.predict=NULL,
       subgroup=TRUE,
       print.subgroup.labels=TRUE,
       bylab=x$bylab, print.byvar=x$print.byvar,
       byseparator=x$byseparator,
       text.fixed.w=text.fixed, text.random.w=text.random, bysort=FALSE, 
       pooled.totals=comb.fixed|comb.random, pooled.events=FALSE,
       pooled.times=FALSE, study.results=TRUE,
       xlab="", xlab.pos,
       smlab=NULL, smlab.pos, xlim="symmetric",
       allstudies=TRUE,
       weight.study, weight.subgroup,
       pscale=x$pscale, irscale=x$irscale, irunit=x$irunit,
       ref=ifelse(backtransf & is.relative.effect(x$sm), 1, 0),
       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, bottom.lr=TRUE,
       lab.NA=".",
       lab.NA.effect="",
       lwd=1,
       at=NULL, label=TRUE,
       type.study="square", type.fixed="diamond", type.random=type.fixed,
       type.subgroup=ifelse(study.results, "diamond", "square"),
       col.study="black",
       col.square="gray", col.square.lines=col.square,
       col.inside="white",
       col.diamond="gray",
       col.diamond.fixed=col.diamond, col.diamond.random=col.diamond,
       col.diamond.lines="black",
       col.diamond.lines.fixed=col.diamond.lines,
       col.diamond.lines.random=col.diamond.lines,
       col.inside.fixed=col.inside,
       col.inside.random=col.inside,
       col.predict="red", col.predict.lines="black",
       col.by="darkgray",
       col.label.right="black", col.label.left="black",
       hetstat = print.I2 | print.tau2 | print.Q | print.pval.Q | print.Rb,
       overall.hetstat = overall & hetstat,
       hetlab = "Heterogeneity: ",
       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,
       print.Rb = FALSE,
       print.Rb.ci = FALSE,
       text.subgroup.nohet = "not applicable",
       ##
       test.overall=gs("test.overall"),
       test.overall.fixed=comb.fixed&overall&test.overall,
       test.overall.random=comb.random&overall&test.overall,
       label.test.overall.fixed, label.test.overall.random,
       print.zval=TRUE,
       ##
       test.subgroup,
       test.subgroup.fixed, test.subgroup.random,
       print.Q.subgroup=TRUE,
       label.test.subgroup.fixed, label.test.subgroup.random,
       ##
       test.effect.subgroup,
       test.effect.subgroup.fixed, test.effect.subgroup.random,
       label.test.effect.subgroup.fixed,
       label.test.effect.subgroup.random,
       ##
       fontsize=12,
       fs.heading = fontsize,
       fs.fixed, fs.random, fs.predict,
       fs.fixed.labels, fs.random.labels, fs.predict.labels,
       fs.study = fontsize, fs.study.labels = fs.study,
       fs.hetstat, fs.test.overall,
       fs.test.subgroup, fs.test.effect.subgroup,
       fs.axis = fontsize, fs.smlab = fontsize, fs.xlab = fontsize,
       fs.lr = fontsize,
       ff.heading = "bold",
       ff.fixed, ff.random, ff.predict,
       ff.fixed.labels, ff.random.labels, ff.predict.labels,
       ff.study = "plain", ff.study.labels = ff.study,
       ff.hetstat, ff.test.overall,
       ff.test.subgroup, ff.test.effect.subgroup,
       ff.axis = "plain", ff.smlab = "bold", ff.xlab = "plain",
       ff.lr = "plain",
       #
       squaresize=0.8 / spacing,
       #
       plotwidth = if (layout != "JAMA") "6cm" else "8cm",
       colgap = "2mm",
       colgap.left = colgap, colgap.right = colgap,
       colgap.studlab = colgap.left, colgap.forest = colgap,
       colgap.forest.left = colgap.forest,
       colgap.forest.right = colgap.forest,
       #
       calcwidth.pooled=TRUE,
       calcwidth.fixed=calcwidth.pooled,
       calcwidth.random=calcwidth.pooled,
       calcwidth.predict=FALSE,
       calcwidth.hetstat=FALSE, calcwidth.tests=FALSE,
       calcwidth.subgroup=FALSE,
       #
       just=if (layout != "JAMA") "right" else "left",
       just.studlab="left", just.addcols="center",
       just.addcols.left=just.addcols, just.addcols.right=just.addcols,
       #
       spacing = 1,
       addrow, addrow.overall, addrow.subgroups,
       #
       new=TRUE,
       #
       backtransf=x$backtransf,
       digits=gs("digits.forest"), digits.se=gs("digits.se"),
       digits.zval=gs("digits.zval"),
       digits.pval=max(gs("digits.pval")-2, 2),
       digits.pval.Q=max(gs("digits.pval.Q")-2, 2),
       digits.Q=gs("digits.Q"),
       digits.tau2=gs("digits.tau2"),
       digits.I2=max(gs("digits.I2")-1, 0),
       digits.weight=gs("digits.weight"),
       #
       digits.mean = digits, digits.sd = digits.se,
       digits.cor = digits, digits.time = digits,
       #
       scientific.pval = gs("scientific.pval"), big.mark = gs("big.mark"),
       #
       col.i=col.study, weight=weight.study,
       ...)

## S3 method for class 'metabind'
forest(x,
       leftcols, leftlabs,
       rightcols=c("effect", "ci"), rightlabs,
       #
       overall=FALSE, subgroup=FALSE, overall.hetstat=FALSE,
       #
       lab.NA="",
       #
       digits=gs("digits.forest"),
       digits.se=gs("digits.se"),
       digits.zval=gs("digits.zval"),
       digits.pval=max(gs("digits.pval") - 2, 2),
       digits.pval.Q=max(gs("digits.pval.Q") - 2, 2),
       digits.Q=gs("digits.Q"),
       digits.tau2=gs("digits.tau2"),
       digits.I2=max(gs("digits.I2") - 1, 0),
       #
       scientific.pval=gs("scientific.pval"),
       big.mark=gs("big.mark"),
       #
       smlab,
       ...)			    

Arguments

x

An object of class meta or metabind.

sortvar

An optional vector used to sort the individual studies (must be of same length as x$TE).

studlab

A logical indicating whether study labels should be printed in the graph. A vector with study labels can also be provided (must be of same length as x$TE then).

layout

A character string specifying the layout of the forest plot (see Details).

comb.fixed

A logical indicating whether fixed effect estimate should be plotted.

comb.random

A logical indicating whether random effects estimate should be plotted.

overall

A logical indicating whether overall summaries should be plotted. This argument is useful in a meta-analysis with subgroups if summaries should only be plotted on group level.

text.fixed

A character string used in the plot to label the pooled fixed effect estimate.

text.random

A character string used in the plot to label the pooled random effects estimate.

lty.fixed

Line type (pooled fixed effect estimate).

lty.random

Line type (pooled random effects estimate).

col.fixed

Line colour (pooled fixed effect estimate).

col.random

Line colour (pooled random effects estimate).

prediction

A logical indicating whether a prediction interval should be printed.

text.predict

A character string used in the plot to label the prediction interval.

subgroup

A logical indicating whether subgroup results should be shown in forest plot. This argument is useful in a meta-analysis with subgroups if summaries should not be plotted on group level.

print.subgroup.labels

A logical indicating whether subgroup label should be printed.

bylab

A character string with a label for the grouping variable.

print.byvar

A logical indicating whether the name of the grouping variable should be printed in front of the group labels.

byseparator

A character string defining the separator between label and levels of grouping variable.

text.fixed.w

A character string to label the pooled fixed effect estimate within subgroups, or a character vector of same length as number of subgroups with corresponging labels.

text.random.w

A character string to label the pooled random effect estimate within subgroups, or a character vector of same length as number of subgroups with corresponging labels.

bysort

A logical indicating whether groups should be ordered alphabetically.

pooled.totals

A logical indicating whether total number of observations should be given in the figure.

pooled.events

A logical indicating whether total number of events should be given in the figure.

pooled.times

A logical indicating whether total person time at risk should be given in the figure.

study.results

A logical indicating whether results for individual studies should be shown in the figure (useful to only plot subgroup results).

xlab

A label for the x-axis.

xlab.pos

A numeric specifying the center of the label on the x-axis.

smlab

A label for the summary measurex (printed at top of figure).

smlab.pos

A numeric specifying the center of the label for the summary measure.

xlim

The x limits (min,max) of the plot, or the character "s" to produce symmetric forest plots.

allstudies

A logical indicating whether studies with inestimable treatment effects should be plotted.

weight.study

A character string indicating weighting used to determine size of squares or diamonds (argument type.study) to plot individual study results. One of missing, "same", "fixed", or "random", can be abbreviated. Plot symbols have the same size for all studies or represent study weights from fixed effect or random effects model.

weight.subgroup

A character string indicating weighting used to determine size of squares or diamonds (argument type.subgroup) to plot subgroup results. One of missing, "same", or "weight", can be abbreviated. Plot symbols have the same size for all subgroup results or represent subgroup weights from fixed effect or random effects model.

pscale

A numeric giving scaling factor for printing of single event probabilities or risk differences, i.e. if argument sm is equal to "PLOGIT", "PLN", "PRAW", "PAS", "PFT", or "RD".

irscale

A numeric defining a scaling factor for printing of single incidence rates or incidence rate differences, i.e. if argument sm is equal to "IR", "IRLN", "IRS", "IRFT", or "IRD".

irunit

A character specifying the time unit used to calculate rates, e.g. person-years.

ref

A numerical giving the reference value to be plotted as a line in the forest plot. No reference line is plotted if argument ref is equal to NA.

leftcols

A character vector specifying (additional) columns to be plotted on the left side of the forest plot or a logical value (see Details).

rightcols

A character vector specifying (additional) columns to be plotted on the right side of the forest plot or a logical value (see Details).

leftlabs

A character vector specifying labels for (additional) columns on left side of the forest plot (see Details).

rightlabs

A character vector specifying labels for (additional) columns on right side of the forest plot (see Details).

lab.e

Label to be used for experimental group in table heading.

lab.c

Label to be used for control group in table heading.

lab.e.attach.to.col

A character specifying the column name where label lab.e should be attached to in table heading.

lab.c.attach.to.col

A character specifying the column name where label lab.c should be attached to in table heading.

label.left

Graph label on left side of forest plot.

label.right

Graph label on right side of forest plot.

bottom.lr

A logical indicating whether labels on right and left side should be printed at bottom or top of forest plot.

lab.NA

A character string to label missing values.

lab.NA.effect

A character string to label missing values in individual treatment estimates and confidence intervals.

lwd

The line width, see par.

at

The points at which tick-marks are to be drawn, see grid.xaxis.

label

A logical value indicating whether to draw the labels on the tick marks, or an expression or character vector which specify the labels to use. See grid.xaxis.

type.study

A character string or vector specifying how to plot treatment effects and confidence intervals for individual studies (see Details).

type.fixed

A character string specifying how to plot treatment effect and confidence interval for fixed effect meta-analysis (see Details).

type.random

A character string specifying how to plot treatment effect and confidence interval for random effects meta-analysis (see Details).

type.subgroup

A character string specifying how to plot treatment effect and confidence interval for subgroup results (see Details).

col.study

The colour for individual study results and confidence limits.

col.inside

The colour for individual study results and confidence limits if confidence limits are completely within squares.

col.square

The colour for squares reflecting study's weight in the meta-analysis.

col.square.lines

The colour for the outer lines of squares reflecting study's weight in the meta-analysis.

col.diamond

The colour of diamonds representing the results for fixed effect and random effects models.

col.diamond.fixed

The colour of diamonds for fixed effect estimates.

col.diamond.random

The colour of diamonds for random effects estimates.

col.diamond.lines

The colour of the outer lines of diamonds representing the results for fixed effect and random effects models.

col.diamond.lines.fixed

The colour of the outer lines of diamond for fixed effect estimate.

col.diamond.lines.random

The colour of the outer lines of diamond for random effects estimate.

col.inside.fixed

The colour for result of fixed effect meta-analysis if confidence limit lies completely within square.

col.inside.random

The colour for result of random effects meta-analysis if confidence limit lies completely within square.

col.predict

Background colour of prediction interval.

col.predict.lines

Colour of outer lines of prediction interval.

col.by

The colour to print information on subgroups.

col.label.right

The colour for label on right side of null effect.

col.label.left

The colour for label on left side of null effect.

hetstat

A logical value indicating whether to print results for heterogeneity measures at all.

overall.hetstat

A logical value indicating whether to print results for heterogeneity measures for overall treatment comparisons. This argument is useful in a meta-analysis with subgroups if heterogeneity statistics should only be printed on subgroup level.

hetlab

Label printed in front of results for heterogeneity measures.

print.I2

A logical value indicating whether to print the value of the I-squared statistic.

print.I2.ci

A logical value indicating whether to print the confidence interval of the I-squared statistic.

print.tau2

A logical value indicating whether to print the value of the between-study variance tau-squared.

print.Q

A logical value indicating whether to print the value of the heterogeneity statistic Q.

print.pval.Q

A logical value indicating whether to print the p-value of the heterogeneity statistic Q.

print.Rb

A logical value indicating whether to print the value of the I-squared statistic.

print.Rb.ci

A logical value indicating whether to print the confidence interval of the I-squared statistic.

text.subgroup.nohet

A logical value or character string which is printed to indicate subgroups with less than two studies contributing to meta-analysis (and thus without heterogeneity). If FALSE, heterogeneity statistics are printed (with NAs).

test.overall

A logical value indicating whether to print results of test for overall effect.

test.overall.fixed

A logical value indicating whether to print results of test for overall effect (based on fixed effect model).

test.overall.random

A logical value indicating whether to print results of test for overall effect (based on random effects model).

label.test.overall.fixed

Label printed in front of results of test for overall effect (based on fixed effect model).

label.test.overall.random

Label printed in front of results of test for overall effect (based on random effects model).

print.zval

A logical value indicating whether z-value for test of treatment effect should be printed.

test.subgroup

A logical value indicating whether to print results of test for subgroup differences.

test.subgroup.fixed

A logical value indicating whether to print results of test for subgroup differences (based on fixed effect model).

test.subgroup.random

A logical value indicating whether to print results of test for subgroup differences (based on random effects model).

print.Q.subgroup

A logical value indicating whether to print the value of the heterogeneity statistic Q (test for subgroup differences).

label.test.subgroup.fixed

Label printed in front of results of test for subgroup differences (based on fixed effect model).

label.test.subgroup.random

Label printed in front of results of test for subgroup differences (based on random effects model).

test.effect.subgroup

A logical value indicating whether to print results of test for effect in subgroups.

test.effect.subgroup.fixed

A logical value indicating whether to print results of test for effect in subgroups (based on fixed effect model).

test.effect.subgroup.random

A logical value indicating whether to print results of test for effect in subgroups (based on random effects model).

label.test.effect.subgroup.fixed

Label printed in front of results of test for effect in subgroups (based on fixed effect model).

label.test.effect.subgroup.random

Label printed in front of results of test for effect in subgroups (based on random effects model).

fontsize

The size of text (in points), see gpar.

fs.heading

The size of text for column headings, see gpar.

fs.fixed

The size of text for results of fixed effect model, see gpar.

fs.random

The size of text for results of random effects model, see gpar.

fs.predict

The size of text for results of prediction interval, see gpar.

fs.fixed.labels

The size of text for label of fixed effect model, see gpar.

fs.random.labels

The size of text for label of random effects model, see gpar.

fs.predict.labels

The size of text for label of prediction interval, see gpar.

fs.study

The size of text for results of individual studies, see gpar.

fs.study.labels

The size of text for labels of individual studies, see gpar.

fs.hetstat

The size of text for heterogeneity measures, see gpar.

fs.test.overall

The size of text of test for overall effect, see gpar.

fs.test.subgroup

The size of text of test of subgroup differences, see gpar.

fs.test.effect.subgroup

The size of text of test of effect in subgroups, see gpar.

fs.axis

The size of text on x-axis, see gpar.

fs.smlab

The size of text of label for summary measure, see gpar.

fs.xlab

The size of text of label on x-axis, see gpar.

fs.lr

The size of text of label on left and right side of forest plot, see gpar.

ff.heading

The fontface for column headings, see gpar.

ff.fixed

The fontface of text for results of fixed effect model, see gpar.

ff.random

The fontface of text for results of random effects model, see gpar.

ff.predict

The fontface of text for results of prediction interval, see gpar.

ff.fixed.labels

The fontface of text for label of fixed effect model, see gpar.

ff.random.labels

The fontface of text for label of random effects model, see gpar.

ff.predict.labels

The fontface of text for label of prediction interval, see gpar.

ff.study

The fontface of text for results of individual studies, see gpar.

ff.study.labels

The fontface of text for labels of individual studies, see gpar.

ff.hetstat

The fontface of text for heterogeneity measures, see gpar.

ff.test.overall

The fontface of text of test for overall effect, see gpar.

ff.test.subgroup

The fontface of text for test of subgroup differences, see gpar.

ff.test.effect.subgroup

The fontface of text for test of effect in subgroups, see gpar.

ff.axis

The fontface of text on x-axis, see gpar.

ff.smlab

The fontface of text of label for summary measure, see gpar.

ff.xlab

The fontface of text of label on x-axis, see gpar.

ff.lr

The fontface of text of label on left and right side of forest plot, see gpar.

squaresize

A numeric used to increase or decrease the size of squares in the forest plot.

plotwidth

Either a character string, e.g., "8cm", "60mm", or "3inch", or a unit object specifying width of the forest plot.

colgap

Either a character string or a unit object specifying gap between columns printed on left and right side of forest plot.

colgap.left

Either a character string or a unit object specifying gap between columns printed on left side of forest plot.

colgap.right

Either a character string or a unit object specifying gap between columns printed on right side of forest plot.

colgap.studlab

Either a character string or a unit object specifying gap between column with study labels and subsequent column.

colgap.forest

Either a character string or a unit object specifying gap between column adjacent to forest plot and the forest plot.

colgap.forest.left

Either a character string or a unit object specifying gap between column on the left side of forest plot and the forest plot.

colgap.forest.right

Either a character string or a unit object specifying gap between column on the right side of forest plot and the forest plot.

calcwidth.pooled

A logical indicating whether text for fixed effect and random effects model should be considered to calculate width of the column with study labels.

calcwidth.fixed

A logical indicating whether text given in arguments text.fixed and text.fixed.w should be considered to calculate width of the column with study labels.

calcwidth.random

A logical indicating whether text given in arguments text.random and text.random.w should be considered to calculate width of the column with study labels.

calcwidth.predict

A logical indicating whether text given in argument text.predict should be considered to calculate width of the column with study labels.

calcwidth.hetstat

A logical indicating whether text for heterogeneity statistics should be considered to calculate width of the column with study labels.

calcwidth.tests

A logical indicating whether text for tests of overall effect or subgroup differences should be considered to calculate width of the column with study labels.

calcwidth.subgroup

A logical indicating whether text with subgroup labels should be considered to calculate width of the column with study labels.

just

Justification of text in all columns but columns with study labels and additional variables (possible values: "left", "right", "center").

just.studlab

Justification of text for study labels (possible values: "left", "right", "center").

just.addcols

Justification of text for additional columns (possible values: "left", "right", "center").

just.addcols.left

Justification of text for additional columns on left side of forest plot (possible values: "left", "right", "center"). Can be of same length as number of additional columns on left side of forest plot.

just.addcols.right

Justification of text for additional columns on right side of forest plot (possible values: "left", "right", "center"). Can be of same length as number of additional columns on right side of forest plot.

spacing

A numeric determining line spacing in a forest plot.

addrow

A logical value indicating whether an empty row is printed above and below study results.

addrow.overall

A logical value indicating whether an empty row is printed above overall meta-analysis results.

addrow.subgroups

A logical value indicating whether an empty row is printed between results for subgroups.

new

A logical value indicating whether a new figure should be printed in an existing graphics window.

backtransf

A logical indicating whether results should be back transformed in forest plots. If backtransf=TRUE, results for sm="OR" are presented as odds ratios rather than log odds ratios and results for sm="ZCOR" are presented as correlations rather than Fisher's z transformed correlations, for example.

digits

Minimal number of significant digits for treatment effects, see print.default.

digits.se

Minimal number of significant digits for standard errors, see print.default.

digits.zval

Minimal number of significant digits for z- or t-statistic for test of overall effect, see print.default.

digits.tau2

Minimal number of significant digits for between-study variance, see print.default.

digits.pval

Minimal number of significant digits for p-value of overall treatment effect, see print.default.

digits.pval.Q

Minimal number of significant digits for p-value of heterogeneity test, see print.default.

digits.Q

Minimal number of significant digits for heterogeneity statistic Q, see print.default.

digits.I2

Minimal number of significant digits for I-squared statistic, see print.default.

digits.weight

Minimal number of significant digits for weights, see print.default.

digits.cor=NULL, digits.time=NULL,

digits.mean

Minimal number of significant digits for means; only applies to metacont objects.

digits.sd

Minimal number of significant digits for standard deviations; only applies to metacont objects.

digits.cor

Minimal number of significant digits for correlations; only applies to metacor objects.

digits.time

Minimal number of significant digits for times; only applies to metainc and metarate objects.

scientific.pval

A logical specifying whether p-values should be printed in scientific notation, e.g., 1.2345e-01 instead of 0.12345.

big.mark

A character used as thousands separator.

col.i

Deprecated argument (replaced by col.study).

weight

Deprecated argument (replaced by weight.study).

...

Additional graphical arguments (ignored at the moment).

Details

A forest plot, also called confidence interval plot, is drawn in the active graphics window. 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.

By default, treatment estimates and confidence intervals are plotted in the following way:

In a forest plot, size of the squares typically reflects the precision of individual treatment estimates based either on the fixed effect (weight.study="fixed") or random effects meta-analysis (weight.study="random"). Information from meta-analysis object x is utilised if argument weight.study is missing. Weights from the fixed effect model are used if argument x$comb.fixed is TRUE; weights from the random effects model are used if argument x$comb.random is TRUE and x$comb.fixed is FALSE. The same square sizes are used if weight.study="same".

Arguments text.fixed, text.random, and text.predict can be used to change the label to identify overall results (fixed effect and random effects model as well as prediction interval). By default the following text is printed:

If confidence interval levels are different for individual studies, meta-analysis, and prediciton interval (arguments level, level.comb, level.predict in meta-analysis functions, e.g. metabin), additional information is printed, e.g. " (99%-CI)" for a 99% confidence interval in the meta-analysis.

The following arguments can be used to print results for various statistical tests:

Argument Statistical test
test.overall.fixed Test for overall effect (fixed effect model)
test.overall.random Test for overall effect (random effects model)
test.effect.subgroup.fixed Test for effect in subgroup (FE model)
test.effect.subgroup.random Test for effect in subgroup (RE model)
test.subgroup.fixed Test for subgroup differences (FE model)
test.subgroup.random Test for subgroup differences (RE model)

By default, these arguments are FALSE. R function settings.meta can be used to change this default for the entire R session. For example, use the following command to always print results of tests for an overall effect:

settings.meta(test.overall=TRUE)

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 columns will be printed on the right side of the forest plot:

Meta-analysis results Value of argument rightcols
No summary c("effect", "ci")
Only fixed effect model c("effect", "ci", "w.fixed")
Only random effects model c("effect", "ci", "w.random")
Both models c("effect", "ci", "w.fixed", "w.random")

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 (which is defined by the R function used to generate the object) a different set of columns is printed on the left side of the forest plot:

Function Value of argument leftcols
metabin c("studlab", "event.e", "n.e",
"event.c", "n.c")
metacont c("studlab", "n.e", "mean.e", "sd.e",
"n.c", "mean.c", "sd.c")
metacor c("studlab", "n")
metagen c("studlab", "TE", "seTE")
metainc c("studlab", "event.e", "time.e",
"event.c", "time.c")
metaprop c("studlab", "event", "n")
metarate c("studlab", "event", "time")
metacum "studlab"
metainf "studlab"

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:

Column: studlab TE seTE n.e n.c n
Label: "Study" "TE" "seTE" "Total" "Total" "Total"
Column: event.e event.c event mean.e mean.c
Label: "Events" "Events" "Events" "Mean" "Mean"
Column: sd.e sd.c time.e time.c effect
Label: "SD" "SD" "Time" "Time" x$sm
Column: ci effect.ci w.fixed w.random
Label: x$level"%-CI" effect+ci "W(fixed)" "W(random)"

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, respectively. The value NA can be used to specify columns which should use default labels (see Examples).

If argument layout="RevMan5" (and arguments leftcols and rightcols are NULL), the layout for forest plots used for Cochrane reviews (which are generated with Review Manager 5, http://community.cochrane.org/tools/review-production-tools/revman-5) is reproduced:

  1. All columns are printed on the left side of the forest plot (see arguments leftcols and rightcols)

  2. Tests for overall effect and subgroup differences are printed (test.overall, test.effect.subgroup, test.subgroup)

  3. Diamonds representing meta-analysis results are printed in black (diamond.fixed, diamond.random)

  4. Color of squares depends on the meta-analysis object (col.square, col.square.lines)

  5. Information on effect measure and meta-analysis method is printed above the forest plot (smlab)

  6. Label "Study or Subgroup" is printed for meta-analysis with subgroups (leftlabs)

If argument layout="JAMA" (and arguments leftcols and rightcols are NULL), instructions for authors of the Journal of the American Medical Association, see http://jamanetwork.com/journals/jama/pages/instructions-for-authors, are taken into account:

  1. Graph labels on right and left side are printed in bold font at top of forest plot (see arguments bottom.lr and ff.lr)

  2. Information on effect measure and level of confidence interval is printed at bottom of forest plot (xlab)

  3. Tests for overall effect are printed (test.overall)

  4. Diamonds representing meta-analysis results are printed in lightblue (diamond.fixed, diamond.random)

  5. Squares representing individual study results are printed in darkblue (col.square, col.square.lines)

  6. Between-study variance τ^2 is not printed

  7. Empty rows are omitted (addrow)

  8. Label "Source" is printed instead of "Study" (leftlabs)

The following changes are conducted if argument layout="subgroup" (and arguments leftcols and rightcols are NULL) and a subgroup analysis was conducted:

  1. Individual study results are omitted (see argument study.results)

  2. Total number of observations is not printed (pooled.totals)

  3. Label "Subgroup" is printed instead of "Study" (leftlabs)

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

Argument pscale can be used to rescale single proportions or risk differences, e.g. pscale=1000 means that proportions are expressed as events per 1000 observations. This is useful in situations with (very) low event probabilities.

Argument irscale can be used to rescale single rates or rate differences, e.g. irscale=1000 means that rates are expressed as events per 1000 time units, e.g. person-years. This is useful in situations with (very) low rates. Argument irunit can be used to specify the time unit used in individual studies (default: "person-years"). This information is printed in summaries and forest plots if argument irscale is not equal to 1.

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, e.g., metabin, metacont, metagen, metacor, and metaprop).

Author(s)

Guido Schwarzer [email protected]

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, metabind, settings.meta

Examples

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
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))


## Not run: 
#
# Do standard (symmetric) forest plot
#
forest(meta1)

## End(Not run)


#
# Layout of forest plot similar to Review Mananager 5
# (see http://community.cochrane.org/tools/review-production-tools/revman-5)
#
# Furthermore, add labels on both sides of forest plot and prediction
# interval
#
forest(meta1, layout="RevMan5", comb.fixed=FALSE,
       label.right="Favours control", col.label.right="red",
       label.left="Favours experimental", col.label.left="green",
       prediction=TRUE)


## Not run: 
#
# 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)


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


#
# 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)


#
# 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
# on right side of forest plot (in one column)
#
forest(meta1, rightcols=c("effect.ci"))


#
# Just give effect estimate and 95
# 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")

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


#
# 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.study=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)


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

#
# Print only subgroup results
#
forest(meta2, layout="subgroup")

#
# Print only subgroup results
# (and consider text for heterogeneity measures in width of subgroup
#  column)
#
forest(meta2, layout="subgroup", calcwidth.hetstat=TRUE)

## End(Not run)

Example output

Loading 'meta' package (version 4.8-4).
Type 'help(meta)' for a brief overview.

meta documentation built on Nov. 30, 2018, 4:22 p.m.