ml.igls: IGLS and RIGLS Iterative Algorithms for mixmeta Models
In mixmeta: An Extended Mixed-Effects Framework for Meta-Analysis

Description Usage Arguments Details Value Note Author(s) References See Also

These functions implements (restricted) iterative generalized least squares (IGLS and RIGLS) algorithms for (restricted) maximum likelihood estimators for random-effects meta-analytical models. They are meant to be used internally and not directly run by the users.

ml.igls(Psi, Xlist, Zlist, ylist, Slist, nalist, rep, k, q, nall, const, bscov,
  fix, control)

reml.rigls(Psi, Xlist, Zlist, ylist, Slist, nalist, rep, k, q, nall, const, bscov,
  fix, control)

igls.iter(Psi, Qlist, Xlist, Zlist, ylist, Slist, nalist, rep, k, q, bscov,
  fix, control)

rigls.iter(Psi, Qlist, Xlist, Zlist, ylist, Slist, nalist, rep, k, q, bscov,
  fix,  control)

Assuming a meta-analysis or meta-regression based on n units aggregated within m (outer-level) groups, k outcomes, p fixed-effects predictors, and q random-effects predictors:

`Psi`	a matrix (or a list of matrices for multilevel models) representing the initial estimate of the random-effects (co)variance matrix.
`Xlist`	a m-dimensional list of group-specific design matrices for the fixed-effects part of the model. Rows corresponding to missing outcomes have been excluded.
`Zlist`	a m-dimensional list of group-specific design matrices for the random-effects part of the model. Each element of this list represents a list of matrices correponding to the (optionally multiple) grouping levels of random effects. In each matrix, rows corresponding to missing outcomes have been excluded.
`Qlist`	a m-dimensional list of group-specific design matrices mapping the random-effects parameters to be estimated in `Psi`. See references below for details.
`ylist`	a m-dimensional list of group-specific vectors of estimated outcomes. Entries corresponding to missing outcomes have been excluded.
`Slist`	a m-dimensional list of within-group (co)variance matrices of estimated outcomes. Rows and columns corresponding to missing outcomes have been excluded.
`nalist`	a m-dimensional list of group-specific logical vectors, identifying missing outcomes.
`rep`	matrix with m rows where each column identifies the number of repetitions (number of groups) for each grouping level. The first column (outer level) is by definition a vector of 1's.
`k, q, nall`	number of outcomes, number of random-effects predictors (including the intercept), total number of observations (excluding missing), respectively. While usually all are scalars, in the case of multilevel models `q` can be a numeric vector representing the number of predictors for each level.
`const`	value of the constant to be included in the (restricted) likelihood, therefore not computed in the iterative algorithms.
`bscov`	a character vector defining the structure of the (co)variance matrix for each level or random effects. See `mixmeta`.
`fix`	a matrix (or optionally a list of matrices for multilevel models) defining the fixed components of the random-effects part of the model. See `mixmeta.control` for details.
`control`	list of parameters for controlling the fitting process, usually internally set to default values by `mixmeta.control`.

These functions are called internally by the fitting functions mixmeta.ml and mixmeta.reml to perform (R)IGLS optimization algorithms for estimating random-effects meta-analytical models.

These estimators are not sensitive to the choice of the starting values, and quickly converge to the vicinity of the (restricted) maximum likelihood. The starting values in Psi are therefore defined by default as a matrix (or matrices) with a diagonal form and 0.001 variances, or otherwise selected by the user in the control argument of mixmeta (see mixmeta.control).

The functions ml.igls and reml.rigls first produce a design matrix that maps the entries of Psi, and then call iter.igls and iter.rigls, respectively, to obtain updated results at each iteration following a (R)IGLS procedure described in Goldstein and colleagues (1992). Convergence is assessed as (lack of) changes in Psi. Positive semi-definiteness is forced by setting the negative eigenvalues of the estimated matrix to a value close to 0 at each iteration (see control).

The functions ml.igls and reml.rigls return an intermediate list object, with components corresponding to the estimated random-effects (co)variance matrix (or list of matrices), its parameters, the maximum (restricted) log-likelihood value, an indicator of convergence, and the number of iterations. These are then re-processed, with other components added later within other functions to finalize an object of class "mixmeta" (see mixmetaObject). The functions iter.igls and iter.rigls return an updated version of Psi.

As stated earlier, these functions are called internally by mixmeta.ml and mixmeta.reml, and are not meant to be used directly. In particular, their code does not contain any check on the arguments provided, which are expected in specific formats. They are however exported in the namespace and documented for completeness.

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

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

Goldstein H (1992). Efficient computational procedures for the estimation of parameters in multilevel models based on iterative generalized least squares. Computational Statistics \& Data Analysis. 13(1):63–71.

Goldstein H (1986). Multilevel mixed linear model analysis using iterative generalized least squares. Biometrika. 73(1):43–56.

Goldstein H (1989). Restricted unbiased iterative generalized least-squares estimation. Biometrika. 76(3):622–623.

See mixmeta.fit and mixmeta.ml for additional info on the fitting procedures. See mixmeta.control to determine specific parameters of the fitting procedures. See mixmetaCovStruct for (co)variance structures. See mixmeta-package for an overview of the package and modelling framework.