added 'forestplot.bmr()' documentation

man/forestplot.bmr.Rd

+\name{forestplot.bmr}
+\alias{forestplot.bmr}
+\title{
+  Generate a forest plot for a \code{\link{bmr}} object
+  (based on the \code{forestplot} package's plotting functions).
+}
+\description{
+  Generates a forest plot, showing individual estimates along with their
+  95 percent confidence intervals, shrinkage intervals, resulting effect
+  estimates and prediction intervals.
+}
+\usage{
+  \method{forestplot}{bmr}(x, X.summary, X.prediction,
+           labeltext, exponentiate=FALSE,
+           shrinkage=TRUE, heterogeneity=TRUE, 
+           digits=2, decplaces.X, plot=TRUE,
+           fn.ci_norm, fn.ci_sum, col, legend, boxsize, ...)
+}
+\arguments{
+  \item{x}{
+    a \code{\link{bmr}} object.
+  }
+  \item{X.summary}{
+    a regressor matrix (\eqn{X}) to be used for effect estimates that
+    are to be shown in the plot. By default, a diagnonal matrix, set to
+    \code{NULL} in order to suppress showing summary estimates.
+  }
+  \item{X.prediction}{
+    an optional regressor matrix (\eqn{X}) to be used for predictions
+    that are to be shown in the plot.
+  }
+  \item{labeltext}{an (alternative) \dQuote{\code{labeltext}} argument
+    which is then handed on to the \code{\link[forestplot]{forestplot}()}
+    function (see the help there). You can use this to change contents
+    or add columns to the displayed table; see the example below.
+  }
+  \item{exponentiate}{
+    a logical flag indicating whether to exponentiate numbers (effect
+    sizes) in table and plot.
+  }
+  \item{shrinkage}{
+    a logical flag indicating whether to show shrinkage intervals along
+    with the quoted estimates.
+  }
+  \item{heterogeneity}{
+    a logical flag indicating whether to quote the heterogeneity estimate 
+    and CI (at the bottom left).
+  }
+  \item{digits}{
+    The number of significant digits to be shown.
+    This is interpreted relative to the standard errors of all estimates.
+  }
+  \item{decplaces.X}{
+    The number of decimal places to be shown for the regressors.
+  }
+  \item{plot}{
+    a logical flag indicating whether to actually generate a plot.
+  }
+  \item{fn.ci_norm, fn.ci_sum, col, legend, boxsize, \ldots}{
+    other arguments passed on to the
+    \pkg{forestplot} package's \code{\link[forestplot]{forestplot}}
+    function (see also the help there).
+  }
+}
+\details{
+  Generates a forest plot illustrating the underlying data and
+  resulting estimates (effect estimates and/or prediction intervals,
+  as well as shrinkage estimates and intervals).
+  For effect estimates and prediction intervals, regressor matrices
+  (\eqn{x}) need to be supplied via the \sQuote{\code{X.summary}} or
+  \sQuote{\code{X.prediction}} arguments. Effect estimates are shown as
+  diamonds, predictions are shown as horizontal bars.
+}
+\note{This function is based on the \pkg{forestplot} package's
+      \dQuote{\code{\link[forestplot]{forestplot}()}} function.
+}
+\author{
+  Christian Roever \email{christian.roever@med.uni-goettingen.de}
+}
+\references{
+  C. Roever.
+  \href{https://www.doi.org/10.18637/jss.v093.i06}{Bayesian random-effects meta-analysis using the bayesmeta R package}.
+  \emph{Journal of Statistical Software}, \bold{93}(6):1-51, 2020.
+
+  C. Lewis and M. Clarke.
+  \href{https://doi.org/10.1136/bmj.322.7300.1479}{Forest plots: trying to see the wood and the trees}.
+  \emph{BMJ}, \bold{322}:1479, 2001.
+
+  C. Guddat, U. Grouven, R. Bender and G. Skipka.
+  \href{https://doi.org/10.1186/2046-4053-1-34}{A note on the
+    graphical presentation of prediction intervals in random-effects
+    meta-analyses}. \emph{Systematic Reviews}, \bold{1}(34), 2012.
+  
+  R.D. Riley, J.P. Higgins and J.J. Deeks.
+  \href{https://doi.org/10.1136/bmj.d549}{Interpretation of random effects meta-analyses}.
+  \emph{BMJ}, \bold{342}:d549, 2011.
+} 
+\seealso{
+  \code{\link{bayesmeta}},
+  \code{\link[forestplot]{forestplot}},
+  \code{\link{forestplot.bayesmeta}},
+  \code{\link{forestplot.escalc}}.
+}
+\examples{
+\dontrun{
+# load data:
+data("CrinsEtAl2014")
+# compute effect measures (log-OR):
+crins.es <- escalc(measure="OR",
+                   ai=exp.AR.events,  n1i=exp.total,
+                   ci=cont.AR.events, n2i=cont.total,
+                   slab=publication, data=CrinsEtAl2014)
+# show data:
+crins.es[,c("publication", "IL2RA", "exp.AR.events", "exp.total",
+            "cont.AR.events", "cont.total", "yi", "vi")]
+# specify regressor matrix (binary indicator variables):
+X <- cbind("basiliximab"=as.numeric(crins.es$IL2RA=="basiliximab"),
+           "daclizumab" =as.numeric(crins.es$IL2RA=="daclizumab"))
+print(X)
+# perform meta-analysis:
+bmr01 <- bmr(crins.es, X=X)
+
+# show forest plot:
+forestplot(bmr01)
+
+# show forest plot including contrast
+# (difference between groups):
+forestplot(bmr01,
+           X.summary=rbind("basiliximab" =c(1, 0),
+                           "daclizumab"  =c(0, 1),
+                           "contrast"    =c(-1, 1)))
+
+##########################################################
+# perform meta-analysis using a different regressor setup:
+X <- cbind("basiliximab"=1,
+           "offset.dac"=as.numeric(crins.es$IL2RA=="daclizumab"))
+print(X)
+# perform meta-analysis:
+bmr02 <- bmr(crins.es, X=X)
+
+# show forest plot:
+forestplot(bmr02,
+           X.summary=rbind("basiliximab" =c(1, 0),
+                           "daclizumab"  =c(1, 1),
+                           "contrast"    =c(0, 1)))
+
+##########################################################
+# continuous regressor and prediction:
+help("NicholasEtAl2019")
+# load data:
+data("NicholasEtAl2019")
+# compute effect sizes (logarithic odds) from count data:
+es <- escalc(measure="PLO",
+             xi=patients*(prog.percent/100), ni=patients,
+             slab=study, data=NicholasEtAl2019)
+# set up regressor matrix:
+X <- cbind("intercept2000" = 1, "year" = (es$year-2000))
+# perform analysis:
+bmr03 <- bmr(es, X=X)
+# show forest plot including mean estimates for the
+# years 1990 and 2018, and a prediction for 2020:
+forestplot(bmr03,
+           X.summary=rbind("mean 1990"=c(1, -10),
+                           "mean 2018"=c(1,18)),
+           X.predict=rbind("prediction 2020"=c(1,20)),
+           xlab="log-odds",
+           txt_gp = fpTxtGp(ticks = gpar(cex=1), xlab = gpar(cex=1)))
+}
+}
+\keyword{ hplot }
\ No newline at end of file