A forest plot, also called confidence interval plot, is drawn in
the active graphics window. The forest functions in R package
meta are based on the grid graphics system. Resize the
graphics windows if the forest plot is too large or too small for
the graphics window. Alternatively, save the forest plot in a file.
Saving forest plots
A forest plot can be directly stored in a file using argument
filename. The R function for the graphics device driver
can be specified using argument device, e.g.,
device = "cairo_pdf" or device = cairo_pdf. If only the
filename is provided, the extension of the filename is checked and matched
against the most common graphics device drivers:
| Extension | Graphics device |
.pdf | pdf |
.ps | postscript |
.svg | svg or svglite if the
R package svglite is available |
.bmp | bmp |
.jpg / .jpeg | jpeg |
.png | png |
.tif / .tiff | tiff |
If only argument device is provided, the filename will be equal to
"Rplots.device".
By default, the file dimensions are determined automatically
(values .height and .width). Automatic sizing is recommended
for most forest plots.
Arguments height and width can adjust these dimensions.
For example, width = .width * 1.05 increases the automatically
determined width by 5 percent. Absolute dimensions can also be supplied,
e.g., width = 10 for a file with a width of 10 inches.
Setting either argument to NA uses the corresponding dimension
of the current graphics device.
The deprecated argument rows.gr uses a different approach to
determine file height and is retained only for backward compatibility.
Set dev.off = FALSE to keep the graphics device open and add
further forest plots to the same file. Afterwards, call
dev.off to close the device and finalize the file.
Additional arguments to the graphics device function can be supplied
as a named list in device.args.
Default forest plot layout
By default, treatment estimates and confidence intervals are
plotted in the following way. The plot types can be specified with the
named list type; see meta-formatting for the
available list elements. The individual arguments type.study,
type.common, type.random, type.subgroup,
type.subgroup.common, and type.subgroup.random are also
supported.
For an individual study, a square with treatment estimate in
the center and confidence interval as a line extending either side
of the square (type.study = "square")
For overall meta-analysis results, a diamond is used by default
(type.common = "diamond" and type.random = "diamond").
For subgroup results, a diamond is used by default if individual
study results are shown; otherwise, a square is used
(type.subgroup, type.subgroup.common,
type.subgroup.random, and study.results).
In a forest plot, size of the squares typically reflects the precision of
individual treatment estimates based either on the common effect
(weight.study = "common") 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 common effect model are used if argument x$common is
TRUE; weights from the random effects model are used if argument
x$random is TRUE and x$common is FALSE.
The same square sizes are used if weight.study = "same".
If prediction = TRUE, a prediction interval for the treatment
effect in a new study is shown (Higgins et al., 2009). The interval is
displayed as a bar, following Guddat et al. (2012).
Columns printed on left side of forest plot
Argument leftcols specifies the columns printed on the left side
of the forest plot. If leftcols = NULL and layout = "meta",
the following columns are printed by default. These column names can
be used in leftcols or rightcols:
| Column | Description |
"studlab" | study labels |
| ... | outcome-specific columns |
"w.common" | weights from the common effect model, if applicable |
"w.random" | weights from the random-effects model, if applicable |
"effect" | estimated effect in the study |
"ci" | confidence interval for the estimated effect |
For three-level models, the cluster variable is printed next to the
study labels. Use "cluster" in leftcols to select this column,
for example, to change the order of variables.
The following outcome-specific columns are printed, depending on the
function used to create the meta-analysis object:
| Function | Default outcome-specific columns |
metabin | "event.e", "n.e",
"event.c", "n.c" |
metacont | "n.e", "mean.e", "sd.e",
"n.c", "mean.c", "sd.c" |
metacor | "n" |
metagen | "TE", "seTE" |
metainc | "event.e", "time.e",
"event.c", "time.c" |
metamean | "n", "mean", "sd" |
metaprop | "event", "n" |
metarate | "event", "time", "n" |
By default, study labels and labels for pooled estimates and
heterogeneity statistics will be printed in the first column on the
left side of the forest plot. The character string "studlab"
is used to identify study labels as this is the name of the list
element of a meta-analysis object.
If the character string "studlab" is not provided in either
leftcols or rightcols, the first additional
variable specified by the user is used as the study labels. Labels
for pooled estimates are also printed in this column. Additional
variables are variables not listed among the predefined column names
below. For example, leftcols = "studlab" and
leftcols = "study" produce the same forest plot if
"study" contains the study labels used in the meta-analysis.
If no additional variable is provided, no study labels are printed.
Columns printed on right side of forest plot
Argument rightcols can be used to specify columns printed on the
right side of the forest plot. By default, if rightcols is
NULL and layout = "meta", no columns are printed on the
right side; internally, rightcols is set to FALSE.
Previous default forest plot layout (layout = "meta8")
If layout = "meta8" is specified and both leftcols and
rightcols are NULL, the previous default forest plot layout
is used.
The following columns are printed on the left side of the forest plot.
These column names can also be used in argument leftcols or
rightcols:
| Column | Description |
"studlab" | study labels |
| ... | outcome-specific columns |
See the section on the default forest plot layout (layout = "meta")
for the outcome-specific columns.
The following columns are printed on the right side of the forest plot:
| Column | Description |
"effect" | estimated effect in the study |
"ci" | confidence interval for the estimated effect |
"w.common" | weights from the common effect model, if applicable |
"w.random" | weights from the random effects model, if applicable |
Predefined columns and column labels
The arguments leftlabs and rightlabs can be used to
specify column headings which are printed on the left or right side of
the forest plot. For certain columns predefined labels exist which
are used by default, i.e., if arguments leftlabs and
rightlabs are NULL:
| Column: | n.e, n.c, n | mean.e, mean.c, mean | sd.e, sd.c, sd |
| Label: | gs("label.n") | gs("label.mean") | gs("label.sd") |
| Column: | event.e, event.c, event | time.e, time.c, time | cor |
| Label: | gs("label.events") | gs("label.time") | gs("label.cor") |
| Column: | effect | ci | effect.ci |
| Label: | x$sm | x$level"% CI" | effect+ci |
| Column: | cluster | cycles | Label: |
gs("label.cluster") | gs("label.cycles") | Column: | pval |
statistic | Label: | gs("label.pval") | "z", "t", or "z|t" |
| Column: | tau2 | tau | I2 |
| Label: | gs("label.tau2") | gs("label.tau") | gs("label.I2") |
For the columns studlab (study labels), TE
(treatment estimates), seTE (standard errors of treatment estimates),
w.common (weights under the common effect model), and w.random
(weights under the random effects model), context-specific column labels
are used.
For other columns, the column name will be used as a label if no
column label is defined. 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 which
should use default labels (see Examples).
In pairwise meta-analysis comparing two groups (i.e.,
metabin, metacont,
metainc, and metagen depending on the
outcome), arguments label.e and label.c are used to
label columns belonging to the two treatment groups. By default,
labels defined in the meta-analysis object are used. The columns
where treatment labels are attached can be changed using arguments
label.e.attach and label.c.attach.
Spacing and width calculation
Information on heterogeneity measures and statistical tests is printed
below the meta-analysis results. Argument addrows.below.overall can
be used to specify the number of empty rows between these results and the
information below them. By default, no extra space is added.
The width of information printed in the leftmost column is automatically
included when calculating the width of the forest plot. Consequently, this
information does not overlap with the forest plot or x-axis by default. The
automatic calculation can be disabled using the relevant elements of
calcwidth; see meta-formatting. Gaps between
columns and plot elements can be adjusted with the named list
colgap or the corresponding individual arguments.
The widths of x-axis tick labels, smlab, xlab,
label.left, and label.right are also considered
automatically. Additional space is allocated through the corresponding
forest-plot gaps to avoid overlap with columns, statistics, details, or
other plot elements. User-specified values supplied through either the
colgap list elements forest.left and forest.right or
the individual arguments colgap.forest.left and
colgap.forest.right take precedence over the automatic calculation.
Title of forest plot
A title for the forest plot can be provided via argument main.
If main is not specified, the title is generated from the general
title, comparison label, and outcome label, i.e., the title,
complab, and outclab components of meta-analysis object
x.
If main.prefix = TRUE (the default), the prefixes
"Review:", "Comparison:", and "Outcome:" are added
automatically to the corresponding title lines. This can be prevented by
setting title.prefixes = FALSE.
Risk of bias assessment
A risk of bias (RoB) assessment can be shown in the forest plot by
either using a meta-analysis object with an RoB assessment as main
input or providing a suitable object created with
rob. Argument rob = FALSE can be used to
suppress the print of the risk of bias information.
RoB assessments are shown as the only information on the right side
of the forest plot if argument rob.only = TRUE. In this case,
arguments rightcols and rightlabs are ignored.
Predefined columns shown by default on the right side of a forest plot will
be moved to the left side.
Note, the column names for risk of bias domains cannot be changed with
argument rightlabs. You have to manually change the column names in
the risk of bias data set, i.e., list element 'rob' in the meta-analysis
object.
Information on heterogeneity and statistical tests
Argument hetstat can be a character string to specify where
to print heterogeneity information:
row with results for common effect model (hetstat =
"common"),
row with results for random effects model (hetstat =
"random").
Otherwise, information on heterogeneity measures is printed below
the meta-analysis results if argument overall.hetstat = TRUE
(default). The heterogeneity measures to print can be specified
(see list of arguments following overall.hetstat).
In addition, results for various statistical tests can be printed using
the named list test; see meta-formatting for the
available list elements. The individual arguments test.overall,
test.overall.common, test.overall.random,
test.subgroup, test.subgroup.common,
test.subgroup.random, test.effect.subgroup,
test.effect.subgroup.common, and
test.effect.subgroup.random are also supported:
| Argument | Statistical test |
test.overall.common | Test for overall effect (common
effect model) |
test.overall.random | Test for overall effect (random
effects model) |
test.effect.subgroup.common | Test for effect in subgroup
(CE model) |
test.effect.subgroup.random | Test for effect in subgroup
(RE model) |
test.subgroup.common | Test for subgroup differences (CE
model) |
test.subgroup.random | Test for subgroup differences (RE
model) |
By default, tests for an overall effect and tests for subgroup
differences are printed if the corresponding models or subgroup analyses
are available. Tests can be suppressed with the relevant arguments.
R function settings.meta can be used to change this default
for the entire R session.
Highlight regions corresponding to minimal clinically important
differences
Regions corresponding to minimal clinically important differences can be
added to the forest plot using either argument cid or
cid.below.null and cid.above.null. Input for the later
arguments will be ignored if argument cid was specified. In this case,
the values of cid.below.null and cid.above.null will be equal
to
Thresholds based on argument cid will always be symmetric. Asymmetric
thresholds can be defined using arguments cid.below.null and
cid.above.null.
Flexible printing of subgroup results
Argument subgroup determines whether summary results are
printed for subgroups. A logical vector of length equal to the
number of subgroups can be provided to determine which subgroup
summaries are printed. By default, only subgroup results based on
at least two studies are printed which is identical to use argument
subgroup = k.w > 1. The order of the logical vector corresponds to
the order of subgroups in list element 'subgroup.levels' of a
meta-analysis object. Argument subgroup = k.w >= 1 can be
used to show results for all subgroups (including those with a
single study).
The following arguments can be used in a similar way:
subgroup.hetstat (heterogeneity statistic in subgroups),
common.subgroup (common effect estimates in subgroups),
random.subgroup (random effects estimates in subgroups),
prediction.subgroup (prediction interval in subgroups),
test.effect.subgroup (test for effect in subgroups),
test.effect.subgroup.common (test for effect in subgroups,
common effect model),
test.effect.subgroup.random (test for effect in subgroups,
random effects model).
Data set with information to print with overall results
Argument data.pooled can be used to provide information printed in
the line(s) with overall results, i.e., for the common effect or random
effects model. Input must be a data frame with variable names equal to those
provided in arguments leftcols or rightcols. Only variables
for additional variables are considered.
It is possible to provide a row in data set data.pooled for each
common effect or random effects estimate. The order in the data set
corresponds to the order of common effect and random effects estimates in
the forest plot, i.e., common effect followed by random effects estimates.
If the data set contains a single row, the value provided for a variable is
considered for all printed common effect and random effects estimates
In meta-analyses with subgroups, a row must be provided in data set
data.pooled for each overall common effect or random effects estimate,
followed by common effect or random effects estimates within subgroups. The
order for subgroup results is the same as see in the forest plot.
Additional general settings
The named list text can be used to change labels identifying
overall results (common-effect and random-effects models) and prediction
intervals; see meta-formatting for the available list
elements. The individual arguments text.common,
text.random, and text.predict are also supported. By
default, the following text is printed:
"Common effect model" (argument text.common)
"Random effects model" (text.random)
"Prediction interval" (text.predict)
If confidence interval levels are different for individual studies,
meta-analysis, and prediction interval (arguments level,
level.ma, 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.
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.
Forest plots in RevMan5 layout
If argument layout = "RevMan5" (and arguments leftcols and
rightcols are NULL), the layout for forest plots used for
Cochrane reviews (which were generated with Review Manager 5) is reproduced:
All columns are printed on the left side of the forest plot
(see arguments leftcols and rightcols)
The main title is left aligned (just.main)
Tests for overall effect and subgroup differences are printed
(test.overall, test.subgroup)
Diamonds representing meta-analysis results are printed in
black (col.diamond.common, col.diamond.random)
Colour of squares depends on the meta-analysis object
(col.square, col.square.lines)
Information on effect measure and meta-analysis method is
printed above the forest plot (smlab)
Label "Study or Subgroup" is printed for meta-analysis with
subgroups (leftlabs)
Details on meta-analysis methods are not printed (details)
Forest plots in JAMA layout
If argument layout = "JAMA" (and arguments leftcols and
rightcols are NULL), instructions for authors of the
Journal of the American Medical Association are taken into account:
All columns are printed on the left side of the forest plot
(see arguments leftcols and rightcols)
The main title is left aligned (just.main)
Graph labels on right and left side are printed in bold font
at top of forest plot (see arguments bottom.lr and
ff.lr)
Information on effect measure and level of confidence
interval is printed at bottom of forest plot (xlab)
Tests for overall effect are printed (test.overall)
Diamonds representing meta-analysis results are printed in
lightblue (col.diamond.common, col.diamond.random)
Squares representing individual study results are printed in
darkblue (col.square, col.square.lines)
Between-study variance \(\tau^2\) is not printed
Empty rows are omitted (addrow, addrow.overall,
addrow.subgroups)
Label "Source" is printed instead of "Study" (leftlabs)
P-values are printed without leading zeros (zero.pval)
P-values are rounded to three digits (for 0.001 < p \(\le\)
0.01) or two digits (p > 0.01) (JAMA.pval)
Details on meta-analysis methods are not printed (details)
Study labels according to JAMA guidelines can be generated using
labels.meta.
Forest plots in BMJ layout
If argument layout = "BMJ" (and arguments leftcols and
rightcols are NULL), the following features of forest plots
for the British Medical Journal are taken into account:
Columns are printed on the left and right side of the forest plot
(see arguments leftcols and rightcols)
The main title is center aligned (just.main)
Combined treatment-group headers are centered over both columns for
binary outcomes, continuous outcomes, and incidence rates
Prediction intervals are shown if requested (prediction)
Tests for overall effect and subgroup differences are printed
(test.overall, test.subgroup)
Details on meta-analysis methods are not printed (details)
Forest plots showing results of subgroups
The following changes are conducted if argument
layout = "subgroup" (and arguments leftcols and
rightcols are NULL) and a subgroup analysis was
conducted:
Individual study results are omitted (see argument
study.results)
Total number of observations is not printed
(pooled.totals)
Label "Subgroup" is printed instead of "Study"
(leftlabs)