spaMM (version 2.2.0)

fitme: Fitting function for fixed- and mixed-effect models with GLM response.

Description

This is a common interface for fitting most models that spaMM can fit, therefore substituting to corrHLfit, HLCor and HLfit. Whene possible, it uses generic optimization methods for estimating all dispersion parameters, rather than the general, but often slow, default method in HLfit. Random-slope models are not yet handled by this function. Currently it is fast for some models and slow for others, with few general guidance except that fitme should generally be faster than the alternative fitting functions for large data sets when the residual variance model is a single constant term (no structured dispersion).

Usage

fitme(formula, data, family = gaussian(), init = list(), fixed = list(), 
      lower = list(), upper = list(), resid.model = ~1, init.HLfit = list(), 
      control = list(), control.dist = list(), method = "ML", 
      HLmethod = method, processed = NULL, ...)

Arguments

formula

Either a linear model formula (as handled by various fitting functions) or a predictor, i.e. a formula with attributes (see Predictor and examples below). See Details in spaMM for allowed terms in the formula.

data

A data frame containing the variables in the response and the model formula.

family

Either a family or a multi value.

init

An optional list of initial values for correlation and/or dispersion parameters and/or response family parameters, e.g. list(rho=1,nu=1,lambda=1,phi=1) where rho and nu are parameters of the Mat<U+00E9>rn family (see Matern), and lambda and phi are dispersion parameters (see Details in spaMM for the meaning of these parameters). All are optional, but giving values for a dispersion parameter changes the ways it is estimated (see Details). rho may be a vector (see make_scaled_dist) and, in that case, it is possible that some or all of its elements are NA, for which corrHLfit substitute automatically determined values.

fixed

A list similar to init, but specifying fixed values of the parameters not estimated.

lower

An optional list of values of parameters specified through init.corrHLfit, used as lower values in calls to optim. See Details for default values.

upper

Same as lower, but upper values.

resid.model

See identically named HLfit argument.

init.HLfit

See identically named HLfit argument.

control

A list of control parameters, with two possible elements:

  • $nloptr, itself a list of control parameters to be copied in the opts argument of nloptr. Default controls are given by spaMM.getOption('nloptr')

  • $refit, a boolean, or a list of booleans with possible elements $phi and $lambda. If either element is set to TRUE, then the corresponding parameters are refitted by the internal HLfit methods (see Details). If $refit is TRUE, all phi and lambda parameters are refit. By default none of them is refitted.

control.dist

See control.dist in HLCor

method, HLmethod

"ML" or "REML". "ML" is the default, in contrast to "REML" for the HLmethod argument of other fitting functions. Other possible values of HLfit's HLmethod argument are handled and should give results close to the other fitting methods with the same HLmethod argument, the most notable exception being PQL/L for binary response data, as fitme does not take into account the specific way leverages are computed in PQL/L.

processed

For programming purposes, not documented.

Optional arguments passed to HLCor, HLfit or designL.from.Corr, for example the distMatrix argument of HLCor.

Value

The return value of an HLCor or an HLfit call, with additional attributes. The HLCor call is evaluated at the estimated correlation parameter values. These values are included in the return object as its $corrPars member. The attributes added by fitme include the original call of the function (which can be retrived by getCall(<fitted object>), and information about the optimization call within fitme.

Details

fitme uses nloptr for optimization, where corrHLfit uses optim.

By default corrHLfit initiates optimization with the best of a grid of parameter values, while fitme performs no such grid search for initial value. The grid search may help find a better maximum (as is the case in the toy examples based on the blackcap data set), but may as well trap the function in an inferior local maximum.

For phi and lambda, fitme does not use the internal fitting methods of HLfit. The latter methods are well suited for structured dispersion models, but require the computation of the so-called leverages, which can be slow. However, they also provide some more information such as the “cond. SE” (about which see warning in Details of HLfit). To obtain such information from a fitme call, use the control$refit argument (see Example).

Examples

Run this code
# NOT RUN {
## Example with 'refit'
# We simulate Gamma deviates with mean mu=3 and variance=2, 
#  ie. phi= var/mu^2= 2/9 in the (mu, phi) parametrization of a Gamma 
#  GLM; and shape=9/2, scale=2/3 in the parametrisation of rgamma().
#  Note that phi is not equivalent to scale: 
#  shape = 1/phi and scale = mu*phi.
set.seed(123)
gr <- data.frame(y=rgamma(100,shape=9/2,scale=2/3))
fitme(y~1,data=gr,family=Gamma(log),control=list(refit=list(phi=TRUE)))

## see help("COMPoisson"), help("negbin"), help("Loaloa"), etc., for further examples.
# }

Run the code above in your browser using DataCamp Workspace