Function to create forest plots for objects of class "rma".

# S3 method for rma
xlim, alim, clim, ylim, top=3, at, steps=5,
level=xlevel, refline=0, digits=2L, width, xlab, slab, mlab, ilab, ilab.xpos, ilab.pos, order, transf, atransf, targs, rows, efac=1, pch=15, psize, col, border, lty, fonts, cex, cex.lab, cex.axis, annosym, …) ## Arguments x an object of class "rma". logical specifying whether annotations should be added to the plot (the default is TRUE). logical specifying whether the summary estimate (for models without moderators) or fitted values (for models with moderators) should be added to the plot. See ‘Details’. logical specifying whether the bounds of the credibility/prediction interval should be added to the plot. See ‘Details’. logical specifying whether the annotations should also include the weights given to the observed effects or outcomes during the model fitting (the default is FALSE). horizontal limits of the plot region. If unspecified, the function tries to set the horizontal plot limits to some sensible values. the actual x-axis limits. If unspecified, the function tries to set the x-axis limits to some sensible values. limits for the confidence/credibility/prediction intervals. If unspecified, no limits are used. the y limits of the plot. If unspecified, the function tries to set the y-axis limits to some sensible values. the amount of space to leave empty at the top of the plot (e.g., for adding headers) (the default is 3 rows). position of the x-axis tick marks and corresponding labels. If unspecified, the function tries to set the tick mark positions/labels to some sensible values. the number of tick marks for the x-axis (the default is 5). Ignored when the user specifies the positions via the at argument. numerical value between 0 and 100 specifying the confidence interval level (the default is to take the value from the object). value at which a vertical ‘reference’ line should be drawn (the default is 0). The line can be suppressed by setting this argument to NA. integer specifying the number of decimal places to which the tick mark labels of the x-axis and the annotations should be rounded (the default is 2L). Can also be a vector of two integers, the first specifying the number of decimal places for the annotations, the second for the x-axis labels. When specifying an integer (e.g., 2L), trailing zeros after the decimal mark are dropped for the x-axis labels. When specifying a numerical value (e.g., 2), trailing zeros are retained. optional integer to manually adjust the width of the columns for the annotations. title for the x-axis. If unspecified, the function tries to set an appropriate axis title. optional vector with labels for the $$k$$ studies. If unspecified, the labels are either taken from the object (if study labels were specified) or simple labels are created within the function. To suppress labels, set this argument to NA. optional character string giving a label to the summary estimate from a fixed- or random-effects model. If unspecified, the label is created within the function. optional vector, matrix, or data frame providing additional information about the studies that should be added to the plot. vector of numerical value(s) specifying the x-axis position(s) of the variable(s) given via ilab (must be specified if ilab is specified). integer(s) (either 1, 2, 3, or 4) specifying the alignment of the vector(s) given via ilab (2 means right, 4 mean left aligned). If unspecified, the default is to center the labels. optional character string specifying how the studies should be ordered. See ‘Details’. optional argument specifying the name of a function that should be used to transform the observed effect sizes, summary estimates, fitted values, and confidence interval bounds (e.g., transf=exp; see also transf). If unspecified, no transformation is used. optional argument specifying the name of a function that should be used to transform the x-axis labels and annotations (e.g., atransf=exp; see also transf). If unspecified, no transformation is used. optional arguments needed by the function specified via transf or atransf. optional vector specifying the rows (or more generally, the horizontal positions) for plotting the outcomes. If unspecified, the function sets this value automatically. Can also be a single value specifying the row (horizontal position) of the first outcome (the remaining outcomes are then plotted below this starting row). vertical expansion factor for confidence interval limits, arrows, and the symbol used to denote summary estimates. The default value of 1 should usually work okay. Can also be a vector of two numbers, the first for CI limits and arrows, the second for summary estimates. Can also be a vector of three numbers, the first for CI limits, the second for arrows, the third for summary estimates. plotting symbol to use for the observed effect sizes or outcomes. By default, a filled square is used. See points for other options. Can also be a vector of values. optional vector with point sizes for the observed effect sizes or outcomes. If unspecified, the point sizes are an inverse function of the model weights. optional character and symbol expansion factor. If unspecified, the function tries to set this to a sensible value. optional expansion factor for the x-axis title. If unspecified, the function tries to set this to a sensible value. optional expansion factor for the x-axis labels. If unspecified, the function tries to set this to a sensible value. optional character string specifying the name of a color to use for the summary polygon or fitted values. If unspecified, the function sets a default color. optional character string specifying the name of a color to use for the border of the summary polygon or fitted values. If unspecified, the function sets a default color. optional character string specifying the line type for the confidence intervals (if unspecified, the function sets this to "solid" by default). optional character string specifying the font to use for the study labels, annotations, and the extra information (if specified via ilab). If unspecified, the default font is used. optional vector of length 3 to change the left bracket, separation, and right bracket symbols for the annotations. other arguments. ## Details The plot shows the individual observed effect sizes or outcomes with corresponding confidence intervals. For fixed- and random-effects models (i.e., for models without moderators), a polygon is added to the bottom of the forest plot, showing the summary estimate based on the model (with the outer edges of the polygon indicating the confidence interval limits). The col and border arguments can be used to adjust the (border) color of the polygon. For random-effects models and if addcred=TRUE, a dotted line indicates the (approximate) bounds of the credibility/credible or prediction interval (the interval indicates where level % of the true effects are expected to fall) (Riley et al., 2011). For random-effects models of class "rma.mv" (see rma.mv) with multiple $$\tau^2$$ values, the addcred argument can be used to specify for which level of the inner factor the credibility/prediction intervals should be provided (since the credibility/prediction intervals differ depending on the $$\tau^2$$ value). If the model should also contain multiple multiple $$\gamma^2$$ values, the addcred argument should then be of length 2 to specify the levels of both inner factors. For models involving moderators, the fitted value for each study is added as a polygon to the plot. By default, the width of the polygons corresponds to the confidence interval limits for the fitted values. By setting addcred=TRUE, the width reflects the credibility/prediction interval limits. Again, the col and border arguments can be used to adjust the (border) color of the polygons. These polygons can be suppressed by setting addfit=FALSE. With the transf argument, the observed effect sizes or outcomes, summary estimate, fitted values, confidence interval bounds, and credibility/prediction interval bounds can be transformed with some suitable function. For example, when plotting log odds ratios, one could use transf=exp to obtain a forest plot showing the odds ratios. Alternatively, one can use the atransf argument to transform the x-axis labels and annotations (e.g., atransf=exp). See also transf for some transformation functions useful for meta-analyses. The examples below illustrate the use of these arguments. By default, the studies are ordered from top to bottom (i.e., the first study in the dataset will be placed in row $$k$$, the second study in row $$k-1$$, and so on, until the last study, which is placed in the first row). The studies can be reordered with the order argument: • order="obs": the studies are ordered by the observed effect sizes, • order="fit": the studies are ordered by the fitted values, • order="prec": the studies are ordered by their sampling variances, • order="resid": the studies are ordered by the size of their residuals, • order="rstandard": the studies are ordered by the size of their standardized residuals, • order="abs.resid": the studies are ordered by the size of their absolute residuals, • order="abs.rstandard": the studies are ordered by the size of their absolute standardized residuals. Alternatively, it is also possible to set order equal to a vector with indices specifying the desired order (see examples below). Additional summary estimates can also be added to the plot with the addpoly function. See the documentation for that function for examples. ## Note The function tries to set some sensible values for the optional arguments, but it may be necessary to tweak these in certain circumstances. The function actually returns some information about the chosen defaults invisibly. Printing this information is useful as a starting point to make adjustments to the plot (see examples below). If the number of studies is quite large, the labels, annotations, and symbols may become quite small and impossible to read. Stretching the plot window vertically may then provide a more readable figure (one should call the function again after adjusting the window size, so that the label/symbol sizes can be properly adjusted). Also, the cex, cex.lab, and cex.axis arguments are then useful to adjust the symbol and text sizes. If the horizontal plot and/or x-axis limits are set by the user, then the horizontal plot limits (xlim) must be at least as wide as the x-axis limits (alim). This restriction is enforced inside the function. If the outcome measure used for creating the plot is bounded (e.g., correlations are bounded between -1 and 1, proportions are bounded between 0 and 1), one can use the clim argument to enforce those limits (confidence/credibility/prediction intervals cannot exceed those bounds then). The models without moderators, the col argument can also be a vector of two elements, the first for specifying the color of the summary polygon, the second for specifying the color of the line for the credibility/prediction interval. The lty argument can also be a vector of up to three elements, the first for specifying the line type of the individual CIs ("solid" by default), the second for the line type of the credibility/prediction interval ("dotted" by default), the third for the line type of the horizontal lines that are automatically added to the plot ("solid" by default; set to "blank" to remove them). ## References Lewis, S., & Clarke, M. (2001). Forest plots: Trying to see the wood and the trees. British Medical Journal, 322, 1479--1480. Riley, R. D., Higgins, J. P. T., & Deeks, J. J. (2011). Interpretation of random effects meta-analyses. British Medical Journal, 342, d549. Viechtbauer, W. (2010). Conducting meta-analyses in R with the metafor package. Journal of Statistical Software, 36(3), 1--48. http://www.jstatsoft.org/v36/i03/. ## See also forest, forest.default, addpoly ## Examples ### meta-analysis of the log risk ratios using a random-effects model res <- rma(measure="RR", ai=tpos, bi=tneg, ci=cpos, di=cneg, data=dat.bcg, slab=paste(author, year, sep=", ")) ### default forest plot of the log risk ratios and summary estimate forest(res) ### summary estimate in row -1; studies in rows k=13 through 1; horizontal ### lines in rows 0 and k+1; and two extra lines of space at the top for ### headings or other annotations op <- par(xpd=TRUE) text(x=-8.5, y=-1:16, -1:16, pos=4, cex=.5)par(op) ### can also inspect defaults chosen defaults <- forest(res)defaults#>xlim
#> [1] -8.00  7.26
#>
#> $alim #> [1] -3 2 #> #>$at
#> [1] -3 -2 -1  0  1  2
#>
#> $ylim #> [1] -1.5 16.0 #> #>$rows
#>  [1]  1  2  3  4  5  6  7  8  9 10 11 12 13
#>
#> $cex #> [1] 1 #> #>$cex.lab
#> [1] 1
#>
#> $cex.axis #> [1] 1 #> ### several forest plots illustrating the use of various arguments forest(res, cex=.8)forest(res, cex=.8, addcred=TRUE)forest(res, cex=.8, alim=c(-3,3))forest(res, cex=.8, order="prec", alim=c(-3,3))forest(res, cex=.8, order=order(dat.bcg$ablat), addcred=TRUE)
### adjust xlim values to see how that changes the plot
forest(res)par("usr")[1:2] ### this shows what xlim values were chosen by default#> [1] -8.00  7.26forest(res, xlim=c(-16,14))forest(res, xlim=c(-18,10))forest(res, xlim=c(-10,10))
### illustrate transf argument
forest(res, transf=exp, at=c(0,1,2,4,6), xlim=c(-8,12), cex=.8, refline=1)
### illustrate atransf argument
forest(res, atransf=exp, at=log(c(.05,.25,1,4,20)), xlim=c(-8,7), cex=.8)
### showweights argument
forest(res, atransf=exp, at=log(c(.05,.25,1,4,20)), xlim=c(-8,8),
order="prec", showweights=TRUE, cex=.8)
### forest plot with extra annotations
### note: may need to widen plotting device to avoid overlapping text
forest(res, atransf=exp, at=log(c(.05, .25, 1, 4)), xlim=c(-16,6),
ilab=cbind(dat.bcg$tpos, dat.bcg$tneg, dat.bcg$cpos, dat.bcg$cneg),
ilab.xpos=c(-9.5,-8,-6,-4.5), cex=.75)op <- par(cex=.75, font=2)
text(c(-9.5,-8,-6,-4.5), 15, c("TB+", "TB-", "TB+", "TB-"))text(c(-8.75,-5.25),     16, c("Vaccinated", "Control"))text(-16,                15, "Author(s) and Year",   pos=4)text(6,                  15, "Risk Ratio [95% CI]", pos=2)par(op)

