mixmeta.control: Ancillary Parameters for Controlling the Fit in mixmeta...
In mixmeta: An Extended Mixed-Effects Framework for Meta-Analysis

mixmeta.control

R Documentation

Ancillary Parameters for Controlling the Fit in mixmeta Models

Description

This internal function sets the parameter options used for fitting meta-analytical models, commonly to pre-specified default values. It is usually internally called by mixmeta.

Usage

mixmeta.control(optim=list(), showiter=FALSE, maxiter=100, initPsi=NULL, Psifix=NULL,
  Scor=NULL, addSlist=NULL, inputna=FALSE, inputvar=10^4, loglik.iter="hybrid",
  igls.inititer=10, hessian=FALSE, vc.adj=TRUE, reltol=sqrt(.Machine$double.eps),
  checkPD=NULL, set.negeigen=sqrt(.Machine$double.eps))

Arguments

`optim`	list of parameters passed to the `control` argument of the function `optim`, which performs the `quasi-Newton optimization` in likelihood-based random-effects models. See `optim` for the list of arguments. See Details for additional info.
`showiter`	logical. If `TRUE`, the progress of iterative optimization is shown.
`maxiter`	positive interger value. Maximum number of iterations in methods involving optimization procedures.
`initPsi`	either a matrix or a vector of its lower triangular elements (with diagonal, taken by column), or optionally a named list with one or more of such objects. Used as starting values of random-effects parameters in likelihood-based optimization routines. See Details.
`Psifix`	either a matrix or a vector of its lower triangular elements (with diagonal, taken by column), or optionally a named list with one or more of such objects. Used to define fixed parts of the random-effects `(co)variance structures`. See Details.
`Scor`	either a scalar, vector or matrix representing the within-unit correlation(s) to be inputted when the covariances are not provided in multivariate models, and ignored if they are. See `inputcov`.
`addSlist`	a list of `m` matrices for the (outer-level) groups of units defining the (known) error (co)variance structure, when this cannot be passed through the argument `S` of `mixmeta`. See Details.
`inputna`	logical. If missing values must be internally inputted. To be used with caution. See `inputna`.
`inputvar`	multiplier for inputting the missing variances, to be passed as an argument to `inputna`.
`loglik.iter`	iterative scheme used in in likelihood-based optimization routines. Options are `"hybrid"`, `"newton"`, and `"igls"` or `"rigls"`. See `mixmeta.ml`.
`igls.inititer`	number of iterations of the (restricted) iterative generalized least square algorithm when used in the initial phase of hybrid optimization procedure of likelihood-based estimators. See `mixmeta.ml`.
`hessian`	logical. If `TRUE`, the Hessian matrix of the parameters estimated in the optimization process is computed and returned. Only applicable to likelihood-based estimation methods. For details, see the info provided in the help pages of the `optimizations algorithms` and `(co)variance structures`.
`vc.adj`	logical. If `TRUE`, an adjustement to the way the marginal variance part is computed in the (co)variance components estimator is applied in the variance components estimator. See `mixmeta.vc`.
`reltol`	relative convergence tolerance in methods involving optimization procedures. The algorithm stops if it is unable to reduce the value by a factor of `reltol * (abs(val) + reltol)` at a step.
`checkPD`	logical. Determines if the semi-positiveness of within-unit error or random-effects (co)variance matrices must be checked.
`set.negeigen`	positive value. Value to which negative eigenvalues are to be set in estimators where such method is used to force semi-positive definiteness of the estimated between-study (co)variance matrix.

Details

This function has default values for most of the arguments, some of them set internally. Non-default values are passed through the control argument of mixmeta. Many arguments refer to specific fitting procedures. See the help page of the related estimator for details.

The function automatically sets non-default values for some control arguments for optim, unless explicitly set in the list passed to it. Specifically, the function selects fnscale=-1, maxit=maxiter and reltol=reltol, where the latter two are specified by other arguments of this function.

The arguments initPsi and Psifix are used to provide information for estimation procedures of the random-effects parameters in likelihood-based methods. Specifically, the former is used to choose non-default starting values (see mixmeta.ml), and the latter for defining the fixed (known) part of specific (co)variance structures. In multilevel models, these arguments must be lists with named components referring to one or more levels of grouping defined by the argument random of mixmeta.

The argument addSlist can be used to define more complex (known) error structures of the outcome(s) that are usually provided through the argument S of mixmeta as within-unit variances (or (co)variance matrices for multivariate models). This can be useful when these error structures spans multiple units (rows), and the between-unit correlation cannot be defined through S, for instance in dose-response meta-analysis (see examples in mixmeta). Note that this information is passed internally after the data have be re-ordered following the grouping defined by random in mixmeta, and this should be consistent in addSlist. Specifically, the grouping variables are assumed as factors and therefore the groups are taken in alphabetical/numeric order. It is suggested to re-order the data according to this order of the groups before fitting the model, so to ensure consistency between the grouped data and addSlist.

Value

A list with components named as the arguments.

Note

The function is expected to be extended and/or modified at every release of the package mixmeta. It is strongly suggested to check the arguments of this function at every release.

Author(s)

Antonio Gasparrini <antonio.gasparrini@lshtm.ac.uk> and Francesco Sera <francesco.sera@lshtm.ac.uk>

References

Sera F, Armstrong B, Blangiardo M, Gasparrini A (2019). An extended mixed-effects framework for meta-analysis.Statistics in Medicine. 2019;38(29):5429-5444. [Freely available here].

Examples

# PRINT THE ITERATIONS (SEE ?optim) AND CHANGE THE DEFAULT FOR STARTING VALUES
mixmeta(cbind(PD,AL) ~ pubyear, S=berkey98[5:7], data=berkey98,
  control=list(showiter=TRUE, igls.inititer=20))

# INPUT THE CORRELATION
mixmeta(cbind(y1,y2), S=cbind(V1,V2), data=p53, control=list(Scor=0.5))

# FIX (PARTS OF) THE RANDOM-EFFECTS (CO)VARIANCE MATRIX
y <- as.matrix(smoking[11:13])
S <- as.matrix(smoking[14:19])
mixmeta(y, S, bscov="prop", control=list(Psifix=diag(3)+1))

mixmeta documentation built on Nov. 5, 2025, 7:39 p.m.