lmeControl {nlme} | R Documentation

## Specifying Control Values for lme Fit

### Description

The values supplied in the `lmeControl()` call replace the defaults, and a `list` with all settings (i.e., values for all possible arguments) is returned. The returned list is used as the `control` argument to the `lme` function.

### Usage

    lmeControl(maxIter = 50, msMaxIter = 50, tolerance = 1e-6, niterEM = 25,
               msMaxEval = 200,
    	   msTol = 1e-7, msVerbose = FALSE,
               returnObject = FALSE, gradHess = TRUE, apVar = TRUE,
    	   .relStep = .Machine$double.eps^(1/3), minAbsParApVar = 0.05,
               opt = c("nlminb", "optim"),
    	   optimMethod = "BFGS", natural = TRUE,
    	   sigma = NULL, ...)

### Arguments

`maxIter` | maximum number of iterations for the `lme` optimization algorithm. Default is `50`.
`msMaxIter` | maximum number of iterations for the optimization step inside the `lme` optimization. Default is `50`.
`tolerance` | tolerance for the convergence criterion in the `lme` algorithm. Default is `1e-6`.
`niterEM` | number of iterations for the EM algorithm used to refine the initial estimates of the random effects variance-covariance coefficients. Default is `25`.
`msMaxEval` | maximum number of evaluations of the objective function permitted for nlminb. Default is `200`.
`msTol` | tolerance for the convergence criterion on the first iteration when `optim` is used. Default is `1e-7`.
`msVerbose` | a logical value passed as the `trace` argument to `nlminb` or `optim`. Default is `FALSE`.
`returnObject` | a logical value indicating whether the fitted object should be returned when the maximum number of iterations is reached without convergence of the algorithm. Default is `FALSE`.

`gradHess`

a logical value indicating whether numerical gradient vectors and Hessian matrices of the log-likelihood function should be used in the internal optimization. This option is only available when the correlation structure (`corStruct`) and the variance function structure (`varFunc`) have no "varying" parameters and the `pdMat` classes used in the random effects structure are `pdSymm` (general positive-definite), `pdDiag` (diagonal), `pdIdent` (multiple of the identity), or `pdCompSymm` (compound symmetry). Default is `TRUE`.

`apVar` | a logical value indicating whether the approximate covariance matrix of the variance-covariance parameters should be calculated. Default is `TRUE`.
`.relStep` | relative step for numerical derivatives calculations. Default is `.Machine$double.eps^(1/3)`.
`opt` | the optimizer to be used, either `"nlminb"` (the default) or `"optim"`.
`optimMethod` | character - the optimization method to be used with the `optim` optimizer. The default is `"BFGS"`. An alternative is `"L-BFGS-B"`.
`minAbsParApVar` | numeric value - minimum absolute parameter value in the approximate variance calculation. The default is `0.05`.
`natural` | a logical value indicating whether the `pdNatural` parametrization should be used for general positive-definite matrices (`pdSymm`) in `reStruct`, when the approximate covariance matrix of the estimators is calculated. Default is `TRUE`.
`sigma` | optionally a positive number to fix the residual error at. If `NULL`, as by default, or `0`, sigma is estimated.
`...` | further named control arguments to be passed, depending on `opt`, to `nlminb` (those from `abs.tol` down) or `optim` (those except `trace` and `maxit`; `reltol` is used only from the second iteration).

### Value

a list with components for each of the possible arguments.

### Author(s)

José Pinheiro and Douglas Bates bates@stat.wisc.edu; the `sigma` option: Siem Heisterkamp and Bert van Willigen.

### See Also

`lme`, `nlminb`, `optim`

### Examples

    # decrease the maximum number iterations in the ms call and
    # request that information on the evolution of the ms iterations be printed
    str(lCtr <- lmeControl(msMaxIter = 20, msVerbose = TRUE))
    ## This should always work:
    do.call(lmeControl, lCtr)

[Package nlme version 3.1-131 Index]