### mixed-effects model with absolute latitude in the model
res <- rma(measure="RR", ai=tpos, bi=tneg, ci=cpos, di=cneg, mods = ~ ablat,
data=dat.bcg, slab=paste(author, year, sep=", "))

### forest plot with observed and fitted values
forest(res, xlim=c(-9,5), order="fit", cex=.8, ilab=dat.bcg$ablat, ilab.xpos=-3.5, atransf=exp, at=log(c(.05,.25,1,4)))op <- par(font=2) text(-9, 15, "Author(s) and Year", pos=4, cex=.8)text( 5, 15, "Observed RR [95% CI]", pos=2, cex=.8)text(-3.5, 15, "Latitude", cex=.8)par(op) ### meta-analysis of the log risk ratios using a random-effects model res <- rma(measure="RR", ai=tpos, bi=tneg, ci=cpos, di=cneg, data=dat.bcg, slab=paste(author, year, sep=", ")) ### for more complicated plots, the ylim and rows arguments may be useful forest(res)forest(res, ylim=c(-1.5, 16)) ### the defaultforest(res, ylim=c(-1.5, 20)) ### extra space in plotforest(res, ylim=c(-1.5, 20), rows=c(17:15, 12:6, 3:1)) ### set positions ### forest plot with subgrouping of studies ### note: may need to widen plotting device to avoid overlapping text forest(res, xlim=c(-16, 6), at=log(c(.05, .25, 1, 4)), atransf=exp, ilab=cbind(dat.bcg$tpos, dat.bcg$tneg, dat.bcg$cpos, dat.bcg$cneg), ilab.xpos=c(-9.5,-8,-6,-4.5), cex=.75, ylim=c(-1, 21), order=order(dat.bcg$alloc), rows=c(1:2,5:11,14:17))op <- par(cex=.75, font=4)
text(-16, c(18,12,3), c("Systematic Allocation", "Random Allocation",
"Alternate Allocation"), pos=4)par(cex=.75, font=2)
text(c(-9.5,-8,-6,-4.5), 20, c("TB+", "TB-", "TB+", "TB-"))text(c(-8.75,-5.25),     21, c("Vaccinated", "Control"))text(-16,                20, "Author(s) and Year",   pos=4)text(6,                  20, "Risk Ratio [95% CI]", pos=2)par(op)

forest(res, xlim=c(-1,2), alim=c(0,1), psize=1, refline=coef(res), clim=c(0,1))text(-1, 16, "Author(s)", pos=4)text( 2, 16, "Proportion [95% CI]", pos=2)