Become an expert in R — Interactive courses, Cheat Sheets, certificates and more!
Get Started for Free

forest.default

Forest Plots (Default Method)


Description

Function to create forest plots for a given set of data.

Usage

## Default S3 method:
forest(x, vi, sei, ci.lb, ci.ub,
       annotate=TRUE, showweights=FALSE, header=FALSE,
       xlim, alim, clim, ylim, top=3, at, steps=5,
       level=95, refline=0, digits=2L, width,
       xlab, slab, ilab, ilab.xpos, ilab.pos,
       subset, transf, atransf, targs, rows,
       efac=1, pch=15, psize, col, lty, fonts,
       cex, cex.lab, cex.axis, annosym, ...)

Arguments

x

vector of length k with the observed effect sizes or outcomes.

vi

vector of length k with the corresponding sampling variances.

sei

vector of length k with the corresponding standard errors (note: only one of the two, vi or sei, needs to be specified).

ci.lb

vector of length k with the corresponding lower confidence interval bounds. Not needed if vi or sei is specified. See ‘Details’.

ci.ub

vector of length k with the corresponding upper confidence interval bounds. Not needed if vi or sei is specified. See ‘Details’.

annotate

logical specifying whether annotations should be added to the plot (the default is TRUE).

showweights

logical specifying whether the annotations should also include inverse variance weights (the default is FALSE).

header

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

xlim

horizontal limits of the plot region. If unspecified, the function tries to set the horizontal plot limits to some sensible values.

alim

the actual x-axis limits. If unspecified, the function tries to set the x-axis limits to some sensible values.

clim

limits for the confidence intervals. If unspecified, no limits are used.

ylim

the y limits of the plot. If unspecified, the function tries to set the y-axis limits to some sensible values.

top

the amount of space to leave empty at the top of the plot (e.g., for adding headers) (the default is 3 rows).

at

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.

steps

the number of tick marks for the x-axis (the default is 5). Ignored when the user specifies the positions via the at argument.

level

numerical value between 0 and 100 specifying the confidence interval level (the default is 95).

refline

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.

digits

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.

width

optional integer to manually adjust the width of the columns for the annotations.

xlab

title for the x-axis. If unspecified, the function tries to set an appropriate axis title.

slab

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.

ilab

optional vector, matrix, or data frame providing additional information about the studies that should be added to the plot.

ilab.xpos

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

ilab.pos

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.

subset

optional (logical or numeric) vector indicating the subset of studies that should be included in the plot. Note that this argument can also be used for reordering the studies.

transf

optional argument specifying the name of a function that should be used to transform the observed effect sizes or outcomes and corresponding confidence interval bounds (e.g., transf=exp; see also transf). If unspecified, no transformation is used.

atransf

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.

targs

optional arguments needed by the function specified via transf or atransf.

rows

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

efac

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.

pch

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.

psize

optional vector with point sizes for the observed effect sizes or outcomes. If unspecified, the point sizes are an inverse function of the precision of the estimates.

col

optional character string specifying the name of a color to use for plotting ("black" is used by default if not specified). Can also be a vector of color names.

lty

optional character string specifying the line type for the confidence intervals (if unspecified, the function sets this to "solid" by default).

fonts

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.

cex

optional character and symbol expansion factor. If unspecified, the function tries to set this to a sensible value.

cex.lab

optional expansion factor for the x-axis title. If unspecified, the function tries to set this to a sensible value.

cex.axis

optional expansion factor for the x-axis labels. If unspecified, the function tries to set this to a sensible value.

annosym

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. To use the function, one should specify the observed effect sizes or 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 effect sizes or outcomes together with the corresponding confidence interval bounds (via the ci.lb and ci.ub arguments).

With the transf argument, the observed effect sizes or 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 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 subset argument (by specifying a vector with indices with the desired order).

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.

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 intervals cannot exceed those bounds then).

The lty argument can also be a vector of two elements, the first for specifying the line type of the individual CIs ("solid" by default), the second for the line type of the horizontal line that is automatically added to the plot ("solid" by default; set to "blank" to remove it).

Author(s)

References

Lewis, S., & Clarke, M. (2001). Forest plots: Trying to see the wood and the trees. British Medical Journal, 322, 1479–1480.

Viechtbauer, W. (2010). Conducting meta-analyses in R with the metafor package. Journal of Statistical Software, 36(3), 1–48. https://www.jstatsoft.org/v036/i03.

See Also

Examples

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

### forest plot of the observed risk ratios
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)

### 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, subset=order(dat$yi))

### see also examples for the forest.rma function

metafor

Meta-Analysis Package for R

v2.4-0
GPL (>= 2)
Authors
Wolfgang Viechtbauer [aut, cre] (<https://orcid.org/0000-0003-3463-4063>)
Initial release
2020-03-19

We don't support your browser anymore

Please choose more modern alternatives, such as Google Chrome or Mozilla Firefox.