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

```
# S3 method for meta
forest(
x,
sortvar,
studlab = TRUE,
layout = gs("layout"),
common = x$common,
random = x$random,
overall = x$overall,
text.common = x$text.common,
text.random = x$text.random,
lty.common = gs("lty.common"),
lty.random = gs("lty.random"),
col.common = gs("col.common"),
col.random = gs("col.random"),
text.w.common = x$text.w.common,
text.w.random = x$text.w.random,
prediction = x$prediction,
text.predict = x$text.predict,
subgroup = TRUE,
subgroup.hetstat = subgroup & (is.character(hetstat) || hetstat),
print.subgroup.labels = TRUE,
subgroup.name = x$subgroup.name,
print.subgroup.name = x$print.subgroup.name,
sep.subgroup = x$sep.subgroup,
text.common.w = text.common,
text.random.w = text.random,
text.predict.w = text.predict,
sort.subgroup = gs("sort.subgroup"),
pooled.totals = common | random,
pooled.events = gs("pooled.events"),
pooled.times = gs("pooled.times"),
study.results = gs("study.results"),
xlab = "",
xlab.pos,
smlab = NULL,
smlab.pos,
xlim = "symmetric",
allstudies = TRUE,
weight.study = NULL,
pscale = x$pscale,
irscale = x$irscale,
irunit = x$irunit,
ref,
lower.equi = gs("lower.equi"),
upper.equi = gs("upper.equi"),
lty.equi = gs("lty.equi"),
col.equi = gs("col.equi"),
fill.equi = gs("fill.equi"),
fill.lower.equi = fill.equi,
fill.upper.equi = rev(fill.equi),
leftcols = NULL,
rightcols = NULL,
leftlabs = NULL,
rightlabs = NULL,
label.e = x$label.e,
label.c = x$label.c,
label.e.attach = NULL,
label.c.attach = NULL,
label.right = x$label.right,
label.left = x$label.left,
bottom.lr = gs("bottom.lr"),
lab.NA = gs("lab.NA"),
lab.NA.effect = gs("lab.NA.effect"),
lab.NA.weight = gs("lab.NA.weight"),
lwd = gs("lwd"),
at = NULL,
label = TRUE,
type.study = gs("type.study"),
type.common = gs("type.common"),
type.random = type.common,
type.subgroup = ifelse(study.results, "diamond", "square"),
type.subgroup.common = type.subgroup,
type.subgroup.random = type.subgroup,
col.study = gs("col.study"),
col.square = gs("col.square"),
col.square.lines = col.square,
col.inside = gs("col.inside"),
col.inside.common = col.inside,
col.inside.random = col.inside,
col.diamond = gs("col.diamond"),
col.diamond.common = col.diamond,
col.diamond.random = col.diamond,
col.diamond.lines = gs("col.diamond.lines"),
col.diamond.lines.common = col.diamond.lines,
col.diamond.lines.random = col.diamond.lines,
col.predict = gs("col.predict"),
col.predict.lines = gs("col.predict.lines"),
col.subgroup = gs("col.subgroup"),
col.label.right = gs("col.label.right"),
col.label.left = gs("col.label.left"),
hetstat = common | random | overall.hetstat,
overall.hetstat = x$overall.hetstat,
hetlab = gs("hetlab"),
resid.hetstat = gs("resid.hetstat"),
resid.hetlab = gs("resid.hetlab"),
print.I2 = gs("forest.I2"),
print.I2.ci = gs("forest.I2.ci"),
print.tau2 = gs("forest.tau2"),
print.tau2.ci = gs("forest.tau2.ci"),
print.tau = gs("forest.tau"),
print.tau.ci = gs("forest.tau.ci"),
print.Q = gs("forest.Q"),
print.pval.Q = gs("forest.pval.Q"),
print.Rb = gs("forest.Rb"),
print.Rb.ci = gs("forest.Rb.ci"),
text.subgroup.nohet = gs("text.subgroup.nohet"),
LRT = gs("LRT"),
test.overall = gs("test.overall"),
test.overall.common = common & overall & test.overall,
test.overall.random = random & overall & test.overall,
label.test.overall.common,
label.test.overall.random,
print.stat = gs("forest.stat"),
test.subgroup = x$test.subgroup,
test.subgroup.common = test.subgroup & common,
test.subgroup.random = test.subgroup & random,
prediction.subgroup = x$prediction.subgroup,
print.Q.subgroup = gs("forest.Q.subgroup"),
label.test.subgroup.common,
label.test.subgroup.random,
test.effect.subgroup = gs("test.effect.subgroup"),
test.effect.subgroup.common,
test.effect.subgroup.random,
label.test.effect.subgroup.common,
label.test.effect.subgroup.random,
text.addline1,
text.addline2,
header.line,
fontsize = gs("fontsize"),
fontfamily = gs("fontfamily"),
fs.heading = fontsize,
fs.common = gs("fs.common"),
fs.random = gs("fs.random"),
fs.predict = gs("fs.predict"),
fs.common.labels = gs("fs.common.labels"),
fs.random.labels = gs("fs.random.labels"),
fs.predict.labels = gs("fs.predict.labels"),
fs.study = fontsize,
fs.study.labels = fs.study,
fs.hetstat = gs("fs.hetstat"),
fs.test.overall = gs("fs.test.overall"),
fs.test.subgroup = gs("fs.test.subgroup"),
fs.test.effect.subgroup = gs("fs.test.effect.subgroup"),
fs.addline = gs("fs.addline"),
fs.axis = fontsize,
fs.smlab = fontsize,
fs.xlab = fontsize,
fs.lr = fontsize,
ff.heading = "bold",
ff.common = gs("ff.common"),
ff.random = gs("ff.random"),
ff.predict = gs("ff.predict"),
ff.common.labels = gs("ff.common.labels"),
ff.random.labels = gs("ff.random.labels"),
ff.predict.labels = gs("ff.predict.labels"),
ff.study = "plain",
ff.study.labels = ff.study,
ff.hetstat = gs("ff.hetstat"),
ff.test.overall = gs("ff.test.overall"),
ff.test.subgroup = gs("ff.test.subgroup"),
ff.test.effect.subgroup = gs("ff.test.effect.subgroup"),
ff.addline = gs("ff.addline"),
ff.axis = gs("ff.axis"),
ff.smlab = gs("ff.smlab"),
ff.xlab = gs("ff.xlab"),
ff.lr = gs("ff.lr"),
squaresize = 0.8/spacing,
plotwidth = if (layout == "JAMA") "8cm" else "6cm",
colgap = gs("colgap"),
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 = (common | random) & (overall | !is.null(x$subgroup)),
calcwidth.common = calcwidth.pooled,
calcwidth.random = calcwidth.pooled,
calcwidth.predict = gs("calcwidth.predict"),
calcwidth.hetstat = gs("calcwidth.hetstat"),
calcwidth.tests = gs("calcwidth.tests"),
calcwidth.subgroup = gs("calcwidth.subgroup"),
calcwidth.addline = gs("calcwidth.addline"),
just = if (layout == "JAMA") "left" else "right",
just.studlab = gs("just.studlab"),
just.addcols = gs("just.addcols"),
just.addcols.left = just.addcols,
just.addcols.right = just.addcols,
spacing = gs("spacing"),
addrow = gs("addrow"),
addrow.overall = gs("addrow.overall"),
addrow.subgroups = gs("addrow.subgroups"),
addrows.below.overall = gs("addrows.below.overall"),
new = TRUE,
backtransf = x$backtransf,
digits = gs("digits.forest"),
digits.se = gs("digits.se"),
digits.stat = gs("digits.stat"),
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.tau = gs("digits.tau"),
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,
digits.TE = gs("digits.TE.forest"),
digits.addcols = digits,
digits.addcols.right = digits.addcols,
digits.addcols.left = digits.addcols,
scientific.pval = gs("scientific.pval"),
big.mark = gs("big.mark"),
zero.pval = if (layout == "JAMA") FALSE else gs("zero.pval"),
JAMA.pval = if (layout == "JAMA") TRUE else gs("JAMA.pval"),
warn.deprecated = gs("warn.deprecated"),
...
)
```

