The metafor Package

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

• added getmfopt() and setmfopt() functions for getting and setting package options and made some of the options more flexible
• removed argument weighted from fsn() (whether weighted or unweighted averages are used in Orwin's method is now simply determined by whether sampling variances are specified or not); added type="General" to fsn() as a generalization of the Orwin and Rosenberg methods (that allows for a fail-safe N calculation based on a random-effects model); can now pass an rma object to the fsn() function
• further improved the theming of all plots based on the foreground and background colors; within RStudio, plot colors can also be automatically chosen based on the theme (with setmfopt(theme="auto"))
• added additional/optional argument tabfig to the various forest() functions, for easily setting the annosym argument to an appropriate vector for exactly aligning numbers (when using a matching font)
• added (for now undocumented) vccon argument to rma.mv() for setting equality constraints on variance/correlation components
• replace argument in conv.2x2(), conv.delta(), conv.fivenum(), and conv.wald() can now also be a logical
• added summary.matreg() and print.summary.matreg() methods for including additional statistics in the output ($R^2$ and the omnibus test) and added coef.matreg() and vcov.matreg() extractor functions
• formatting functions fmtp(), fmtx(), and fmtt() gain a quote argument, which is set to FALSE by default
• for measures "PCOR", "ZPCOR", "SPCOR", and "ZSPCOR", argument mi in escalc() now refers to the total number of predictors in the regression models (i.e., also counting the focal predictor of interest)
• added measures "R2" and "ZR2" to escalc()
• addpoly.default() and addpoly.rma.predict() gain a constarea argument (for the option to draw the polygons with a constant area)
• plot.rma.uni.selmodel() gains a shade argument (for shading the confidence interval region)
• plot.permutest.rma.uni() gains a legend argument
• vcalc() gains a sparse argument
• aggregate.escalc gains var.names argument
• made the legend argument more flexible in funnel()
• made the append argument more flexible in to.long()
• added a few more transformation functions
• small bug fixes
• added automated visual comparison tests of plots
• improved the documentation a bit

• improved the various plotting functions so they respect par("fg"); as a result, one can now create plots with a dark background and light plotting colors
• also allow two or three values for xlab in the various forest() functions (for adding labels at the ends of the x-axis limits)
• better default choices for xlim in the various forest() functions; also, argument ilab.xpos is now optional when using the ilab argument
• added shade and colshade arguments to the various forest() functions
• the various forest() functions no longer enforce that xlim must be at least as wide as alim
• added link argument to rma.glmm()
• rma.glmm() with measure="OR", model="CM.EL", method="ML" now treats tau^2 values below 1e-04 effectively as zero before computing the standard errors of the fixed effects; this helps to avoid numerical problems in approximating the Hessian; similarly, selmodel() now treats tau^2 values below 1e-04 or min(vi/10) effectively as zero before computing the standard errors
• for measure SMCC, can now specify d-values, t-test statistics, and p-values via arguments di, ti, and pi
• functions that issue a warning when omitting studies due to NAs now indicate how many were omitted
• properly documented the level argument
• added a few more transformation functions
• small bug fixes
• improved the documentation a bit

• added conv.2x2() function for reconstructing the cell frequencies in 2x2 tables based on other summary statistics
• added conv.wald() function for converting Wald-type confidence intervals and test statistics to sampling variances
• added conv.fivenum() function for estimating means and standard deviations from five-number summary values
• added conv.delta() function for transforming observed effect sizes or outcomes and their sampling variances using the delta method
• added emmprep() function to create a reference grid for use with the emmeans() function from the package of the same name
• exposed formatter functions fmtp(), fmtx(), and fmtt()
• package numDeriv moved from Suggests to Depends
• model.matrix.rma() gains asdf argument
• corrected bug in vcalc() (values for obs and type were taken directly as indices instead of using them as identifiers)
• improved efficiency of vif() when sim=TRUE by reshuffling only the data needed in the model matrix; due to some edge cases, the simulation approach cannot be used when some redundant predictors were dropped from the original model; and when redundancies occur after reshuffling the data, the simulated (G)VIF value(s) are now set to Inf instead of NA
• selmodel() gains type='trunc' and type='truncest' models (the latter should be considered experimental)
• added exact="i" option in permutest() (to just return the number of iterations required for an exact permutation test)
• escalc() now provides more informative error messages when not specifying all required arguments to compute a particular measure
• added measures "ZPHI", "ZTET", "ZPB", "ZBIS", and "ZSPCOR" to escalc() (but note that Fisher's r-to-z transformation is not a variance-stabilizing transformation for these measures)
• the variance of measure ZPCOR is now calculated with 1/(ni-mi-3) (instead of 1/(ni-mi-1)), which provides a better approximation in small samples (and analogous to how the variance of ZCOR is calculated with 1/(ni-3))
• as with measure="SMD", one can now also use arguments di and ti to specify d-values and t-test statistics for measures RPB, RBIS, D2ORN, and D2ORL in escalc()
• for measures COR, UCOR, and ZCOR, can now use argument ti to specify t-test statistics in escalc()
• can also specify (two-sided) p-values (of the respective t-tests) for these measures (and for measures PCOR, ZPCOR, SPCOR, and ZSPCOR) via argument pi (the sign of the p-value is taken to be the sign of the measure)
• can also specify (semi-)partial correlations directly via argument ri for measures PCOR, ZPCOR, SPCOR, and ZSPCOR
• when passing a correlation marix to rcalc(), it now orders the elements (columnwise) based on the lower triangular part of the matrix, not the upper one (which is more consistent with what matreg() expects as input when using the V argument)
• optimizers Rcgmin and Rvmmin are now available in rma.uni(), rma.mv(), rma.glmm(), and selmodel()
• improved the documentation a bit

• funnel.default(), funnel.rma(), and regplot.rma() gain slab argument
• vif() was completely refactored and gains reestimate, sim, and parallel arguments; added as.data.frame.vif.rma() and plot.vif.rma() methods
• plot.permutest.rma.uni() function sets the y-axis limits automatically and in a smarter way when also drawing the reference/null distribution and the density estimate
• added possibility to specify a list for btt in anova.rma(); added print.list.anova.rma() to print the resulting object
• added as.data.frame.anova.rma() and as.data.frame.list.anova.rma() methods
• documented the possibility to use an identity link (with link="identity") in rma.uni() when fitting location-scale models (although this will often lead to estimation problems); added solnp() as an additional optimizer for this case
• optimizers nloptr and constrOptim.nl (the latter from the alabama package) are now available in rma.uni() for location-scale models when using an identity link
• added measure SMD1H to escalc()
• for measure="SMD", escalc() now also allows the user to specify d-values and t-test statistics via arguments di and ti, respectively
• aggregate.escalc() gains addk argument
• added (experimental!) support for measures "RR", "RD", "PLN", and "PR" to rma.glmm() (but using these measures will often lead to estimation problems)
• replmiss() gains data argument
• cumul() functions also store data, so that arguments ilab, col, pch, and psize in the forest.cumul.rma() function can look for variables therein
• fixed issue with rendering Rmarkdown documents with metafor output due to the use of a zero-width space

• added misc-models, misc-recs, and misc-options help pages
• added as.data.frame.confint.rma() and as.data.frame.list.confint.rma methods
• permutest() can now also do permutation tests for location-scale models; it also always returns the permutation distributions; hence, argument retpermdist was removed
• added plot.permutest.rma.uni() function to plot the permutation distributions
• simplified regtest(), ranktest(), and tes() to single functions instead of using generics and methods; this way, a data argument could be added
• added vcalc() and blsplit() functions
• robust() gains clubSandwich argument; if set to TRUE, the methods from the clubSandwich package (https://cran.r-project.org/package=clubSandwich) are used to obtain the cluster-robust results; anova.rma() and predict.rma() updated to work appropriately in this case
• results from robust() are no longer printed with print.robust.rma() but with the print methods print.rma.uni() and print.rma.mv()
• anova.rma() now gives a warning when running LRTs not based on ML/REML estimation and gains rhs argument; it also now has a refit argument (to refit REML fits with ML in case the fixed effects of the models differ)
• setting dfs="contain" in rma.mv() automatically sets test="t" for convenience
• elements of rho and phi in rma.mv() are now based on the lower triangular part of the respective correlation matrix (instead of the upper triangular part) for consistency with other functions; note that this is in principle a backwards incompatible change, although this should only be a concern in very special circumstances
• rma.mv() gains cvvc argument (for calculating the var-cov matrix of the variance/correlation/covariance components)
• added measure "MPORM" to escalc() for computing marginal log odds ratios based on marginal 2x2 tables directly (which requires specification of the correlation coefficients in the paired tables for the calculation of the sampling variances via the ri argument)
• added measure "REH" to escalc() for computing the (log transformed) relative excess heterozygosity (to assess deviations from the Hardy-Weinberg equilibrium)
• aggregate.escalc() gains checkpd argument and struct="CS+CAR"
• rma.glmm() now has entire array of optimizers available for model="CM.EL" and measure="OR"; switched the default from optim() with method BFGS to nlminb() for consistency with rma.mv(), rma.uni(), and selmodel.rma.uni()
• rma.glmm() gains coding and cor arguments and hence more flexibility how the group variable should be coded in the random effects structure and whether the random study effects should be allowed to be correlated with the random group effects
• rma.uni() now also provides R^2 for fixed-effects models
• matreg() can now also analyze a covariance matrix with a corresponding V matrix; can also specify variable names (instead of indices) for arguments x and y
• renamed argument nearPD to nearpd in matreg() (but nearPD continues to work)
• plot.profile.rma() gains refline argument
• added addpoly.rma.predict() method
• addpoly.default() and addpoly.rma() gain lty and annosym arguments; if unspecified, arguments annotate, digits, width, transf, atransf, targs, efac, fonts, cex, and annosym are now automatically set equal to the same values that were used when creating the forest plot
• documented textpos and rowadj arguments for the various forest functions and moved the top and annosym arguments to 'additional arguments'
• fixed that level argument in addpoly.rma() did not affect the CI width
• points.regplot() function now also redraws the labels (if there were any to begin with)
• added lbfgsb3c, subplex, and BBoptim as possible optimizer in rma.mv(), rma.glmm(), rma.uni(), and selmodel.rma.uni()
• the object returned by model fitting functions now includes the data frame specified via the data argument; various method functions now automatically look for specified variables within this data frame first
• datasets moved to the `metadat` package (https://cran.r-project.org/package=metadat)
• improved the documentation a bit

• 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

Older updates are archived here.