# The metafor Package

A Meta-Analysis Package for R

### Site Tools

 — updates [2019/05/25 18:04] (current) Line 1: Line 1: + ===== Package Updates ===== + + On this page, you can find a description of the (recent) updates to the metafor package. Older updates are archived [[updates_old|here]]. + + ==== 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 credibility 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 + + ==== Version 2.0-0 (2017-06-22) ==== + + * 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 location-scale model + * 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 + + ==== 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 ==== + + Older updates are archived [[updates_old|here]].