Function to create forest plots for a given set of data.
# S3 method for default
forest(x, vi, sei, ci.lb, ci.ub,
annotate=TRUE, showweights=FALSE, header=FALSE,
xlim, alim, olim, ylim, top=3, at, steps=5,
level=95, refline=0, digits=2L, width,
xlab, slab, ilab, ilab.xpos, ilab.pos,
order, subset, transf, atransf, targs, rows,
efac=1, pch=15, psize, plim=c(0.5,1.5), col,
lty, fonts, cex, cex.lab, cex.axis, annosym, …)vector of length k with the observed effect sizes or outcomes.
vector of length k with the corresponding sampling variances.
vector of length k with the corresponding standard errors (note: only one of the two, vi or sei, needs to be specified).
vector of length k with the corresponding lower confidence interval bounds. Not needed if vi or sei is specified. See ‘Details’.
vector of length k with the corresponding upper confidence interval bounds. Not needed if vi or sei is specified. See ‘Details’.
logical to specify whether annotations should be added to the plot (the default is TRUE).
logical to specify whether the annotations should also include inverse variance weights (the default is FALSE).
logical to specify whether column headings should be added to the plot (the default is FALSE). Can also be a character vector to specify the left and right headings.
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.
optional argument to specify observation/outcome limits. If unspecified, no limits are used.
the y-axis 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 positions are specified via the at argument.
numeric value between 0 and 100 to specify the confidence interval level (the default is 95).
numeric value to specify the location of the vertical ‘reference’ line (the default is 0). The line can be suppressed by setting this argument to NA.
integer to specify 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 to specify 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 numeric 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, simple labels are created within the function. To suppress labels, set this argument to NA.
optional vector, matrix, or data frame providing additional information about the studies that should be added to the plot.
numeric vector to specify 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) to specify 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 to specify how the studies should be ordered. Can also be a variable based on which the studies will be ordered. See ‘Details’.
optional (logical or numeric) vector to specify the subset of studies that should be included in the plot.
optional argument to specify a function that should be used to transform the observed outcomes and corresponding confidence interval bounds (e.g., transf=exp; see also transf). If unspecified, no transformation is used.
optional argument to specify 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 to specify the rows (or more generally, the horizontal positions) for plotting the outcomes. Can also be a single value to specify the row (horizontal position) of the first outcome (the remaining outcomes are then plotted below this starting row). If unspecified, the function sets this value automatically.
vertical expansion factor for confidence interval limits and arrows. The default value of 1 should usually work okay. Can also be a vector of two numbers, the first for CI limits, the second for arrows.
plotting symbol to use for the observed outcomes. By default, a filled square is used. See points for other options. Can also be a vector of values.
optional numeric value to specify the point sizes for the observed outcomes. If unspecified, the point sizes are a function of the precision of the estimates. Can also be a vector of values.
numeric vector of length 2 to scale the point sizes (ignored when psize is specified). See ‘Details’.
optional character string to specify the name of a color to use for plotting the observed outcomes ("black" is used by default if not specified). Can also be a vector of color names.
optional character string to specify the line type for the confidence intervals. If unspecified, the function sets this to "solid" by default.
optional character string to specify 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 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 vector of length 3 to change the left bracket, separation, and right bracket symbols for the annotations.
other arguments.
The plot shows the observed effect sizes or outcomes with corresponding confidence intervals. To use the function, one should specify the observed outcomes (via the x argument) together with the corresponding sampling variances (via the vi argument) or with the corresponding standard errors (via the sei argument). Alternatively, one can specify the observed outcomes together with the corresponding confidence interval bounds (via the ci.lb and ci.ub arguments).
With the transf argument, the observed outcomes and corresponding confidence interval bounds can be transformed with some suitable function. For example, when plotting log odds ratios, then 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 other useful transformation functions in the context of a meta-analysis. 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 outcomes,
order="prec": the studies are ordered by their sampling variances.
Alternatively, it is also possible to set order equal to a variable based on which the studies will be ordered (see ‘Examples’).
By default (i.e., when psize is not specified), the size of the points is a function of the precision (i.e., inverse standard error) of the outcomes. This way, more precise estimates are visually more prominent in the plot. By making the point sizes a function of the inverse standard error of the estimates, their area is proportional to the inverse sampling variances, which corresponds to the weights they would receive in a fixed-effects model. However, the point sizes are rescaled so that the smallest point size is plim[1] and the largest point size is plim[2]. As a result, their relative sizes (i.e., areas) no longer exactly correspond to their relative weights in such a model. If exactly relative point sizes are desired, one can set plim[2] to NA, in which case the points are rescaled so that the smallest point size corresponds to plim[1] and all other points are scaled accordingly. As a result, the largest point may be very large. Alternatively, one can set plim[1] to NA, in which case the points are rescaled so that the largest point size corresponds to plim[2] and all other points are scaled accordingly. As a result, the smallest point may be very small and essentially indistinguishable from the confidence interval line. To avoid the latter, one can also set plim[3], which enforces a minimal point size.
Summary estimates can be added to the plot with the addpoly function. See the documentation for that function for examples.
Lewis, S., & Clarke, M. (2001). Forest plots: Trying to see the wood and the trees. British Medical Journal, 322(7300), 1479--1480. https://doi.org/10.1136/bmj.322.7300.1479
Viechtbauer, W. (2010). Conducting meta-analyses in R with the metafor package. Journal of Statistical Software, 36(3), 1--48. https://doi.org/10.18637/jss.v036.i03
# NOT RUN {
### calculate log risk ratios and corresponding sampling variances
dat <- escalc(measure="RR", ai=tpos, bi=tneg, ci=cpos, di=cneg, data=dat.bcg)
### default forest plot of the observed log risk ratios
forest(dat$yi, dat$vi)
### forest plot of the observed risk ratios (transform outcomes)
forest(dat$yi, dat$vi, slab=paste(dat$author, dat$year, sep=", "), transf=exp,
alim=c(0,2), steps=5, xlim=c(-2.5,4), refline=1, cex=.9, header=TRUE)
### forest plot of the observed risk ratios (transformed x-axis)
forest(dat$yi, dat$vi, slab=paste(dat$author, dat$year, sep=", "), atransf=exp,
at=log(c(.05,.25,1,4,20)), xlim=c(-10,8), cex=.9, header=TRUE)
### forest plot of the observed risk ratios with studies ordered by the RRs
forest(dat$yi, dat$vi, slab=paste(dat$author, dat$year, sep=", "), atransf=exp,
at=log(c(.05,.25,1,4,20)), xlim=c(-10,8), cex=.9, header=TRUE, order="obs")
### forest plot of the observed risk ratios with studies ordered by absolute latitude
forest(dat$yi, dat$vi, slab=paste(dat$author, dat$year, sep=", "), atransf=exp,
at=log(c(.05,.25,1,4,20)), xlim=c(-10,8), cex=.9, header=TRUE, order=dat$ablat)
### see also examples for the forest.rma function
# }
Run the code above in your browser using DataLab