mixmeta.control {mixmeta}

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 <[e-mail]> and Francesco Sera <[e-mail]>

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].

See Also

See mixmeta. See also glm.control. See the help pages of the related fitting functions for details on each parameter. See mixmeta-package for an overview of this modelling framework.

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))