\name{metafor-package}
\alias{metafor-package}
\alias{metafor}
\docType{package}
\title{metafor: A Meta-Analysis Package for R \loadmathjax}
\description{
   The \pkg{metafor} package provides a comprehensive collection of functions for conducting meta-analyses in \R. The package can be used to calculate a wide variety of effect sizes or outcome measures and allows the user to fit equal-, fixed-, and random-effects models to these data. By including study-level variables (\sQuote{moderators}) as predictors in these models, (mixed-effects) meta-regression models can also be fitted. For meta-analyses of \mjeqn{2 \times 2}{2x2} tables, proportions, incidence rates, and incidence rate ratios, the package also provides specialized methods, including the Mantel-Haenszel method, Peto's method, and a variety of suitable generalized linear mixed-effects models (i.e., mixed-effects logistic and Poisson regression models). For non-independent effects/outcomes (e.g., due to correlated sampling errors, correlated true effects or outcomes, or other forms of clustering), one can fit multilevel and multivariate models.

   Various methods are available to assess model fit, to identify outliers and/or influential studies, and for conducting sensitivity analyses (e.g., standardized residuals, Cook's distances, leave-one-out analyses). Advanced techniques for hypothesis testing and obtaining confidence intervals (e.g., for the average effect or outcome or for the model coefficients in a meta-regression model) have also been implemented (e.g., the Knapp and Hartung method, permutation tests, cluster-robust inference methods / robust variance estimation).

   The package also provides functions for creating forest, funnel, radial (Galbraith), normal quantile-quantile, \enc{L'Abbé}{L'Abbe}, Baujat, bubble, and GOSH plots. The presence of publication bias (or more precisely, funnel plot asymmetry or \sQuote{small-study effects}) and its potential impact on the results can be examined via the rank correlation and Egger's regression test, the trim and fill method, the test of excess significance, and by applying a variety of selection models.
}
\section{The escalc Function}{
   [\code{\link{escalc}}] Before a meta-analysis can be conducted, the relevant results from each study must be quantified in such a way that the resulting values can be further aggregated and compared. The \code{\link{escalc}} function can be used to compute a wide variety of effect sizes or \sQuote{outcome measures} (and the corresponding sampling variances) that are often used in meta-analyses (e.g., risk ratios, odds ratios, risk differences, mean differences, standardized mean differences, response ratios / ratios of means, raw or r-to-z transformed correlation coefficients). Measures for quantifying some characteristic of individual groups (e.g., in terms of means, proportions, or incidence rates and transformations thereof), measures of change (e.g., raw and standardized mean changes), and measures of variability (e.g., variability ratios and coefficient of variation ratios) are also available.
}
\section{The rma.uni Function}{
   [\code{\link{rma.uni}}] The various meta-analytic models that are typically used in practice are special cases of the general linear (mixed-effects) model. The \code{\link{rma.uni}} function (with alias \code{\link{rma}}) provides a general framework for fitting such models. The function can be used in combination with any of the effect sizes or outcome measures computed with the \code{\link{escalc}} function or, more generally, any set of estimates (with corresponding sampling variances or standard errors) one would like to analyze. The notation and models underlying the \code{\link{rma.uni}} function are explained below.

   For a set of \mjseqn{i = 1, \ldots, k} independent studies, let \mjseqn{y_i} denote the observed value of the effect size or outcome measure in the \mjeqn{i\text{th}}{ith} study. Let \mjseqn{\theta_i} denote the corresponding (unknown) true effect/outcome, such that \mjdeqn{y_i \mid \theta_i \sim N(\theta_i, v_i).}{y_i | \theta_i ~ N(\theta_i, v_i).} In other words, the observed effect sizes or outcomes are assumed to be unbiased and normally distributed estimates of the corresponding true effects/outcomes with sampling variances equal to \mjseqn{v_i} (where \mjseqn{v_i} is the square of the standard errors of the estimates). The \mjseqn{v_i} values are assumed to be known. Depending on the outcome measure used, a bias correction, normalizing, and/or variance stabilizing transformation may be necessary to ensure that these assumptions are (at least approximately) true (e.g., the log transformation for odds/risk ratios, the bias correction for standardized mean differences, Fisher's r-to-z transformation for correlations; see \code{\link{escalc}} for further details).

   According to the \bold{random-effects model}, we assume that \mjeqn{\theta_i \sim N(\mu, \tau^2)}{\theta_i ~ N(\mu, \tau^2)}, that is, the true effects/outcomes are normally distributed with \mjseqn{\mu} denoting the average true effect/outcome and \mjseqn{\tau^2} the variance in the true effects/outcomes (\mjseqn{\tau^2} is therefore often referred to as the amount of \sQuote{heterogeneity} in the true effects/outcomes or the \sQuote{between-study variance}). The random-effects model can also be written as \mjdeqn{y_i = \mu + u_i + \varepsilon_i,}{y_i = \mu + u_i + \epsilon_i,} where \mjeqn{u_i \sim N(0, \tau^2)}{u_i ~ N(0, \tau^2)} and \mjeqn{\varepsilon_i \sim N(0, v_i)}{\epsilon_i ~ N(0, v_i)}. The fitted model provides estimates of \mjseqn{\mu} and \mjseqn{\tau^2}, that is, \mjdeqn{\hat{\mu} = \frac{\sum_{i=1}^k w_i y_i}{\sum_{i=1}^k w_i},}{\mu-hat = \sum w_i y_i / \sum w_i,} where \mjeqn{w_i = 1/(\hat{\tau}^2 + v_i)}{w_i = 1/(\tau-hat^2 + v_i)} and \mjeqn{\hat{\tau}^2}{\tau-hat^2} denotes an estimate of \mjseqn{\tau^2} obtained with one of the many estimators that have described in the literature for this purpose (this is sometimes called the standard \sQuote{inverse-variance} method for random-effects models or the \sQuote{normal-normal} model).

   A special case of the model above is the \bold{equal-effects model} (also sometimes called the common-effect(s) model) which arises when \mjseqn{\tau^2 = 0}. In this case, the true effects/outcomes are homogeneous (i.e., \mjeqn{\theta_1 = \theta_2 = \ldots = \theta_k \equiv \theta}{\theta_1 = \theta_2 = \ldots = \theta_k = \theta}) and hence we can write the model as \mjdeqn{y_i = \theta + \varepsilon_i,}{y_i = \theta + \epsilon_i,} where \mjseqn{\theta} denotes \emph{the} true effect/outcome in the studies, which is estimated with \mjdeqn{\hat{\theta} = \frac{\sum_{i=1}^k w_i y_i}{\sum_{i=1}^k w_i},}{\theta-hat = \sum w_i y_i / \sum w_i,} where \mjeqn{w_i = 1/v_i}{w_i = 1/v_i} (again, this is the standard \sQuote{inverse-variance} method as described in the meta-analytic literature). Note that the commonly-used term \sQuote{fixed-effects model} is not used here -- for an explanation, see \link[=misc-models]{here}.

   Study-level variables (often referred to as \sQuote{moderators}) can also be included as predictors in meta-analytic models, leading to so-called \sQuote{meta-regression} models (to examine whether the effects/outcomes tend to be larger/smaller under certain conditions or circumstances). When including moderator variables in a random-effects model, we obtain a \bold{mixed-effects meta-regression model}. This model can be written as \mjdeqn{y_i = \beta_0 + \beta_1 x_{i1} + \beta_2 x_{i2} + \ldots + \beta_{p'} x_{ip'} + u_i + \varepsilon_i,}{y_i = \beta_0 + \beta_1 x_i1 + \beta_2 x_i2 + \ldots + \beta_p' x_ip' + u_i + \epsilon_i,} where \mjeqn{u_i \sim N(0, \tau^2)}{u_i ~ N(0, \tau^2)} and \mjeqn{\varepsilon_i \sim N(0, v_i)}{\epsilon_i ~ N(0, v_i)} as before and \mjeqn{x_{ij}}{x_ij} denotes the value of the \mjeqn{j\text{th}}{jth} moderator variable for the \mjeqn{i\text{th}}{ith} study (letting \mjseqn{p = p' + 1} denote the total number of coefficients in the model including the model intercept). Therefore, \mjseqn{\beta_j} denotes how much the average true effect/outcome differs for studies that differ by one unit on \mjeqn{x_{ij}}{x_ij} and the model intercept \mjseqn{\beta_0} denotes the average true effect/outcome when the values of all moderator variables are equal to zero. The value of \mjseqn{\tau^2} in the mixed-effects model denotes the amount of \sQuote{residual heterogeneity} in the true effects/outcomes (i.e., the amount of variability in the true effects/outcomes that is not accounted for by the moderators included in the model). In matrix notation, the model can also be written as \mjdeqn{y = X\beta + u + \varepsilon,}{y = X\beta + u + \epsilon,} where \mjseqn{y} is a \mjeqn{k \times 1}{k x 1} column vector with the observed effect sizes or outcomes, \mjseqn{X} is the \mjeqn{k \times p}{k x p} model matrix (with the first column equal to 1s for the intercept term), \mjseqn{\beta} is a \mjeqn{p \times 1}{p x 1} column vector with the model coefficients, and \mjseqn{u} and \mjeqn{\varepsilon}{\epsilon} are \mjeqn{k \times 1}{k x 1} column vectors for the random effects and sampling errors, where \mjeqn{\text{Var}[\varepsilon]}{Var[\epsilon]} is a \mjeqn{k \times k}{k x k} diagonal matrix with the \mjseqn{v_i} values along the diagonal and \mjeqn{\text{Var}[u] = \tau^2 I}{Var[u] = \tau^2 I}, where \mjseqn{I} is a \mjeqn{k \times k}{k x k} identity matrix.
}
\section{The rma.mh Function}{
   [\code{\link{rma.mh}}] The Mantel-Haenszel method provides an alternative approach for fitting equal-effects models when dealing with studies providing data in the form of \mjeqn{2 \times 2}{2x2} tables or in the form of event counts (i.e., person-time data) for two groups (Mantel & Haenszel, 1959). The method is particularly advantageous when aggregating a large number of studies with small sample sizes (the so-called sparse data or increasing strata case). The Mantel-Haenszel method is implemented in the \code{\link{rma.mh}} function. It can be used in combination with risk ratios, odds ratios, risk differences, incidence rate ratios, and incidence rate differences.
}
\section{The rma.peto Function}{
   [\code{\link{rma.peto}}] Yet another method that can be used in the context of a meta-analysis of \mjeqn{2 \times 2}{2x2} table data is Peto's method (see Yusuf et al., 1985), implemented in the \code{\link{rma.peto}} function. The method provides an estimate of the (log) odds ratio under an equal-effects model. The method is particularly advantageous when the event of interest is rare, but see the documentation of the function for some caveats.
}
\section{The rma.glmm Function}{
   [\code{\link{rma.glmm}}] Dichotomous response variables and event counts (based on which one can calculate outcome measures such as odds ratios, incidence rate ratios, proportions, and incidence rates) are often assumed to arise from binomial and Poisson distributed data. Meta-analytic models that are directly based on such distributions are implemented in the \code{\link{rma.glmm}} function. These models are essentially special cases of generalized linear mixed-effects models (i.e., mixed-effects logistic and Poisson regression models). For \mjeqn{2 \times 2}{2x2} table data, a mixed-effects conditional logistic model (based on the non-central hypergeometric distribution) is also available. Random/mixed-effects models with dichotomous data are often referred to as \sQuote{binomial-normal} models in the meta-analytic literature. Analogously, for event count data, such models could be referred to as \sQuote{Poisson-normal} models.
}
\section{The rma.mv Function}{
   [\code{\link{rma.mv}}] Standard meta-analytic models assume independence between the observed effect sizes or outcomes obtained from a set of studies. This assumption is often violated in practice. Dependencies can arise for a variety of reasons. For example, the sampling errors and/or true effects/outcomes may be correlated in multiple treatment studies (e.g., when multiple treatment groups are compared with a common control/reference group, such that the data from the control/reference group is used multiple times to compute the observed effect sizes or outcomes) or in multiple endpoint studies (e.g., when more than one effect size estimate or outcome is calculated based on the same sample of subjects due to the use of multiple endpoints or response variables). Correlation among the true effects/outcomes can also arise due to other forms of clustering (e.g., when multiple effects/outcomes derived from the same author, lab, or research group may be more similar to each other than effects/outcomes derived from different authors, labs, or research groups). In ecology and related fields, the shared phylogenetic history of the organisms studied (e.g., plants, fungi, animals) can also induce correlation among the effects/outcomes. The \code{\link{rma.mv}} function can be used to fit suitable meta-analytic multivariate/multilevel models to such data, so that the non-independence in the effects/outcomes is accounted for. Network meta-analyses (also called multiple/mixed treatment comparisons) can also be carried out with this function.
}
\section{Future Plans and Updates}{
   The \pkg{metafor} package is a work in progress and is updated on a regular basis with new functions and options. The development version of the package can be found on GitHub at \url{https://github.com/wviechtb/metafor} and can be installed with: \preformatted{install.packages("remotes")
remotes::install_github("wviechtb/metafor")} With \code{metafor.news()}, you can read the \file{NEWS} file of the package after installation. Comments, feedback, and suggestions for improvements are always welcome.
}
\section{Citing the Package}{
   To cite the package, please use the following reference:

   Viechtbauer, W. (2010). Conducting meta-analyses in R with the metafor package. \emph{Journal of Statistical Software}, \bold{36}(3), 1-48. \doi{10.18637/jss.v036.i03}
}
\section{Getting Started with the Package}{
   The paper mentioned above is a good starting place for those interested in using the package. The purpose of the article is to provide a general overview of the package and its capabilities (as of version 1.4-0). Not all of the functions and options are described in the paper, but it should provide a useful introduction to the package. The paper can be freely downloaded from the URL given above or can be directly loaded with the command \code{vignette("metafor")}.

   In addition to reading the paper, carefully read this page and then the help pages for the \code{\link{escalc}} and the \code{\link{rma.uni}} functions (or the \code{\link{rma.mh}}, \code{\link{rma.peto}}, \code{\link{rma.glmm}}, and/or \code{\link{rma.mv}} functions if you intend to use these models/methods). The help pages for these functions provide links to many additional functions, which can be used after fitting a model. You can also read the entire documentation online at \url{https://wviechtb.github.io/metafor/} (where it is nicely formatted and the output from all examples is provided).

   A (pdf) diagram showing the various functions in the metafor package (and how they are related to each other) can be opened with the command \code{vignette("diagram", package="metafor")}.

   Finally, additional information about the package, several detailed analysis examples, examples of plots and figures provided by the package (with the corresponding code), some additional tips and notes, and a FAQ can be found on the package website at \url{https://www.metafor-project.org}.
}
\author{
   Wolfgang Viechtbauer \email{wvb@metafor-project.org} \cr
   package website: \url{https://www.metafor-project.org} \cr
   author homepage: \verb{https://www.wvbauer.com} \cr

   Suggestions on how to obtain help with using the package can found on the package website at: \url{https://www.metafor-project.org/doku.php/help}
}
\references{
   Cooper, H., Hedges, L. V., & Valentine, J. C. (Eds.) (2009). \emph{The handbook of research synthesis and meta-analysis} (2nd ed.). New York: Russell Sage Foundation.

   Hedges, L. V., & Olkin, I. (1985). \emph{Statistical methods for meta-analysis}. San Diego, CA: Academic Press.

   Mantel, N., & Haenszel, W. (1959). Statistical aspects of the analysis of data from retrospective studies of disease. \emph{Journal of the National Cancer Institute}, \bold{22}(4), 719--748. \verb{https://doi.org/10.1093/jnci/22.4.719}

   Viechtbauer, W. (2010). Conducting meta-analyses in R with the metafor package. \emph{Journal of Statistical Software}, \bold{36}(3), 1--48. \verb{https://doi.org/10.18637/jss.v036.i03}

   Yusuf, S., Peto, R., Lewis, J., Collins, R., & Sleight, P. (1985). Beta blockade during and after myocardial infarction: An overview of the randomized trials. \emph{Progress in Cardiovascular Disease}, \bold{27}(5), 335--371. \verb{https://doi.org/10.1016/s0033-0620(85)80003-7}
}
\keyword{package}