- x
An object of class

`meta`

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

- common
A logical indicating whether common effect estimate should be plotted.

- 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.common
A character string used in the plot to label the pooled common effect estimate.

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

- lty.common
Line type (pooled common effect estimate).

- lty.random
Line type (pooled random effects estimate).

- col.common
Line colour (pooled common effect estimate).

- col.random
Line colour (pooled random effects estimate).

- text.w.common
A character string used to label weights of common effect model.

- text.w.random
A character string used to label weights of random effects model.

- 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 single logical or logical vector indicating whether / which subgroup results should be shown in forest plot. This argument is useful in a meta-analysis with subgroups if summaries should not be plotted for (some) subgroups.

- subgroup.hetstat
A single logical or logical vector indicating whether / which information on heterogeneity in subgroups should be shown in forest plot. This argument is useful in a meta-analysis with subgroups if heterogeneity statistics should not be printed for (some) subgroups.

- print.subgroup.labels
A logical indicating whether subgroup label should be printed.

- subgroup.name
A character string with a label for the grouping variable.

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

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

- text.common.w
A character string to label the pooled common 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.

- text.predict.w
A character string to label the prediction interval within subgroups, or a character vector of same length as number of subgroups with corresponging labels.

- sort.subgroup
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 measure (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 string "symmetric" to produce symmetric forest plots.

- allstudies
A logical indicating whether studies with inestimable treatment effects should be included in the forest plot.

- 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"`

,`"common"`

, or`"random"`

, can be abbreviated. Plot symbols have the same size for all studies or represent study weights from common 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`

.- lower.equi
A numerical giving the lower limit of equivalence to be plotted as a line in the forest plot. Or a vector to provide several limits, e.g., for large, moderate and small effects. No line is plotted if argument

`lower.equi`

is equal to`NA`

.- upper.equi
A numerical giving the upper limit of equivalence to be plotted as a line in the forest plot. Or a vector to provide several limits, e.g., for small, moderate and large effects. No line is plotted if argument

`upper.equi`

is equal to`NA`

.- lty.equi
Line type (limits of equivalence).

- col.equi
Line colour (limits of equivalence).

- fill.equi
Colour(s) for area between limits of equivalence or more general limits.

- fill.lower.equi
Colour of area between lower limit(s) and reference value. Can be equal to the number of lower limits or the number of limits plus 1 (in this case the the region between minimum and smallest limit is also filled).

- fill.upper.equi
Colour of area between reference value and upper limit(s). Can be equal to the number of upper limits or the number of limits plus 1 (in this case the region between largest limit and maximum is also filled).

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

- rightcols
A character vector specifying (additional) columns to be printed 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).

- label.e
Label to be used for experimental group in table heading.

- label.c
Label to be used for control group in table heading.

- label.e.attach
A character specifying the column name where label

`label.e`

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

`label.c`

should be attached to in table heading.- label.right
Graph label on right side of forest plot.

- label.left
Graph label on left 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.

- lab.NA.weight
A character string to label missing weights.

- 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.common
A character string specifying how to plot treatment effect and confidence interval for common 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).

- type.subgroup.common
A character string specifying how to plot treatment effect and confidence interval for subgroup results (common effect model).

- type.subgroup.random
A character string specifying how to plot treatment effect and confidence interval for subgroup results (random effects model).

- col.study
The colour for individual study results and confidence limits.

- 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.inside
The colour for individual study results and confidence limits if confidence limits are completely within squares.

- col.inside.common
The colour for result of common 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.diamond
The colour of diamonds representing the results for common effect and random effects models.

- col.diamond.common
The colour of diamonds for common 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 common effect and random effects models.

- col.diamond.lines.common
The colour of the outer lines of diamond for common effect estimate.

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

- col.predict
Background colour of prediction interval.

- col.predict.lines
Colour of outer lines of prediction interval.

- col.subgroup
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
Either a logical value indicating whether to print results for heterogeneity measures at all or a character string (see Details).

- overall.hetstat
A logical value indicating whether to print 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.

- resid.hetstat
A logical value indicating whether to print measures of residual heterogeneity in a meta-analysis with subgroups.

- resid.hetlab
Label printed in front of results for residual 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^2\).

- print.tau2.ci
A logical value indicating whether to print the confidence interval of \(\tau^2\).

- print.tau
A logical value indicating whether to print \(\tau\), the square root of the between-study variance \(\tau^2\).

- print.tau.ci
A logical value indicating whether to print the confidence interval of \(\tau\).

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

- LRT
A logical value indicating whether to report Likelihood-Ratio or Wald-type test of heterogeneity for generalized linear mixed models.

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

- test.overall.common
A logical value indicating whether to print results of test for overall effect (common effect model).

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

- label.test.overall.common
Label printed in front of results of test for overall effect (common effect model).

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

- print.stat
A logical value indicating whether z- or t-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.common
A logical value indicating whether to print results of test for subgroup differences (common effect model).

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

- prediction.subgroup
A single logical or logical vector indicating whether / which prediction intervals should be printed for subgroups.

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

- label.test.subgroup.common
Label printed in front of results of test for subgroup differences (common effect model).

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

- test.effect.subgroup
A single logical or logical vector indicating whether / which tests for effect in subgroups should be printed.

- test.effect.subgroup.common
A single logical or logical vector indicating whether / which tests for effect in subgroups should be printed (common effect model).

- test.effect.subgroup.random
A single logical or logical vector indicating whether / which tests for effect in subgroups should be printed (random effects model).

- label.test.effect.subgroup.common
Label printed in front of results of test for effect in subgroups (common effect model).

- label.test.effect.subgroup.random
Label printed in front of results of test for effect in subgroups (random effects model).

- text.addline1
Text for first additional line (below meta-analysis results).

- text.addline2
Text for second additional line (below meta-analysis results).

- header.line
A logical value indicating whether to print a header line or a character string ("both", "below", "").

- fontsize
The size of text (in points), see

`gpar`

.- fontfamily
The font family, see

`gpar`

.- fs.heading
The size of text for column headings, see

`gpar`

.- fs.common
The size of text for results of common 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.common.labels
The size of text for label of common 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.addline
The size of text for additional lines, 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.common
The fontface of text for results of common 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.common.labels
The fontface of text for label of common 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.addline
The fontface of text for additional lines, 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 common effect and random effects model should be considered to calculate width of the column with study labels.

- calcwidth.common
A logical indicating whether text given in arguments

`text.common`

and`text.common.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`

and`text.predict.w`

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.

- calcwidth.addline
A logical indicating whether text for additional lines 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 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.

- addrows.below.overall
A numeric value indicating how many empty rows are printed between meta-analysis results and heterogeneity statistics and test results.

- 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.stat
Minimal number of significant digits for z- or t-statistic for test of overall effect, 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.tau2
Minimal number of significant digits for between-study variance, see

`print.default`

.- digits.tau
Minimal number of significant digits for square root of between-study variance, 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.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.- digits.TE
Minimal number of significant digits for list element 'TE'.

- digits.addcols
A vector or scalar with minimal number of significant digits for additional columns.

- digits.addcols.right
A vector or scalar with minimal number of significant digits for additional columns on right side of forest plot.

- digits.addcols.left
A vector or scalar with minimal number of significant digits for additional columns on left side of forest plot.

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

- zero.pval
A logical specifying whether p-values should be printed with a leading zero.

- JAMA.pval
A logical specifying whether p-values for test of overall effect should be printed according to JAMA reporting standards.

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

- ...
Additional graphical arguments.

Guido Schwarzer guido.schwarzer@uniklinik-freiburg.de

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. In order to
print the forest plot, resize the graphics window and either use
`dev.copy2eps`

or `dev.copy2pdf`

. Another
possibility is to create a file using `pdf`

,
`png`

, or `svg`

and to specify the width and
height of the graphic (see Examples).

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

For an individual study, a square with treatment estimate in the center and confidence interval as line extending either side of the square (

`type.study = "square"`

)For meta-analysis results, a diamond with treatment estimate in the center and right and left side corresponding to lower and upper confidence limits (

`type.common = "diamond"`

,`type.random = "diamond"`

, and`type.subgroup = "diamond"`

)

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"`

.

A prediction interval for treatment effect of a new study (Higgins
et al., 2009) is given in the forest plot if arguments
`prediction`

and `random`

are `TRUE`

. For
graphical presentation of prediction intervals the approach by
Guddat et al. (2012) is used.

Argument `leftcols`

can be used to specify columns which are
printed on the left side of the forest plot. By default, i.e. if
argument `leftcols`

is `NULL`

and `layout = "meta"`

,
and 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

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

`metamean` | `c("studlab", "n", "mean", "sd")` |

`metaprop` | `c("studlab", "event", "n")` |

`metarate` | `c("studlab", "event", "time", "n")` |

`metacum` | `"studlab"` |

`metainf` | `"studlab"` |

For three-level models, the cluster variable is printed next to the
study labels (value `"cluster"`

in argument `leftcols`

).

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
`leftcols`

and `rightcols`

, the first *additional*
variable specified by the user is used as study labels (and labels
for pooled estimates are printed in this column). Additional
variables are any variables not mentioned in the section on
predefined column names below. For example, ```
leftcols =
"studlab"
```

and `leftcols = "study"`

would result in the same
forest plot if the variable `"study"`

was used in the command
to conduct the meta-analysis. If no additional variable is provided
by the user, no study labels will be printed.

Depending on the number of columns printed on the left side of the
forest plot, information on heterogeneity measures or statistical
tests (see below) can be overlapping with the x-axis. Argument
`addrows.below.overall`

can be used to specify the number of
empty rows that are printed between meta-analysis results and
information on heterogeneity measures and statistical tests. By
default, no additional rows are added to the forest plot. If
`addrows.below.overall = NULL`

, the function tries to add a
sufficient number of empty rows to prevent overlapping
text. Another possibility is to manually increase the space between
the columns on the left side (argument `colgap.left`

) or
between the columns on the left side and the forest plot (argument
`colgap.forest.left`

).

Argument `rightcols`

can be used to
specify columns which are printed on the right side of the
forest plot. If argument `rightcols`

is
`FALSE`

, no columns will be printed on the right side. By
default, i.e. if argument `rightcols`

is
`NULL`

and `layout = "meta"`

, the following
* columns* will be printed

Meta-analysis results | Value of argument
rightcols |

No summary | `c("effect", "ci")` |

Only common effect model | `c("effect", "ci", "w.common")` |

Only random effects model | `c("effect", "ci", "w.random")` |

Both models | `c("effect", "ci", "w.common", "w.random")` |

By default, estimated treatment effect and corresponding confidence
interval will be printed. Depending on arguments `common`

and
`random`

, weights of the common effect and/or random effects
model will be given too.

For an object of class `metacum`

or
`metainf`

the following columns will be printed:
`c("effect", "ci", "pval", "tau2", "tau", "I2")`

. This
information corresponds to the printout with
`print.meta`

.

The arguments `leftlabs`

and `rightlabs`

can be used to
specify column headings which are printed on 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: | `studlab` | `TE` | `seTE` | `cluster` | `n.e` | `n.c` |

Label: | "Study" | "TE" | "seTE" | "Cluster" | "Total" | "Total" |

Column: | `n` | `event.e` | `event.c` | `event` | `mean.e` | |

`mean.c` | Label: | "Total" | "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.common` | ||

`w.random` | Label: | `x$level` "%-CI" | effect+ci | "W(common)" |

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`

.

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, the following arguments can be used to print results for various statistical tests:

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, these arguments are `FALSE`

with exception of
tests for subgroup differences which are `TRUE`

. 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)`

.

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),`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).

Arguments `text.common`

, `text.random`

, and
`text.predict`

can be used to change the label to identify
overall results (common effect and random effects model as well as
prediction interval). 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.

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,
https://training.cochrane.org/online-learning/core-software/revman)
is reproduced:

All columns are printed on the left side of the forest plot (see arguments

`leftcols`

and`rightcols`

)Tests for overall effect and subgroup differences are printed (

`test.overall`

,`test.effect.subgroup`

,`test.subgroup`

)Diamonds representing meta-analysis results are printed in black (

`diamond.common`

,`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`

)

If argument `layout = "JAMA"`

(and arguments `leftcols`

and
`rightcols`

are `NULL`

), instructions for authors of the
*Journal of the American Medical Association*, see
https://jamanetwork.com/journals/jama/pages/instructions-for-authors/,
are taken into account:

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 (

`diamond.common`

,`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`

)

Study labels according to JAMA guidelines can be generated using
`labels.meta`

.

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`

)

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

