spaMM (version 4.7.0)

resid.model: Structured dispersion models

Description

The resid.model argument of fitting functions can be used to specify a model for a residual-dispersion parameter of various response families, that is, either
(1) the \(\phi\) parameter of the gaussian and Gamma GLM families;
(2a) the dispersion parameter of some other GLM families, such as the shape parameter of the negbin1 and negbin2 families; or
(2b) the dispersion parameter of some other (non-GLM) distribution families, such as the precision parameter of the beta family.

This documentation is more specifically for case (2). Case (1) is more specifically documented as phi-resid.model.

In case (2) the model for the dispersion parameter is constrained as a fixed-effect model, of the form
dispersion parameter = exp(X\(\beta\)+offset),
and specified using the standard formula syntax. Random effects cannot be included, in contrast to dispersion models for case (1).

Usage

# 'resid.model' argument of fitme() and fitmv()

Value

The fit results for the residual model are accessible through the summary and various extractors. In particular, the get_fittedPars extractor will by default include in its return value the rdisPars element, which is here the vector of fitted \(\beta\) coefficients. residVar(., which="fam_parm") will return the vector of fitted values of the dispersion parameter.

Arguments

The resid.model for case (2) is simply a formula (without left-hand side) for the logarithm of the dispersion parameter. Fixed \(\beta\) values can be specified through the rdisPars element of the fixed argument in the fitme call (or through the fixed argument of each submodel of a fitmv call). Likewise, initial values can be specified through the init argument.

Details

In case (2) a fixed “heteroscedastic” model can also be specified directly through the family specification, e.g., family=negbin1(shape=<vector>) where the vector has the length of the response vector, but this may not be suitable if the model is to be used for prediction purposes (where the residual-dispersion model should be specified in such a way that one can “predict” new dispersion values from it).

The design matrix for the specified model is internally rescaled to avoid numerical problems. That means that there is no need to rescale the predictor variable, even if it tends to take large (cf ‘population’ variable in the Examples) of small values (this is also true for fixed-effect predictors of the mean-response model).

Examples

data("scotlip")
if (spaMM.getOption("example_maxtime")>3) {
(toyfit <- fitme(cases~1+(1|id),family=negbin1(), data=scotlip, 
                 resid.model = ~ population))
}

# => This toy example is a bit challenging to fit because the data set is small and 
# individual-level variation is here described both by a random effect 
# and by a two-parameter negbin1 residual variation. Such fits might often stop 
# at a local maximum of the logLik (although there is no evidence
# that this is presently the case).