Differences

This shows you the differences between two versions of the page.

--- updates [2021/06/02 15:46] – Wolfgang Viechtbauer
+++ updates [2023/03/20 08:27] – Wolfgang Viechtbauer
@@ Line 3: / Line 3: @@
 On this page, you can find a description of the (recent) updates to the metafor package. Older updates are archived [[updates_old|here]].
-==== Version 3.0-0 (2021-06-02) ====
+==== Version 4.0-0 (2023-03-19) ====
-  * the metafor package now makes use of the ''mathjaxr'' package to nicely render equations shown in the HTML help pages
+  * 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)
@@ Line 11: / Line 86: @@
   * 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 matries
+  * 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
@@ Line 157: / Line 232: @@
   * 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
+  * renamed ''diagram_metafor.pdf'' vignette to just ''diagram.pdf''
   * minor updates in the documentation
-==== Version 1.9-9 (2016-09-25) ====
-  * 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)
-==== Version 1.9-8 (2015-05-28) ====
-  * 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 Versions ====