residVar: Residual variance extractor

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

Residual variance extractor

Description

Extracts from a fit object the residual variance or, depending on the which argument, a family dispersion parameter phi (which is generally not the residual variance itself except for gaussian-response models without prior weights), or a vector of values of the dispersion parameter, or further information about the residual variance model.

For gaussian and Gamma response families, the which = "var" and "phi" cases are distinctive as prior weights, if any, are included in the return value.

Usage

residVar(object, which = "var", submodel = NULL, newdata = NULL)

Arguments

object	An object of class HLfit, as returned by the fitting functions in spaMM.
which	Character: "var" for the fitted residual variances, "phi" for the fitted phi values, "fam_parm" for the dispersion parameter of COMPoisson, negbin1, negbin2, beta_resp or betabin families, "fit" for the fitted residual model (a GLM or a mixed model for residual variances, if not a simpler object), and "family" or "formula" for such properties of the residual model.
submodel	integer: the index of a submodel, if object is a multivariate-response model fitted by fitmv. This argument is mandatory for all which values except "var" and "phi".
newdata	Either NULL, a matrix or data frame, or a numeric vector. See predict.HLfit for details.

Value

which="var" (default) and "phi" always return a vector of residual variances (or, alternatively, phi values) of length determined by the newdata and submodel arguments.
which="fit" returns an object of class HLfit, glm, or a single scalar depending on the residual dispersion model (which="fit" is the option to be used to extract the scalar phi value).
which="fam_parm" returns either NULL (for families without such a parameter), a vector (if a resid.model was specified for relevant families), a single scalar (relevant families, without resid.model), or a list of such objects (for multivariate-response models).
Other which values return an object of class family or formula as expected.

See Also

get_residVar is a alternative extractor of residual variances with different features inherited from get_predVar. In particular, it is more suited for computing the residual variances of new realizations of a fitted model, not accounting for prior weights used in fitting the model (basic examples of using the IsoriX package provide a context where this is the appropriate design decision). By contrast, residVar aims to account for prior weights.

Examples

# data preparation: simulated trivial life-history data
set.seed(123)
nind <- 20L
u <- rnorm(nind)
lfh <- data.frame(
  id=seq_len(nind), id2=seq_len(nind), 
  feco= rpois(nind, lambda = exp(1+u)), 
  growth=rgamma(nind,shape=1/0.2, scale=0.2*exp(1+u)) # mean=exp(1+u), var= 0.2*mean^2
)
# multivariate-response fit                  
fitlfh <- fitmv(submodels=list(list(feco ~ 1+(1|id), family=poisson()),
                               list(growth ~ 1+(1|id), family=Gamma(log))),
                data=lfh)
#
residVar(fitlfh)
residVar(fitlfh, which="phi") # shows fixed phi=1 for Poisson responses
residVar(fitlfh, submodel=2)
residVar(fitlfh, which="family", submodel=2)
residVar(fitlfh, which="formula", submodel=2)
residVar(fitlfh, which="fit", submodel=2) # Fit here characterized by a single scalar

spaMM documentation built on Aug. 30, 2023, 1:07 a.m.