updates

### Table of Contents

## Package Updates

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

### Version 4.2-0 (2023-05-08)

- 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

### Version 4.0-0 (2023-03-19)

- 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

### Version 3.8-1 (2022-08-26)

`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

### Version 3.4-0 (2022-04-21)

- 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

### Version 3.0-2 (2021-06-02)

- 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 2.4-0 (2020-03-19)

- 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

### Version 2.1-0 (2019-05-13)

- 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`hcol`

argument 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

### Older Versions

Older updates are archived here.

updates.txt ยท Last modified: 2023/05/09 06:25 by Wolfgang Viechtbauer