`metabin`

, `metacont`

,
`metagen`

, `forest.metabind`

,
`settings.meta`

, `labels.meta`

```
data(Olkin1995)
m1 <- metabin(ev.exp, n.exp, ev.cont, n.cont,
data = Olkin1995, subset = c(41, 47, 51, 59),
sm = "RR", method = "I",
studlab = paste(author, year))
if (FALSE) {
# Do standard (symmetric) forest plot
#
forest(m1)
}
# Layout of forest plot similar to Review Manager 5
#
# Furthermore, add labels on both sides of forest plot and
# prediction interval
#
forest(m1, layout = "RevMan5", common = FALSE,
label.right = "Favours control", col.label.right = "red",
label.left = "Favours experimental", col.label.left = "green",
prediction = TRUE)
if (FALSE) {
# Create a PDF file forest-m1.pdf with the forest plot
#
pdf("forest-m1.pdf", width = 10, height = 3)
forest(m1)
dev.off()
# Define equivalence limits: 0.75 and 1 / 0.75
#
forest(m1, layout = "RevMan5", common = FALSE,
lower.equi = 0.75, upper.equi = 1 / 0.75, fill.equi = "lightgray")
# Fill areas with beneficial and detrimental effects
#
forest(m1, layout = "RevMan5", common = FALSE,
lower.equi = 0.75, upper.equi = 1 / 0.75,
fill.lower.equi = c("green", "lightgray"),
fill.upper.equi = c("lightgray", "red"))
# Define thresholds for small, moderate and large effects
# and use hcl.colors() to define colours to fill areas
#
thresholds <- c(0.25, 0.5, 0.75)
n.cols <- length(thresholds) + 1
forest(m1, layout = "RevMan5", common = FALSE,
label.right = "Undesirable effect",
label.left = "Desirable effect",
lty.equi = 3, col.equi = "darkgray",
lower.equi = thresholds, upper.equi = 1 / rev(thresholds),
fill.lower.equi =
hcl.colors(n.cols, palette = "Blues 2", alpha = 0.6),
fill.upper.equi =
hcl.colors(n.cols, palette = "Oranges", alpha = 0.6, rev = TRUE))
# Conduct subgroup meta-analysis
#
m2 <- update(m1,
subgroup = ifelse(year < 1987, "Before 1987", "1987 and later"),
print.subgroup.name = FALSE)
# Show summary results for subgroups with at least two studies
#
forest(m2, sortvar = -TE, random = FALSE)
# Show results for all subgroups
#
forest(m2, sortvar = -TE, random = FALSE, subgroup = k.w >= 1)
# Forest plot specifying argument xlim
#
forest(m1, xlim = c(0.01, 10))
# Print results of test for overall effect
#
forest(m1, test.overall.common = TRUE, test.overall.random = TRUE)
# Forest plot with 'classic' layout used in R package meta,
# version < 1.6-0
#
forest(m1, col.square = "black", hetstat = FALSE)
# Change set of columns printed on left side of forest plot
# (resulting in overlapping text)
#
forest(m1, random = FALSE, leftcols = "studlab")
# Use argument 'calcwidth.hetstat' to consider text for heterogeneity
# measures in width of column with study labels
#
forest(m1, random = FALSE, leftcols = "studlab",
calcwidth.hetstat = TRUE)
# Use argument 'addrows.below.overall' to manually add two empty
# rows
#
forest(m1, random = FALSE, leftcols = "studlab", addrows = 2)
# Do not print columns on right side of forest plot
#
forest(m1, rightcols = FALSE)
# Change study label to "Author"
#
forest(m1, random = FALSE, leftlabs = c("Author", NA, NA, NA, NA))
# Just give effect estimate and 95% confidence interval on right
# side of forest plot (in one column)
#
forest(m1, rightcols = c("effect.ci"))
# Just give effect estimate and 95% confidence interval on right
# side of forest plot
#
forest(m1, 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(m1,
leftcols = c("studlab", "n.e", "event.e", "n.c", "event.c"),
label.e.attach = "event.e", label.c.attach = "event.c")
# Specify column labels only for variables 'year' and 'author'
# (and define digits for additional variables)
#
forest(m1,
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(m1,
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(m1,
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(m1,
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.common = "plain", ff.hetstat = "plain")
# Change some colours
#
forest(m1,
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 common effect model
#
forest(m1, sortvar = w.common, random = FALSE)
# Sort by decreasing weight in common effect model
#
forest(m1, sortvar = -w.common, random = FALSE)
# Sort by size of treatment effect
#
forest(m1, sortvar = TE, random = FALSE)
# Sort by size of treatment effect
#
forest(m1, sortvar = -TE, random = FALSE)
# Sort by decreasing year of publication
#
forest(m1, sortvar = -year, random = FALSE)
# Print results of test for subgroup differences (random effects
# model)
#
forest(m2, sortvar = -TE, common = FALSE)
# Print only subgroup results
#
forest(m2, layout = "subgroup")
# Print only subgroup results (and consider text for tests of
# subgroup differences in width of subgroup column)
#
forest(m2, layout = "subgroup", calcwidth.tests = TRUE)
# Print only subgroup results (and consider text for heterogeneity
# in width of subgroup column)
#
forest(m2, layout = "subgroup", calcwidth.hetstat = TRUE)
}
```

Run the code above in your browser using DataLab