spaMM (version 4.6.1)

residVar: 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 return values for which = "var" and "phi" include prior weights, if any.

Usage

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

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.

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.

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

## residVar optional arguments:

# 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

## Prior weights in residVar() vs. get_residVar():
  data(wafers)
  spfit <- fitme(I(y/1000)~X1, family=gaussian(), data=wafers)
  residVar(spfit)[1] #      0.015...
  get_residVar(spfit)[1] #  0.015...
  
  spfit2 <- fitme(I(y/1000)~X1, family=gaussian(), data=wafers, prior.weights=rep(2,198))
  head(residVar(spfit2)) #     0.015... = phi/prior.weights
  head(get_residVar(spfit2)) # 0.030... = phi
  
  spfit3 <- fitme(I(y/1000)~X1, family=gaussian(), data=wafers, fixed=list(phi=2),
                  prior.weights=rep(2,198))
  residVar(spfit3)[1] #     1 = phi/prior.weights
  get_residVar(spfit3)[1] # 2 = phi