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

In spaMM: Mixed-Effect Models, with or without Spatial Random Effects

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, from linear models to mixed models with non-gaussian random effects, except multivariate-response models (see fitmv for the latter). By default, it uses ML rather than REML (differing in this respect from the other fitting functions corrHLfit, HLCor and HLfit). It tends to use “outer optimization”, i.e., generic optimization methods for estimating all dispersion parameters, rather than the iterative methods implemented in HLfit (see Details).

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, nb_cores = NULL, objective = NULL, 
      weights.form = NULL, ...)
# '...' may notably include arguments 
#     'rand.family', 'control.HLfit', and 'verbose' 
# (see HLfit() documentation for them), 
#     'covStruct', 'corrMatrix', 'adjMatrix' and 'distMatrix' 
# (see HLCor() documentation for them).

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 response family or a multi value.
init	An optional list of initial values for correlation and/or dispersion parameters for distribution family. The general syntax is the same as for the fixed argument, and a simplified syntax may be used when it is not ambiguous. E.g., list(rho=1,nu=1,lambda=1,phi=1) can be used to fix the rho and nu parameters of the Matérn family (see Matern), as well as the dispersion parameters denoted lambda and phi in spaMM (see Examples below, and in the additional inits documentation). All initial values are optional, but giving values for a dispersion parameter changes the ways it is estimated (see Details and Examples). 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 fitme substitutes automatically determined initial values.
fixed	A list similar to init, but specifying fixed values of the parameters not estimated. See fixed for further information; and keep in mind that fixed fixed-effect coefficients can be passed as the etaFix argument as part of the ‘...’.
lower, upper	optional (sub)lists of values of parameters, in the same format as init, used to control lower or upper values in calls to nloptr or similar generic numerical optimization functions. See optimBounds for further information.
resid.model	See identically named HLfit argument.
init.HLfit	See identically named HLfit argument.
control.dist	See control.dist in HLCor
method, HLmethod	Character: the fitting method to be used, such as "ML", "REML" or "PQL/L". "ML" is the default, in contrast to "REML" for HLfit, HLCor and corrHLfit. Other possible values of HLfit's method argument are handled. method=c(<"ML" or "REML">,"exp") can be distinctly useful for slow fits of models with Gamma(log) family (see method).
weights.form	Specification of prior weights by a one-sided formula: use weights.form = ~ pw instead of prior.weights = pw. The effect will be the same except that such an argument, known to evaluate to an object of class "formula", is suitable to enforce safe programming practices (see good-practice).
control	A list of (rarely needed) control parameters, with possible elements: refit, a boolean, or a list of booleans with possible elements phi, lambda and ranCoefs. If either element is set to TRUE, then the corresponding parameters are refitted by the internal HLfit methods (see Details), unless these methods were already selected for such parameters in the main fitting step. If refit is a single boolean, it affects all parameters. By default no parameter is refitted. optimizer, the numerical optimizer, specified as a string and whose default is controlled by the global spaMM option "optimizer". Possible values are "nloptr", "bobyqa", "L-BFGS-B" and ".safe_opt", whose meanings are detailed in the documentation for the optimizer argument of spaMM.options. Better left unchanged unless suspect fits are obtained. nloptr, itself a list of control parameters to be copied in the opts argument of nloptr. Default value is given by spaMM.getOption('nloptr') and possibly other global spaMM options. Better left unchanged unless you are ready to inspect source code. bobyqa, optim, lists of controls similar to nloptr but for methods "bobyqa" and "L-BFGS-B", respectively.
nb_cores	For development purpose, not documented.
processed	For programming purpose, not documented.
objective	For development purpose, not documented.
...	Optional arguments, notably those listed in the comments of the Usage section above, passed to (or operating as if passed to) either HLfit or HLCor or mat_sqrt.

Details

For approximations of likelihood, see method. For the possible structures of random effects, see random-effects. For the different results that may be obtained by using the init argument to select “inner”- vs.“outer”-estimation methods for dispersion parameters \lambda and \phi, and the availability of standard errors for these estimates, see inner-vs-outer.

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.

Examples

## Examples with Matern correlations
## A likelihood ratio test based on the ML fits of a full and of a null model.
 data("blackcap")
 (fullfit <- fitme(migStatus ~ means+ Matern(1|longitude+latitude),data=blackcap) )
 (nullfit <- fitme(migStatus ~ 1 + Matern(1|longitude+latitude),data=blackcap)) 
 ## p-value:
 1-pchisq(2*(logLik(fullfit)-logLik(nullfit)),df=1)

# See help("spaMM")" for examples of conditional 
# autoregressive model and of non-spatial models. 
# see help("COMPoisson"), help("negbin"), help("Loaloa"), help("inner-vs-outer"), 
# and many other documentation pages, for further examples.

spaMM documentation built on Sept. 10, 2026, 1:07 a.m.