metafor (version 0.5-0)

forest.rma: Forest Plots for rma Objects

Description

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

Usage

## S3 method for class 'rma':
forest(x, annotate=TRUE, addfit=TRUE, xlim=NULL, alim=NULL, ylim=NULL, 
       at=NULL, steps=5, level=x$level, digits=2, refline=0, xlab=NULL, 
       slab=NULL, mlab=NULL, ilab=NULL, ilab.xpos=NULL, ilab.pos=NULL, 
       order=NULL, transf=FALSE, atransf=FALSE, targs=NULL, addrows=0, 
       efac=1, pch=15, psize=NULL, col="darkgray", border="darkgray", 
       cex=NULL, cex.lab=NULL, cex.axis=NULL, ...)

Arguments

x

an object of class "rma".

annotate

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

addfit

logical specifying whether the summary estimate or fitted values should be added to the plot. See Details.

xlim

horizontal limits of the plot region. Defaults to NULL, which means that the function tries to set the horizontal plot limits to some sensible values.

alim

the actual x axis limits. Defaults to NULL, which means that the function tries to set the x axis limits to some sensible values.

ylim

the y limits of the plot. Defaults to NULL, which means that the function tries to set the y axis limits to some sensible values.

at

position of the x axis tick marks and corresponding labels. Defaults to NULL, which means that the function tries to set the tick mark positions/labels to some sensible values.

steps

the number of tick marks and corresponding labels for the x axis (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 to take the value from the object).

digits

integer value specifying the number of decimal places to which the tick mark labels and annotations should be rounded (default is 2).

refline

value at which a vertical reference line should be drawn (default is 0). The line can be suppressed by setting this argument to NA.

xlab

title for the x axis (NULL by default, which suppresses the title).

slab

an optional vector with unique labels for the $k$ studies. Defaults to NULL, which means that the labels are either taken from the object (if study labels were specified) or simple labels are created within the function. To suppress labels, s

mlab

an optional character string giving a label to the summary estimate from a fixed- or random-effects model. Defaults to NULL, which means that the label is created within the function.

ilab

an optional vector or matrix of character strings providing additional information about the studies.

ilab.xpos

vector of numerical value(s) specifying the x axis position(s) of the character vector(s) given via ilab.

ilab.pos

integer(s) (either 1, 2, 3, or 4) specifying the alignment of the character vector(s) given via ilab (2 means right, 4 mean left aligned). The default is to center the labels.

order

an optional character string specifying how the studies should be ordered. See Details.

transf

an 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). Defaults to FALSE, which mean

atransf

an optional argument specifying the name of a function that should be used to transform the x axis labels and annotations (e.g., transf=exp). Defaults to FALSE, which means that no transformation is used.

targs

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

addrows

number of extra rows that should be added at the bottom of the forest plot (default is 0).

efac

vertical expansion factor for arrows, confidence interval limits, and the symbol used to denote summary estimates. The default value of 1 should usually work okay.

pch

plotting symbol to use for the observed effect sizes or outcomes. By default, a filled square is used. See points for other options.

psize

an optional vector with point sizes for the observed effect sizes or outcomes. Default is NULL, which means that the point sizes are drawn proportional to the inverse of the sampling variances.

cex

an optional character and symbol expansion factor. If NULL (default), the function tries to set this to a sensible value.

cex.lab

an optional expansion factor for the x axis titel. If NULL (default), the function tries to set this to a sensible value.

cex.axis

an optional expansion factor for x axis labels. If NULL (default), the function tries to set this to a sensible value.

col

character string specifying the name of a color to use for the fitted values ("darkgray" by default).

border

character string specifying the name of a color to use for the border of the fitted values ("darkgray" by default).

...

other arguments.

Details

The plot shows the individual observed effect sizes or outcomes with corresponding confidence intervals. For fixed- and random-effects models, a polygon is added to the bottom of the forest plot, showing the summary estimate based on the model. For models involving moderators, the fitted values are added to the plot. With the transf argument, the observed effect sizes, summary estimate, fitted values, and confidence interval bounds can be transformed with an arbitrary function. For example, if log odds ratios were analyzed, 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. The examples below illustrate the use of these arguments. 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,

Alternatively, it is possible to set order equal to a vector with indices giving the desired order. Additional summary estimates can also be added to the plot with the addpoly function. See the documentation for that function for examples.

See Also

forest.rma, addpoly, addpoly.default, addpoly.rma

Examples

### load BCG vaccine data
data(dat.bcg)

### meta-analysis of the log risk rates using a random-effects model
res <- rma(ai=tpos, bi=tneg, ci=cpos, di=cneg, slab=paste(author, year),
           data=dat.bcg, measure="RR", method="REML")

### several forest plots illustrating the use of various arguments
forest(res, xlab="Log Relative Risk")
forest(res, transf=exp, alim=c(0,6), steps=4, xlim=c(-8,12), 
       xlab="Relative Risk", refline=1)
forest(res, atransf=exp, at=log(c(.05,.25,1,4,12)), xlim=c(-8,6), 
       xlab="Relative Risk (log scale)", order="prec")
forest(res, atransf=exp, at=log(c(.05,1,12)), xlim=c(-34,14), ylim=c(-2.5,15), 
       xlab="Relative Risk (log scale)", order="prec", 
       ilab=cbind(dat.bcg$tpos, dat.bcg$tneg, dat.bcg$cpos, dat.bcg$cneg), 
       ilab.xpos=c(-18,-14,-10,-6), cex=.7)
text(c(-18,-14,-10,-6), y=14.5, c("TB+", "TB-", "TB+", "TB-"), cex=.7)
text(c(-16,-8), y=15.5, c("Vaccinated", "Control"), cex=.7)
text(c(10), y=15, c("Observed [95% CI]"), cex=.7)

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

### forest plots with observed and fitted values
forest(res, xlim=c(-18,10), ylim=c(.5, 15), order="fit", xlab="Log Relative Risk", 
       ilab=dat.bcg$ablat, ilab.xpos=-6)
text(-6, y=15, c("Absolute
Latitude"))