The metafor Package

On this page, you can find a description of the (recent) updates to the metafor package. Older updates are archived here.

• the metafor package now makes use of the mathjaxr package to nicely render equations shown in the HTML help pages
• rma() can now also fit location-scale models
• added selmodel() for fitting a wide variety of selection models (and added the corresponding plot.rma.uni.selmodel() function for drawing the estimated selection function)
• rma.mv() gains dfs argument and now provides an often better way for calculating the (denominator) degrees of freedom for approximate t- and F-tests when dfs="contain"
• added tes() function for the test of excess significance
• added regplot() function for drawing scatter plots / bubble plots based on meta-regression models
• added rcalc() for calculating the variance-covariance matrix of correlation coefficients and matreg() for fitting regression models based on correlation/covariance matrices
• added convenience functions dfround() and vec2mat()
• added aggregate.escalc() function to aggregate multiple effect sizes or outcomes within studies/clusters
• regtest() now shows the 'limit estimate' of the (average) true effect when using sei, vi, ninv, or sqrtninv as predictors (and the model does not contain any other moderators)
• vif() gains btt argument and can now also compute generalized variance inflation factors; a proper print.vif.rma() function was also added
• anova.rma() argument L renamed to X (the former still works, but is no longer documented)
• argument order in cumul() should now just be a variable, not the order of the variable, to be used for ordering the studies and must be of the same length as the original dataset that was used in the model fitting
• similarly, vector arguments in various plotting functions such as forest.rma() must now be of the same length as the original dataset that was used in the model fitting (any subsetting and removal of NAs is automatically applied)
• the various leave1out() and cumul() functions now provide I^2 and H^2 also for fixed-effects models; accordingly, plot.cumul.rma() now also works with such models
• fixed level not getting passed down to the various cumul() functions
• plot.cumul.rma() argument addgrid renamed to grid (the former still works, but is no longer documented)
• forest.default(), forest.rma(), and labbe() gain plim argument and now provide more flexibility in terms of the scaling of the points
• forest.rma() gains colout argument (to adjust the color of the observed effect sizes or outcomes)
• in the various forest() functions, the right header is now suppressed when annotate=FALSE and header=TRUE
• funnel.default() and funnel.rma() gain label and offset arguments
• funnel.default() and funnel.rma() gain lty argument; the reference line is now drawn by default as a dotted line (like the line for the pseudo confidence region)
• the forest and funnel arguments of reporter.rma.uni() can now also be logicals to suppress the drawing of these plots
• added weighted argument to fsn() (for Orwin's method)
• added some more transformation functions
• bldiag() now properly handles ?x0 or 0x? matrices
• p-values are still given to 2 digits even when digits=1
• summary.escalc() also provides the p-values (of the Wald-type tests); but when using the transf argument, the sampling variances, standard errors, test statistics, and p-values are no longer shown
• rma.uni() no longer constrains a fixed tau^2 value to 0 when k=1
• slight speedup in functions that repeatedly fit rma.uni() models by skipping the computation of the pseudo R^2 statistic
• started using the pbapply package for showing progress bars, also when using parallel processing
• to avoid potential confusion, all references to 'credibility intervals' have been removed from the documentation; these intervals are now exclusively referred to as 'prediction intervals'; in the output, the bounds are therefore indicated now as pi.lb and pi.ub (instead of cr.lb and cr.ub); the corresponding argument names were changed in addpoly.default(); argument addcred was changed to addpred in addpoly.rma() and forest.rma(); however, code using the old arguments names should continue to work
• one can now use weights(..., type="rowsum") for intercept-only rma.mv models (to obtain 'row-sum weights')
• simulate.rma() gains olim argument; renamed the clim argument in summary.escalc() and the various forest() functions to olim for consistency (the old clim argument should continue to work)
• show nicer network graphs for dat.hasselblad1998 and dat.senn2013 in the help files
• added 23 datasets (dat.anand1999, dat.assink2016, dat.baskerville2012, dat.bornmann2007, dat.cannon2006, dat.cohen1981, dat.craft2003, dat.crede2010, dat.dagostino1998, dat.damico2009, dat.dorn2007, dat.hahn2001, dat.kalaian1996, dat.kearon1998, dat.knapp2017, dat.landenberger2005, dat.lau1992, dat.lim2014, dat.lopez2019, dat.maire2019, dat.moura2021, dat.obrien2003, dat.vanhowe1999, dat.viechtbauer2021)
• the package now runs a version check on startup in interactive sessions; setting the environment variable METAFOR_VERSION_CHECK to FALSE disables this
• refactored various functions (for cleaner/simpler code)
• improved the documentation a bit

• version jump to 2.4-0 for CRAN release (from now on, even minor numbers for CRAN releases, odd numbers for development versions)
• the various forest() functions gain header argument
• escalc() gains include argument
• setting verbose=3 in model fitting functions sets options(warn=1)
• forest.rma() and forest.default() now throw informative errors when misusing order and subset arguments
• fixed failing tests due to the stringsAsFactors=FALSE change in the upcoming version of R
• print.infl.rma.uni() gains infonly argument, to only show the influential studies
• removed MASS from Suggests (no longer needed)
• argument btt can now also take a string to grep for
• added optimParallel as possible optimizer in rma.mv()
• added (for now undocumented) option to fit models in rma.glmm() via the GLMMadaptive package (instead of lme4); to try this, use: control=list(package="GLMMadaptive")
• started to use numbering scheme for 'devel' version (the number after the dash indicates the devel version)
• added contrmat() function (for creating a matrix that indicates which groups have been compared against each other in each row of a dataset)
• added to.wide() function (for restructuring long format datasets into the wide format needed for contrast-based analyses)
• I^2 and H^2 are also shown in output for fixed-effects models
• argument grid in baujat() can now also be a color name
• added (for now undocumented) time argument to more functions that are computationally expensive
• added (for now undocumented) textpos argument to the various forest functions
• added a new dataset (dat.graves2010)
• added more tests

• added formula() method for objects of class rma
• llplot() now also allows for measure="GEN"; also, the documentation and y-axis label have been corrected to indicate that the function plots likelihoods (not log likelihoods)
• confint.rma.mv() now returns an object of class list.confint.rma when obtaining CIs for all variance and correlation components of the model; added corresponding print.list.confint.rma() function
• moved tol argument in permutest() to control and renamed the argument to comptol
• added PMM and GENQM estimators in rma.uni()
• added vif() function to get variance inflation factors
• added .glmulti object for making the interaction with glmulti easier
• added reporter() and reporter.rma.uni() for dynamically generating analysis reports for objects of class rma.uni
• output is now styled/colored when crayon package is loaded (this only works on a 'proper' terminal with color support; also works in RStudio)
• overhauled plot.gosh.rma(); when out is specified, it now shows two distributions, one for the values when the outlier is included and one for the values when for outlier is excluded; dropped the hcolargument and added border argument
• refactored influence.rma.uni() to be more consistent internally with other functions; print.infl.rma.uni() and plot.infl.rma.uni() adjusted accordingly; functions cooks.distance.rma.uni(), dfbetas.rma.uni(), and rstudent.rma.uni() now call influence.rma.uni() for the computations
• rstudent.rma.uni() now computes the SE of the deleted residuals in such a way that it will yield identical results to a mean shift outlier model even when that model is fitted with test="knha"
• rstandard.rma.uni() gains type argument, and can now also compute conditional residuals (it still computes marginal residuals by default)
• cooks.distance.rma.mv() gains cluster argument, so that the Cook's distances can be computed for groups of estimates
• cooks.distance.rma.mv() gains parallel, ncpus, and cl arguments and can now make use of parallel processing
• cooks.distance.rma.mv() should be faster by using the estimates from the full model as starting values when fitting the models with the ith study/cluster deleted from the dataset
• cooks.distance.rma.mv() gains reestimate argument; when set to FALSE, variance/correlation components are not reestimated
• rstandard.rma.mv() gains cluster argument for computing cluster-level multivariate standardized residuals
• added rstudent.rma.mv() and dfbetas.rma.mv()
• smarter matching of elements in newmods (when using a named vector) in predict() that also works for models with interactions (thanks to Nicole Erler for pointing out the problem)
• rma.uni() and rma.mv() no longer issue (obvious) warnings when user constrains vi or V to 0 (i.e., vi=0 or V=0, respectively)
• rma.mv() does more intelligent filtering based on NAs in V matrix
• rma.mv() now ensures strict symmetry of any (var-cov or correlation) matrices specified via the R argument
• fixed rma.mv() so checks on R argument run as intended; also fixed an issue when multiple formulas with slashes are specified via random (thanks to Andrew Loignon for pointing out the problem)
• suppressed showing calls on some warnings/errors in rma.mv()
• rma.mv() now allows for a continuous-time autoregressive random effects structure (struct="CAR") and various spatial correlation structures (struct="SPEXP", "SPGAU", "SPLIN", "SPRAT", and "SPSPH")
• rma.mv() now allows for struct="GEN" which models correlated random effects for any number of predictors, including continuous ones (i.e., this allows for 'random slopes')
• in the various forest() functions, when options(na.action="na.pass") or options(na.action="na.exclude") and an annotation contains NA, this is now shown as a blank (instead of NA [NA, NA])
• the various forest() and addpoly() functions gain a fonts argument
• the various forest() functions gain a top argument
• the various forest() functions now show correct point sizes when the weights of the studies are exactly the same
• forest.cumul.rma() gains a col argument
• funnel.default() and funnel.rma() can now take vectors as input for the col and bg arguments (and also for pch); both functions also gain a legend argument
• addpoly() functions can now also show prediction interval bounds
• removed 'formula interface' from escalc(); until this actually adds some kind of extra functionality, this just makes escalc() more confusing to use
• escalc() can now compute the coefficient of variation ratio and the variability ratio for pre-post or matched designs ("CVRC", "VRC")
• escalc() does a bit more housekeeping
• added (currently undocumented) arguments onlyo1, addyi, and addvi to escalc() that allow for more flexibility when computing certain bias corrections and when computing sampling variances for measures that make use of the add and to arguments
• escalc() now sets add=0 for measures where the use of such a bias correction makes little sense; this applies to the following measures: "AS", "PHI", "RTET", "IRSD", "PAS", "PFT", "IRS", and "IRFT"; one can still force the use of the bias correction by explicitly setting the add argument to some non-zero value
• added clim argument to summary.escalc()
• added ilim argument to trimfill()
• labbe() gains lty argument
• labbe() now (invisibly) returns a data frame with the coordinates of the points that were drawn (which may be useful for manual labeling of points in the plot)
• added a print method for profile.rma objects
• profile.rma.mv() now check whether any of the profiled log-likelihood values is larger than the log-likelihood of the fitted model (using numerical tolerance given by lltol) and issues a warning if so
• profile.rma.uni(), profile.rma.mv(), and plot.profile.rma() gain cline argument; plot.profile.rma() gains xlim, ylab, and main arguments
• fixed an issue with robust.rma.mv() when the model was fitted with sparse=TRUE (thanks to Roger Martineau for noting the problem)
• various method functions (fitted(), resid(), predict(), etc.) behave in a more consistent manner when model omitted studies with missings
• predict.rma() gains vcov argument; when set to TRUE, the variance-covariance matrix of the predicted values is also returned
• vcov.rma() can now also return the variance-covariance matrix of the fitted values (type="fitted") and the residuals (type="resid")
• added `$<-` and as.matrix() methods for list.rma objects
• fixed error in simulate.rma() that would generate too many samples for rma.mv models
• added undocumented argument time to all model fitting functions; if set to TRUE, the model fitting time is printed
• added more tests (also for parallel operations); also, all tests updated to use proper tolerances instead of rounding
• reorganized the documentation a bit

• added simulate() method for rma objects; added MASS to Suggests (since simulating for rma.mv objects requires mvrnorm() from MASS)
• cooks.distance.rma.mv() now works properly even when there are missing values in the data
• residuals() gains type argument and can compute Pearson residuals
• the newmods argument in predict() can now be a named vector or a matrix/data frame with column names that get properly matched up with the variables in the model
• added ranef.rma.mv() for extracting the BLUPs of the random effects for rma.mv models
• all functions that repeatedly refit models now have the option to show a progress bar
• added ranktest.default(), so user can now pass the outcomes and corresponding sampling variances directly to the function
• added regtest.default(), so user can now pass the outcomes and corresponding sampling variances directly to the function
• funnel.default() gains subset argument
• funnel.default() and funnel.rma() gain col and bg arguments
• plot.profile.rma() gains ylab argument
• more consistent handling of robust.rma objects
• added a print method for rma.gosh objects
• the (log) relative risk is now called the (log) risk ratio in all help files, plots, code, and comments
• escalc() can now compute outcome measures based on paired binary data ("MPRR", "MPOR", "MPRD", "MPORC", and "MPPETO")
• escalc() can now compute (semi-)partial correlation coefficients ("PCOR", "ZPCOR", "SPCOR")
• escalc() can now compute measures of variability for single groups ("CVLN", "SDLN") and for the difference in variability between two groups ("CVR", "VR"); also the log transformed mean ("MNLN") has been added for consistency
• escalc() can now compute the sampling variance for measure="PHI" for studies using stratified sampling (vtpye="ST")
• the `[` method for escalc objects now properly handles the ni and slab attributes and does a better job of cleaning out superfluous variable name information
• added rbind() method for escalc objects
• added as.data.frame() method for list.rma objects
• added a new dataset (dat.pagliaro1992) for another illustration of a network meta-analysis
• added a new dataset (dat.laopaiboon2015) on the effectiveness of azithromycin for treating lower respiratory tract infections
• rma.uni() and rma.mv() now check if the ratio of the largest to smallest sampling variance is very large; results may not be stable then (and very large ratios typically indicate wrongly coded data)
• model fitting functions now check if extra/superfluous arguments are specified via ... and issues are warning if so
• instead of defining own generic ranef(), import ranef() from nlme
• improved output formatting
• added more tests (but disabled a few tests on CRAN to avoid some issues when R is compiled with --disable-long-double)
• some general code cleanup
• renamed diagram_metafor.pdf vignette to just diagram.pdf
• minor updates in the documentation

• started to use git as version control system, GitHub to host the repository (https://github.com/wviechtb/metafor) for the development version of the package, Travis CI as continuous integration service (https://travis-ci.org/wviechtb/metafor), and Codecov for automated code coverage reporting (https://codecov.io/github/wviechtb/metafor)
• argument knha in rma.uni() and argument tdist in rma.glmm() and rma.mv() are now superseded by argument test in all three functions; for backwards compatibility, the knha and tdist arguments still work, but are no longer documented
• rma(yi, vi, weights=1, test="knha") now yields the same results as rma(yi, vi, weighted=FALSE, test="knha") (but use of the Knapp and Hartung method in the context of an unweighted analysis remains an experimental feature)
• one can now pass an escalc object directly to rma.uni(), which then tries to automatically determine the yi and vi variables in the data frame (thanks to Christian Röver for the suggestion)
• escalc() can now also be used to convert a regular data frame to an escalc object
• for measure="UCOR", the exact bias-correction is now used (instead of the approximation); when vtype="UB", the exact equation is now used to compute the unbiased estimate of the variance of the bias-corrected correlation coefficient; hence gsl is now a suggested package (needed to compute the hypergeometric function) and is loaded when required
• cooks.distance() now also works with rma.mv objects; and since model fitting can take some time, an option to show a progress bar has been added
• fixed an issue with robust.rma.mv() throwing errors when the model was fitted with sparse=TRUE
• fixed an error with robust.rma.mv() when the model was fitted with user-defined weights (or a user-defined weight matrix)
• added ranef() for extracting the BLUPs of the random effects (only for rma.uni objects at the moment)
• reverted back to the pre-1.1-0 way of computing p-values for individual coefficients in permutest.rma.uni(), that is, the p-value is computed with mean(abs(z_perm) >= abs(z_obs) - tol) (where tol is a numerical tolerance)
• permutest.rma.uni() gains permci argument, which can be used to obtain permutation-based CIs of the model coefficients (note that this is computationally very demanding and may take a long time to complete)
• rma.glmm() continues to work even when the saturated model cannot be fitted (although the tests for heterogeneity are not available then)
• rma.glmm() now allows control over the arguments used for method.args (via control=list(hessianCtrl=list(...))) passed to hessian() (from the numDeriv package) when using model="CM.EL" and measure="OR"
• in rma.glmm(), default method.args value for r passed to hessian() has been increased to 16 (while this slows things down a bit, this appears to improve the accuracy of the numerical approximation to the Hessian, especially when tau^2 is close to 0)
• the various forest() and addpoly() functions now have a new argument called width, which provides manual control over the width of the annotation columns; this is useful when creating complex forest plots with a monospaced font and we want to ensure that all annotations are properly lined up at the decimal point
• the annotations created by the various forest() and addpoly() functions are now a bit more compact by default
• more flexible efac argument in the various forest() functions
• trailing zeros in the axis labels are now dropped in forest and funnel plots by default; but trailing zeros can be retained by specifying a numeric (and not an integer) value for the digits argument
• added funnel.default(), which directly takes as input a vector with the observed effect sizes or outcomes and the corresponding sampling variances, standard errors, and/or sample sizes
• added plot.profile.rma(), a plot method for objects returned by the profile.rma.uni() and profile.rma.mv() functions
• simplified baujat.rma.uni(), baujat.rma.mh(), and baujat.rma.peto() to baujat.rma(), which now handles objects of class rma.uni, rma.mh, and rma.peto
• baujat.rma() gains argument symbol for more control over the plotting symbol
• labbe() gains a grid argument
• more logical placement of labels in qqnorm.rma.uni(), qqnorm.rma.mh(), and qqnorm.rma.peto() functions (and more control thereof)
• qqnorm.rma.uni() gains lty argument
• added gosh.rma() and plot.gosh.rma() for creating GOSH (i.e., graphical display of study heterogeneity) plots based on Olkin et al. (2012)
• in the (rare) case where all observed outcomes are exactly equal to each other, test="knha" (i.e., knha=TRUE) in rma() now leads to more appropriate results
• updated datasets so those containing precomputed effect size estimates or observed outcomes are already declared to be escalc objects
• added new datasets (dat.egger2001 and dat.li2007) on the effectiveness of intravenous magnesium in acute myocardial infarction
• methods package is now under Depends (in addition to Matrix), so that rma.mv(..., sparse=TRUE) always works, even under Rscript
• some general code cleanup
• added more tests (and used a more consistent naming scheme for tests)

• due to more stringent package testing, it is increasingly difficult to ensure that the package passes all checks on older versions of R; from now on, the package will therefore require, and be checked under, only the current (and the development) version of R
• added graphics, grDevices, and methods to Imports (due to recent change in how CRAN checks packages)
• the struct argument for rma.mv() now also allows for "ID" and "DIAG", which are identical to the "CS" and "HCS" structures, but with the correlation parameter fixed to 0
• added robust() for (cluster) robust tests and confidence intervals for rma.uni and rma.mv models (this uses a robust sandwich-type estimator of the variance-covariance matrix of the fixed effects along the lines of the Eicker-Huber-White method)
• confint() now works for models fitted with the rma.mv() function; for variance and correlation parameters, the function provides profile likelihood confidence intervals; the output generated by the confint() function has been adjusted in general to make the formatting more consistent across the different model types
• for objects of class rma.mv, profile() now provides profile plots for all (non-fixed) variance and correlation components of the model when no component is specified by the user (via the sigma2, tau2, rho, gamma2, or phi arguments)
• for measure="MD" and measure="ROM", one can now choose between vtype="LS" (the default) and vtype="HO"; the former computes the sampling variances without assuming homoscedasticity, while the latter assumes homoscedasticity
• multiple model objects can now be passed to the fitstats(), AIC(), and BIC() functions
• check for duplicates in the slab argument is now done *after* any subsetting is done (as suggested by Michael Dewey)
• rma.glmm() now again works when using add=0, in which case some of the observed outcomes (e.g., log odds or log odds ratios) may be NA
• when using rma.glmm() with model="CM.EL", the saturated model (used to compute the Wald-type and likelihood ratio tests for the presence of (residual) heterogeneity) often fails to converge; the function now continues to run (instead of stopping with an error) and simply omits the test results from the output
• when using rma.glmm() with model="CM.EL" and inversion of the Hessian fails via the Choleski factorization, the function now makes another attempt via the QR decomposition (even when this works, a warning is issued)
• for rma.glmm(), BIC and AICc values were switched around; corrected
• more use of suppressWarnings() is made when functions repeatedly need to fit the same model, such as cumul(), influence(), and profile(); that way, one does not get inundated with the same warning(s)
• some (overdue) updates to the documentation

Older updates are archived here.