meta (version 0.9-17)

forest: Forest plot (new plot function for objects of class meta)

Description

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

Usage

forest(x, byvar, bylab, print.byvar=TRUE, sortvar, studlab=TRUE,
       level=x$level, level.comb=x$level.comb,
       comb.fixed=FALSE, comb.random=FALSE, overall=comb.fixed|comb.random,
       text.fixed="Fixed effect model", text.random="Random effects model",
       lty.fixed=2, lty.random=3, xlab=NULL, xlab.pos=ref, xlim,
       allstudies=TRUE,
       weight=ifelse(comb.random & !comb.fixed, "random", "fixed"),
       ref=ifelse(x$sm %in% c("RR", "OR", "HR"), 1, 0),
       leftcols=NULL, rightcols=NULL,
       leftlabs=NULL, rightlabs=NULL,
       lab.e="Experimental", lab.c="Control",
       lab.e.attach.to.col=NULL, lab.c.attach.to.col=NULL,
       lwd=1,
       at=NULL, label=TRUE,
       fontsize=12, boxsize=0.8,
       plotwidth=unit(6, "cm"), colgap=unit(2, "mm"),
       col.i="black", col.by="darkgray")

Arguments

x

An object of class meta.

byvar

An optional vector containing grouping information (must be of same length as x$TE). Parameter byvar can not be used if x is an object of class metacum or metainf.

bylab

A character string with a label for the grouping variable.

print.byvar

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

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

level

The level used to calculate confidence intervals for individual studies.

level.comb

The level used to calculate confidence intervals for pooled estimates.

comb.fixed

A logical indicating whether fixed effect estimate should be plotted.

comb.random

A logical indicating whether random effects estimate should be plotted.

overall

A logical indicating whether overall summaries should be plotted. This parameter is useful in combination with the parameter byvar if summaries should only be plotted on group level.

text.fixed

A character string used in the plot to label the pooled fixed effect estimate.

text.random

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

lty.fixed

Line type (pooled fixed effect estimate).

lty.random

Line type (pooled random effects estimate).

xlab

A label for the x axis.

xlab.pos

A numeric specifying the center of the label on the x axis.

xlim

The x limits (min,max) of the plot.

allstudies

A logical indicating whether studies with inestimable treatment effects should be plotted.

weight

A character string indicating which type of plotting symbols is to be used for individual treatment estimates. One of "same", "fixed", or "random", can be abbreviated. Plot symbols have the same size for

ref

A numerical giving the reference value to be plotted as a line in the forest plot. No reference line is plotted if parameter ref is equal to NA.

leftcols

A character vector specifying (additional) columns to be plotted on the left side of the forest plot (see Details).

rightcols

A character vector specifying (additional) columns to be plotted on the right side of the forest plot (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).

lab.e

Label to be used for experimental group in table heading.

lab.c

Label to be used for control group in table heading.

lab.e.attach.to.col

A character specifying the column name where label lab.e should be attached to in table heading.

lab.c.attach.to.col

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

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.

fontsize

The size of text (in points), see gpar.

boxsize

A numeric used to increase or decrease the size of boxes in the forest plot.

plotwidth

A unit object specifying width of the forest plot.

colgap

A unit object specifying gap between columns printed on left and right side of forest plot.

col.i

The colour for individual study results and confidence limits.

col.by

A character specifying colour to print information on subgroups.

Details

A forest plot, also called confidence interval plot, is drawn in the active graphics window. Sub-group analyses are conducted and displayed in the plot if byvar is not missing.

The forest function is based on the grid graphics system. Therefore, to plot a new figure in an existing graphics window, one has to use the grid.newpage function. In order to print the forest plot, (i) resize the graphics window, (ii) either use dev.copy2eps or dev.copy2pdf. For basic forest plots, the plot.meta function can be used. The parameters leftcols and rightcols can be used to specify columns which are plotted on the left and right side of the forest plot, respectively. If these parameters are NULL, the following default columns will be plotted.

Parameter rightcols: (i) estimated treatment effect with level-confidence interval, (ii) in addition, weights of the fixed and/or random effects model will be given, if comb.fixed=TRUE and/or comb.random=TRUE. For an object of class metacum or metainf only the estimated treatment effect with level-confidence interval are plotted. Parameter leftcols: (i) leftcols=c("studlab", "event.e", "n.e", "event.c", "n.c") for an object of class metabin, (ii) leftcols=c("studlab", "n.e", "mean.e", "sd.e", "n.c", "mean.c", "sd.c") for an object of class metacont, (iii) leftcols=c("studlab", "TE", "seTE") for an object of class metagen, (iv) leftcols=c("studlab", "event", "n") for an object of class metaprop, (v) leftcols=c("studlab") for an object of class metacum or metainf.

The parameters leftlabs and rightlabs can be used to specify column headings which are plotted on left and right side of the forest plot, respectively. For certain columns predefined labels exist. If the parameters leftlabs and rightlabs are NULL, the following default labels will be used: for columns c("studlab", "TE", "seTE", "n.e", "n.c", "event.e", "event.c", "mean.e", "mean.c", "sd.e", "sd.c", "effect", "ci", "w.fixed", "w.random") the labels c("Study", "TE", "seTE", "Total", "Total", "Events", "Events", "Mean", "Mean", "SD", "SD", summary measure, level for confidence interval, "W(fixed)", "W(random)"). For additional columns the column name will be used as label. It is possible to only provide labels for new columns (see Examples).

See Also

plot.meta, metabin, metacont, metagen

Examples

data(Olkin95)
meta1 <- metabin(event.e, n.e, event.c, n.c,
                 data=Olkin95, subset=c(41,47,51,59),
                 sm="RR", meth="I",
                 studlab=paste(author, year))


grid.newpage()
##
## Do forest plot
##
forest(meta1, comb.fixed=TRUE, comb.random=TRUE)


grid.newpage()
##
## Change set of columns printed on left side
## of forest plot
##
forest(meta1, comb.fixed=TRUE, comb.random=FALSE,
       leftcols="studlab")


grid.newpage()
##
## 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(meta1,
       leftcols=c("studlab", "n.e", "event.e", "n.c", "event.c"),
       lab.e.attach.to.col="event.e",
       lab.c.attach.to.col="event.c",
       comb.fixed=TRUE)


Olkin95$studlab <- paste(Olkin95$author, Olkin95$year)
##
## Add variables 'year' and 'author' to meta-analysis object
##
meta1$year <- addvar(meta1, Olkin95, "year")
meta1$author <- addvar(meta1, Olkin95, "author")

grid.newpage()
##
## Specify column labels only for newly created variables
## 'year' and 'author'
##
forest(meta1,
       leftcols=c("studlab", "event.e", "n.e", "event.c", "n.c",
                  "author", "year"),
       leftlabs=c("Author", "Year of Publ"),
       comb.fixed=TRUE)