\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 }