meta包forest函数源代码
| forest | R Documentation |
Forest plot to display the result of a meta-analysis
Description
Draws a forest plot in the active graphics window (using grid graphics system).
Usage
forest(x, ...)## S3 method for class 'meta'forest(x, sortvar, studlab=TRUE, comb.fixed=x$comb.fixed, comb.random=x$comb.random, overall=TRUE, text.fixed=if (x$level!=x$level.comb) paste("Fixed effect model (", round(x$level.comb*100), "%-CI)", sep="") else "Fixed effect model", text.random=if (x$level!=x$level.comb) paste("Random effects model (", round(x$level.comb*100), "%-CI)", sep="") else "Random effects model", lty.fixed=2, lty.random=3, prediction=x$prediction, text.predict=if (!(length(x$level.predict)==0) && x$level!=x$level.predict) paste("Prediction interval (", round(x$level.predict*100), "%)", sep="") else "Prediction interval", bylab=x$bylab, print.byvar=x$print.byvar, text.fixed.w=text.fixed, text.random.w=text.random, bysort=FALSE, pooled.totals=comb.fixed|comb.random, pooled.events=FALSE, xlab="", xlab.pos=ref, smlab=NULL, smlab.pos=ref, xlim="symmetric", allstudies=TRUE, weight, pscale=1, ref=ifelse(backtransf & is.relative.effect(x$sm), 1, 0), layout="meta", leftcols=NULL, rightcols=NULL, leftlabs=NULL, rightlabs=NULL, lab.e=x$label.e, lab.c=x$label.c, lab.e.attach.to.col=NULL, lab.c.attach.to.col=NULL, label.right=x$label.right, label.left=x$label.left, lab.NA=".", lab.NA.effect="", lwd=1, at=NULL, label=TRUE, col.i="black", col.i.inside.square="white", col.square="gray", col.square.lines=col.square, col.diamond="gray", col.diamond.fixed=col.diamond, col.diamond.random=col.diamond, col.diamond.lines="black", col.diamond.fixed.lines=col.diamond.lines, col.diamond.random.lines=col.diamond.lines, col.predict="red", col.predict.lines="black", col.by="darkgray", print.I2=comb.fixed|comb.random, print.I2.ci=FALSE, print.tau2=comb.fixed|comb.random, print.Q=FALSE, print.pval.Q=comb.fixed|comb.random, hetstat=print.I2|print.tau2|print.Q|print.pval.Q, overall.hetstat=overall&hetstat, hetlab="Heterogeneity: ", text.I2 = "I-squared", text.tau2 = "tau-squared", test.overall=.settings$test.overall, test.overall.fixed=comb.fixed&overall&test.overall, test.overall.random=comb.random&overall&test.overall, label.test.overall.fixed=paste("Test for overall effect", if (comb.fixed & comb.random) " (fixed effect)", ": ", sep=""), label.test.overall.random=paste("Test for overall effect", if (comb.fixed & comb.random) " (random effects)", ": ", sep=""), test.subgroup=.settings$test.subgroup, test.subgroup.fixed=if (missing(test.subgroup)) FALSE else test.subgroup, test.subgroup.random=if (missing(test.subgroup)) !is.null(x$byvar)& comb.random&test.subgroup else test.subgroup, print.Q.subgroup=print.Q, label.test.subgroup.fixed="Test for subgroup differences (fixed effect): ", label.test.subgroup.random=paste("Test for subgroup differences", if (test.subgroup.fixed | comb.fixed) " (random effects)", ": ", sep=""), fontsize=12, fs.heading=fontsize, fs.fixed=fontsize, fs.random=fs.fixed, fs.predict=fs.fixed, fs.study=fontsize, fs.fixed.labels=fs.fixed, fs.random.labels=fs.random, fs.predict.labels=fs.predict, fs.study.labels=fs.study, fs.hetstat=fontsize-2, fs.test.overall=fs.hetstat, fs.test.subgroup=fs.hetstat, fs.axis=fontsize, fs.smlab=fontsize, fs.xlab=fontsize, fs.lr=fontsize, ff.heading="bold", ff.fixed="bold", ff.random=ff.fixed, ff.predict=ff.fixed, ff.study="plain", ff.fixed.labels=ff.fixed, ff.random.labels=ff.random, ff.predict.labels=ff.predict, ff.study.labels=ff.study, ff.hetstat="bold.italic", ff.test.overall=ff.hetstat, ff.test.subgroup=ff.hetstat, ff.axis="plain", ff.smlab="bold", ff.xlab="plain", ff.lr="plain", # squaresize=0.8, # plotwidth=grid::unit(6, "cm"), colgap=grid::unit(2, "mm"), colgap.left=colgap, colgap.right=colgap, colgap.forest=colgap, colgap.forest.left=colgap.forest, colgap.forest.right=colgap.forest, # just="right", just.studlab="left", just.addcols="center", # addspace=TRUE, # new=TRUE, # backtransf=x$backtransf, digits = .settings$digits.forest, digits.se = .settings$digits.se, digits.pval = .settings$digits.pval, digits.pval.Q = .settings$digits.pval.Q, digits.Q = .settings$digits.Q, digits.tau2 = .settings$digits.tau2, digits.I2 = .settings$digits.I2, digits.weight = .settings$digits.weight, ...)
Arguments
x |
An object of class |
sortvar |
An optional vector used to sort the individual studies (must be of same length as |
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 |
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 argument is useful in combination with the argument |
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). |
prediction |
A logical indicating whether a prediction interval should be printed. |
level.predict |
The level used to calculate prediction interval for a new study. |
text.predict |
A character string used in the plot to label the prediction interval. |
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. |
text.fixed.w |
A character string to label the pooled fixed effect estimate within subgroups, or a character vector of same length as number of subgroups with corresponging labels. |
text.random.w |
A character string to label the pooled random effect estimate within subgroups, or a character vector of same length as number of subgroups with corresponging labels. |
bysort |
A logical indicating whether groups should be ordered alphabetically. |
pooled.totals |
A logical indicating whether total number of observations should be given in the figure. |
pooled.events |
A logical indicating whether total number of events should be given in the figure. |
xlab |
A label for the x-axis. |
xlab.pos |
A numeric specifying the center of the label on the x-axis. |
smlab |
A label for the summary measurex (printed at top of figure). |
smlab.pos |
A numeric specifying the center of the label for the summary measure. |
xlim |
The x limits (min,max) of the plot, or the character "s" to produce symmetric forest plots. |
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 missing (see Details), |
pscale |
A numeric giving scaling factor for probabilities for objects of class |
ref |
A numerical giving the reference value to be plotted as a line in the forest plot. No reference line is plotted if argument |
layout |
A character string specifying the layout of the forest plot (see Details). |
leftcols |
A character vector specifying (additional) columns to be plotted on the left side of the forest plot or a logical value (see Details). |
rightcols |
A character vector specifying (additional) columns to be plotted on the right side of the forest plot or a logical value (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.c.attach.to.col |
A character specifying the column name where label |
label.left |
Graph label on left side of forest plot. |
label.right |
Graph label on right side of forest plot. |
lab.NA |
A character string to label missing values. |
lab.NA.effect |
A character string to label missing values in individual treatment estimates and confidence intervals. |
lwd |
The line width, see |
at |
The points at which tick-marks are to be drawn, see |
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 |
col.i |
The colour for individual study results and confidence limits. |
col.i.inside.square |
The colour for individual study results and confidence limits if confidence limits are completely within squares. |
col.square |
The colour for squares reflecting study's weight in the meta-analysis. |
col.square.lines |
The colour for the outer lines of squares reflecting study's weight in the meta-analysis. |
col.diamond |
The colour of diamonds representing the results for fixed effect and random effects models. |
col.diamond.fixed |
The colour of diamonds for fixed effect estimates. |
col.diamond.random |
The colour of diamonds for random effects estimates. |
col.diamond.lines |
The colour of the outer lines of diamonds representing the results for fixed effect and random effects models. |
col.diamond.fixed.lines |
The colour of the outer lines of diamond for fixed effect estimate. |
col.diamond.random.lines |
The colour of the outer lines of diamond for random effects estimate. |
col.predict |
Background colour of prediction interval. |
col.predict.lines |
Colour of outer lines of prediction interval. |
col.by |
The colour to print information on subgroups. |
print.I2 |
A logical value indicating whether to print the value of the I-squared statistic. |
print.I2.ci |
A logical value indicating whether to print the confidence interval of the I-squared statistic. |
print.tau2 |
A logical value indicating whether to print the value of the between-study variance tau-squared. |
print.Q |
A logical value indicating whether to print the value of the heterogeneity statistic Q. |
print.pval.Q |
A logical value indicating whether to print the p-value of the heterogeneity statistic Q. |
hetstat |
A logical value indicating whether to print results for heterogeneity measures at all. |
overall.hetstat |
A logical value indicating whether to print results for heterogeneity measures for overall treatment comparisons. This argument is useful in combination with subgroup analyses (list object |
hetlab |
Label printed in front of results for heterogeneity measures. |
text.I2 |
Label for I-squared statistic. |
text.tau2 |
Label for between-study variance tau-squared. |
test.overall |
A logical value indicating whether to print results of test for overall effect. |
test.overall.fixed |
A logical value indicating whether to print results of test for overall effect (based on fixed effect model). |
test.overall.random |
A logical value indicating whether to print results of test for overall effect (based on random effects model). |
label.test.overall.fixed |
Label printed in front of results of test for overall effect (based on fixed effect model). |
label.test.overall.random |
Label printed in front of results of test for overall effect (based on random effects model). |
test.subgroup |
A logical value indicating whether to print results of test for subgroup differences. |
test.subgroup.fixed |
A logical value indicating whether to print results of test for subgroup differences (based on fixed effect model). |
test.subgroup.random |
A logical value indicating whether to print results of test for subgroup differences (based on random effects model). |
label.test.subgroup.fixed |
Label printed in front of results of test for subgroup differences (based on fixed effect model). |
label.test.subgroup.random |
Label printed in front of results of test for subgroup differences (based on random effects model). |
print.Q.subgroup |
A logical value indicating whether to print the value of the heterogeneity statistic Q (test for subgroup differences). |
fontsize |
The size of text (in points), see |
fs.heading |
The size of text for column headings, see |
fs.fixed |
The size of text for results of fixed effect model, see |
fs.random |
The size of text for results of random effects model, see |
fs.predict |
The size of text for results of prediction interval, see |
fs.study |
The size of text for results of individual studies, see |
fs.fixed.labels |
The size of text for label of fixed effect model, see |
fs.random.labels |
The size of text for label of random effects model, see |
fs.predict.labels |
The size of text for label of prediction interval, see |
fs.study.labels |
The size of text for labels of individual studies, see |
fs.hetstat |
The size of text for heterogeneity measures, see |
fs.test.overall |
The size of text of test for overall effect, see |
fs.test.subgroup |
The size of text of test of subgroup differences, see |
fs.axis |
The size of text on x-axis, see |
fs.smlab |
The size of text of label for summary measure, see |
fs.xlab |
The size of text of label on x-axis, see |
fs.lr |
The size of text of label on left and right side of forest plot, see |
ff.heading |
The fontface for column headings, see |
ff.fixed |
The fontface of text for results of fixed effect model, see |
ff.random |
The fontface of text for results of random effects model, see |
ff.predict |
The fontface of text for results of prediction interval, see |
ff.study |
The fontface of text for results of individual studies, see |
ff.fixed.labels |
The fontface of text for label of fixed effect model, see |
ff.random.labels |
The fontface of text for label of random effects model, see |
ff.predict.labels |
The fontface of text for label of prediction interval, see |
ff.study.labels |
The fontface of text for labels of individual studies, see |
ff.hetstat |
The fontface of text for heterogeneity measures, see |
ff.test.overall |
The fontface of text of test for overall effect, see |
ff.test.subgroup |
The fontface of text for test of subgroup differences, see |
ff.axis |
The fontface of text on x-axis, see |
ff.smlab |
The fontface of text of label for summary measure, see |
ff.xlab |
The fontface of text of label on x-axis, see |
ff.lr |
The fontface of text of label on left and right side of forest plot, see |
squaresize |
A numeric used to increase or decrease the size of squares 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. |
colgap.left |
A unit object specifying gap between columns printed on left side of forest plot. |
colgap.right |
A unit object specifying gap between columns printed on right side of forest plot. |
colgap.forest |
A unit object specifying gap between column adjacent to forest plot and the forest plot. |
colgap.forest.left |
A unit object specifying gap between column on the left side of forest plot and the forest plot. |
colgap.forest.right |
A unit object specifying gap between column on the right side of forest plot and the forest plot. |
just |
Justification of text in all columns but columns with study labels and additional variables (possible values: "left", "right", "center"). |
just.studlab |
Justification of text for study labels (possible values: "left", "right", "center"). |
just.addcols |
Justification of text for additional columns (possible values: "left", "right", "center"). |
addspace |
A logical value indicating whether additional space (i.e. a blank row) is printed above and below study results. |
new |
A logical value indicating whether a new figure should be printed in an existing graphics window. |
backtransf |
A logical indicating whether results should be back transformed in forest plots. If |
digits |
Minimal number of significant digits for treatment effects, see |
digits.se |
Minimal number of significant digits for standard errors, see |
digits.tau2 |
Minimal number of significant digits for between-study variance, see |
digits.pval |
Minimal number of significant digits for p-value of overall treatment effect, see |
digits.pval.Q |
Minimal number of significant digits for p-value of heterogeneity test, see |
digits.Q |
Minimal number of significant digits for heterogeneity statistic Q, see |
digits.I2 |
Minimal number of significant digits for I-squared statistic, see |
digits.weight |
Minimal number of significant digits for weights, see |
... |
Additional graphical arguments (ignored at the moment). |
Details
A forest plot, also called confidence interval plot, is drawn in the active graphics window. Subgroup analyses are conducted and displayed in the plot if byvar is not missing.
The forest function is based on the grid graphics system. In order to print the forest plot, (i) resize the graphics window, (ii) either use dev.copy2eps or dev.copy2pdf.
Result of a test for overall effect or subgroup differences are printed if argument test.overall.fixed, test.overall.random, test.subgroup.fixed, ortest.subgroup.random is TRUE; by default, these arguments are FALSE. R function settings.meta can be used to change this default for the entire R session by setting argument test.overall=TRUE or test.subgroup=TRUE.
Information from object x is utilised if argument weight is missing. Weights from the fixed effect model are used (weight="fixed") if argument x$comb.fixed is TRUE; weights from the random effects model are used (weight="random") if argument x$comb.random is TRUE and x$comb.fixed is FALSE.
The arguments leftcols and rightcols can be used to specify columns which are plotted on the left and right side of the forest plot, respectively. If argument rightcols is FALSE, no columns will be plotted on the right side. By default, i.e. if arguments leftcols and rightcols areNULL and layout="meta", the following default columns will be plotted.
| Additional settings | Default for argument rightcols |
| --- | c("effect", "ci") |
comb.fixed=TRUE & comb.random=FALSE |
c("effect", "ci", "w.fixed") |
comb.fixed=FALSE & comb.random=TRUE |
c("effect", "ci", "w.random") |
comb.fixed=TRUE & comb.random=TRUE |
c("effect", "ci", "w.fixed", "w.random") |
By default, estimated treatment effect and corresponding confidence interval will be printed. Depending on arguments comb.fixed and comb.random, weights of the fixed effect and/or random effects model will be given too. For an object of class metacum or metainf only the estimated treatment effect with confidence interval are plotted.
Depending on the class of the meta-analysis object a different set of columns is printed on the left side of a forest plot.
| Object type | Default for argument leftcols |
| metabin | c("studlab", "event.e", "n.e", "event.c", "n.c") |
| metacont | c("studlab", "n.e", "mean.e", "sd.e", "n.c", "mean.c", "sd.c") |
| metacor | c("studlab", "n") |
| metagen | c("studlab", "TE", "seTE") |
| metainc | c("studlab", "event.e", "time.e", "event.c", "time.c") |
| metaprop | c("studlab", "event", "n") |
| metacum | c("studlab") |
| metainf | c("studlab") |
The arguments 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 arguments leftlabs and rightlabs are NULL, the following default labels will be used:
| Column | studlab |
TE |
seTE |
n.e |
n.c |
n |
| Label | "Study" | "TE" | "seTE" | "Total" | "Total" | "Total" |
| Column | event.e |
event.c |
event |
mean.e |
mean.c |
|
| Label | "Events" | "Events" | "Events" | "Mean" | "Mean" | |
| Column | sd.e |
sd.c |
time.e |
time.c |
||
| Label | "SD" | "SD" | "Time" | "Time" | ||
| Column | effect |
ci |
w.fixed |
w.random |
||
| Label | x$sm |
x$level-CI |
"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). Otherwise the length of leftlabs and rightlabs must be the same as the number of printed columns. The value NA can be used to specify columns using the default labels (see Example).
If argument layout="revman5" (and arguments leftcols and rightcols are NULL) all columns mentioned above will be printed on the left side of the forest plot.
If arguments lab.e and lab.c are NULL, "Experimental" and "Control" are used as labels for experimental and control group, respectively.
The arguments pscale can be used to rescale proportions for objects of class metaprop, e.g. pscale=100 means that proportions are expressed per 100 observations. This is useful in situations with (very) low proportions. For pscale=100, column heading and x-axis label are changed to "Prop (in %)" and "Proportion (in %)", respectively.
A prediction interval for treatment effect of a new study (Higgins et al., 2009) is given in the forest plot if arguments prediction and comb.random are TRUE. For graphical presentation of prediction intervals the approach by Guddat et al. (2012) is used.
Note, in R package meta, version 3.0-0 the following arguments have been removed from R function forest.meta: byvar, level, level.comb, level.predict. This functionality is now provided by R function update.meta (or directly in R functions metabin, metacont, metagen, metacor, and metaprop).
Author(s)
Guido Schwarzer sc@imbi.uni-freiburg.de
References
Guddat C, Grouven U, Bender R, Skipka G 2012), A note on the graphical presentation of prediction intervals in random-effects meta-analyses. Systematic Reviews, 1, 34.
Higgins JPT, Thompson SG, Spiegelhalter DJ (2009), A re-evaluation of random-effects meta-analysis. Journal of the Royal Statistical Society: Series A, 172, 137-159.
See Also
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", method="I", studlab=paste(author, year))## Do (symmetric) forest plot#forest(meta1)## Forest plot specifying argument xlim#forest(meta1, xlim=c(0.01, 10))## Add prediction interval to forest plot#forest(meta1, prediction=TRUE)## Print results of test for overall effect#forest(meta1, test.overall.fixed=TRUE, test.overall.random=TRUE)## Forest plot with 'classic' layout used in# R package meta, version < 1.6-0#forest(meta1, col.square="black", hetstat=FALSE)## Layout of forest plot similar to RevMan 5#forest(meta1, layout="revman5", comb.random=FALSE)## Change set of columns printed on left side# of forest plot#forest(meta1, comb.random=FALSE, leftcols="studlab")## Do not print columns on right side of forest plot#forest(meta1, rightcols=FALSE)## Change study label to "Author"#forest(meta1, comb.random=FALSE, leftlabs=c("Author", NA, NA, NA, NA))## Just give effect estimate and 95% confidence interval# on right side of forest plot#forest(meta1, rightcols=c("effect", "ci"))## 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")## Specify column labels only for newly created variables# 'year' and 'author' (which are part of dataset Olkin95)#forest(meta1, leftcols=c("studlab", "event.e", "n.e", "event.c", "n.c", "author", "year"), leftlabs=c("Author", "Year of Publ"))## Center text in all columns#forest(meta1, leftcols=c("studlab", "event.e", "n.e", "event.c", "n.c", "author", "year"), leftlabs=c("Author", "Year of Publ"), hetstat=FALSE, just="center", just.addcols="center", just.studlab="center")## Not run: ## Same result#forest(meta1, leftcols=c("studlab", "event.e", "n.e", "event.c", "n.c", "author", "year"), leftlabs=c("Author", "Year of Publ"), hetstat=FALSE, just="c", just.addcols="c", just.studlab="c")## End(Not run)## Change some fontsizes and fontfaces#forest(meta1, fs.study=10, ff.study="italic", fs.study.label=11, ff.study.label="bold", fs.axis=5, ff.axis="italic", ff.smlab="bold.italic", ff.fixed="plain", ff.hetstat="plain")## Change some colours#forest(meta1, col.diamond="green", col.diamond.lines="red", col.i=c("green", "blue", "red", "orange"), col.square="pink", col.square.lines="black")## Sort by weight in fixed effect model#forest(meta1, sortvar=1/w.fixed, comb.random=FALSE)## Sort by decreasing weight in fixed effect model#forest(meta1, sortvar=-1/w.fixed, comb.random=FALSE)## Sort by size of treatment effect#forest(meta1, sortvar=TE, comb.random=FALSE)## Sort by size of treatment effect#forest(meta1, sortvar=-TE, comb.random=FALSE)## Sort by decreasing year of publication#forest(meta1, sortvar=-year, comb.random=FALSE)## Sort studies by decreasing treatment effect within year subgroups#meta2 <- update(meta1, byvar=ifelse(year < 1987, "Before 1987", "1987 and later"), print.byvar=FALSE)forest(meta2, sortvar=-TE, comb.random=FALSE)## Print results of test for subgroup differences (random effects model)#forest(meta2, sortvar=-TE, comb.fixed=FALSE, test.subgroup.random=TRUE)