spaMM (version 1.5.1)

predict: Prediction from a model fit.

Description

Predictions of the response variable, based on given values of the predictor variables for fixed effects, and/or on predicted random effects.

Usage

## S3 method for class 'HLfit':
predict(
                 object,newdata = newX, newX=NULL,coeffs=NULL,re.form= NULL,
                 variances=list(fixef=FALSE, linPred=FALSE, 
                                resid=FALSE, sum=FALSE, cov=FALSE),
                 predVar=variances$linPred,residVar=variances$resid,
                 binding = FALSE,...)

Arguments

object

The return object of an HLfit or similar function.

newdata

Either a matrix or data frame containing all required variables for evaluating fixed and random effects, including an offset. If NULL, the original data are reused. or a numeric vector, which names (if any) are ignored.

newX

equivalent to newdata, available for back-compatibility

coeffs

Precomputed coefficients for the prediction (see Details).

re.form

formula for random effects to include. If NULL, include all random effects; if NA, include no random effects

variances

A list which elements control the computation of different estimated variances. fixef=TRUE will provide the variances of X$\beta$; linPred=TRUE will provide the variance of the linear predictor $\eta$ (see Details);

predVar

(for back-compatibility: variances should now be used) predVar=TRUE corresponds to variances=list(linPred=TRUE), and predVar="Cov" corresponds to variances=list(linPred=TRUE,cov=TRUE).

residVar

(for back-compatibility: variances should now be used) residVar=TRUE corresponds to variances=list(resid=TRUE).

binding

If binding is a character string, the predicted values are bound with the newdata and the result is returned as a data frame. The predicted values column name is the given binding, or a name based on it, if the

...

further arguments passed to or from other methods.

Value

• A matrix or data frame (according to the binding argument), with optionally one or more prediction variance vector or (co)variance matrices as attributes. The further attribute fittedName contains the binding name, if any.

Details

If newdata is NULL, predict only returns the fitted responses, including random effects, from the object. Otherwise it computes new predictions including random effects as far as possible. For spatial random effects it constructs a correlation matrix C between new locations and locations in the original fit. Then it infers the random effects in the new locations as C (L'$)^{-1}$ v (see spaMM for notation). If the predictor is used many times, it may be useful to precompute (L'$)^{-1}$ v and either to provide this vector through the coeffs argument (see Examples), or to include it as member predictionCoeffs of the object. For non-spatial random effects, it checks whether any group (i.e., level of a random effect) in the new data was represented in the original data, and it adds the inferred random effect for this group to the prediction for individuals in this group. predVar is the prediction (co)variance of the linear predictor ($\eta$). It takes into account the uncertainty in estimation of $\beta$, which affects $\eta$ directly through its X$\beta$ component but also through the uncertainty in inferred random effects v in original locations, as the inferred v depends on the inferred $\beta$ (e.g. Harville, 1985). This is extended to GLMMs as described in Gotway and Wolfinger (2003). fixefVar is the (co)variance of X$\beta$, deduced from the asymptotic covariance matrix of $\beta$ estimates. Unobserved levels of non-spatial random effects are handled as follows. In the point prediction of the linear predictor, the expected value of $u$ is assigned to the realizations of $u$ for unobserved groups (this value is 0 in LMMs). Corresponding realizations of $v$ are then deduced using the link function(s) for the random effects (the identity link in LMMs). The same computation is performed in all other models, for good or bad. For prediction covariance, it matters whether a single or multiple new levels are used: see Examples.

References

Gotway, C.A., Wolfinger, R.D. (2003) Spatial prediction of counts and rates. Statistics in Medicine 22: 1415-1432. Harville, D.A. (1985) Decomposition of prediction error. J. Am. Stat. Assoc. 80: 132-138.

Examples

data(blackcap)
fitobject <- corrHLfit(migStatus ~ 1 + Matern(1|latitude+longitude),data=blackcap,
                       ranFix=list(nu=4,rho=0.4,phi=0.05))
predict(fitobject)
predict(fitobject,blackcap) ## same computation, different format 
getDistMat(fitobject)

## same result using precomputed 'coeffs':
coeffs <- predictionCoeffs(fitobject) ## using dedicated extractor function
predict(fitobject,coeffs=coeffs,variances=list(linPred=TRUE)) -> pf
attr(pf,"predVar")


###### handling of unobserved groups
## (1) fit with an additional random effect
grouped <- cbind(blackcap,grp=c(rep(1,7),rep(2,7))) 
fitobject <- corrHLfit(migStatus ~ 1 +  (1|grp) +Matern(1|latitude+longitude),
                       data=grouped,  ranFix=list(nu=4,rho=0.4,phi=0.05))
## (2) comparison of covariance matrices for two types of new data
moregroups <- grouped[1:5,]
rownames(moregroups) <- paste("newloc",1:5,sep="")
moregroups$grp <- rep(3,5) ## all new data belong to an unobserved third group 
cov1 <- attr(predict(fitobject,newdata=moregroups,
                     variances=list(linPred=TRUE,cov=TRUE)),"predVar")
moregroups$grp <- 3:7 ## all new data belong to distinct unobserved groups
cov2 <- attr(predict(fitobject,newdata=moregroups,
                     variances=list(linPred=TRUE,cov=TRUE)),"predVar")
cov1-cov2 ## the expected off-diagonal covariance due to the common group in the first fit.

## Effects of numerically singular correlation matrix C:
fitobject <- corrHLfit(migStatus ~ 1 + Matern(1|latitude+longitude),data=blackcap,
                       ranFix=list(nu=10,rho=0.001)) ## numerically singular C
predict(fitobject) ## predicted mu computed as X beta + L v 
predict(fitobject,newdata=blackcap) ## predicted mu computed as X beta + C