corrHLfit: Fits a mixed model, typically a spatial GLMM.

Description

corrHLfit performs the joint estimation of correlation parameters, fixed effect and dispersion parameters.

Usage

corrHLfit(formula,data,init.corrHLfit=list(),ranFix=list(),lower=list(),upper=list(),
          trace=list(file=NULL,append=T),objective="p_bv",control.corrHLfit=list(),...)

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 exa

data

A data frame containing the variables in the response and the model formula.

init.corrHLfit

An optional list of initial values for correlation and/or dispersion parameters, e.g. list(rho=1,nu=1,lambda=1,phi=1) where rho and nu are parameters of the Matérn family, and lambda and phi

ranFix

A list similar to initpar, but specifying fixed values of the parameters not estimated.

lower

An optional list of values of parameters specified through initpar, used as lower values in calls to optim

upper

Same as lower, but upper values.

trace

Not for normal use. If trace is of the form trace=list(file=,append=F), some trace information is written in the file 'filename'. This file is written over by each new call of corrHLfit unless append=T.

objective

The objective function maximized for estimation of parameters by optim. Either "p_bv" for restricted likelihood or "p_v" for marginal likelihood.

control.corrHLfit

Only for development purposes, not documented.

...

Optional arguments passed to HLCor, HLfit or designL.from.Corr, for example the distMatrix

Value

A list with currently a single element hlfit, which is the HLfit object returned by HLCor for the estimated correlation parameter values. These correlation parameter values are included in hlfit as its $corrPars member.

Details

Under the Matérn correlation model, corrHLfit typically performs a optimization over the $\rho$ and $\nu$ parameters, with maximum possible values as set by spaMM.options. By default corrHLfit will estimate correlation parameters by maximizing the objective value returned by HLCor calls wherein the dispersion parameters are estimated jointly with fixed effects for given correlation parameters. If dispersion parameters are specified in init.corrHLfit, they will also be estimated by maximizing the objective value, and HLCor calls will not estimate them jointly with fixed effects. This means that in general the fixed effect estimates may vary depending on init.corrHLfit when any form of REML correction is applied. Correctly using corrHLfit for likelihood ratio tests of fixed effects may then by tricky. It is safe to perform full ML fits of all parameters (using objective="p_v",HLmethod="ML") for such tests (see Examples). The higher level function fixedLRT is a safe interface for likelihood ratio tests using some form of REML estimation in corrHLfit.

Examples

Run this code

#### example with an adjacency matrix (autoregressive model)
data(scotlip)
corrHLfit(cases~I(prop.ag/10) +adjacency(1|gridcode)+offset(log(scotlip$expec)),
               data=scotlip,family=poisson(),
               adjMatrix=Nmatrix,lower=list(rho=0),upper=list(rho=0.1745))


#### Examples with Matérn correlations
## A likelihood ratio test based on the ML fits of a full and of a null model.
data(blackcap)
fullfit <- corrHLfit(migStatus ~ means+ Matern(1|latitude+longitude),data=blackcap,
                    objective="p_v",HLmethod="ML") ## takes ~ 6s
summary(fullfit)
nullfit <- corrHLfit(migStatus ~ 1 + Matern(1|latitude+longitude),data=blackcap,
                    objective="p_v",HLmethod="ML") ## takes ~ 3s
summary(nullfit)
## p-value:
1-pchisq(2*(fullfit$hlfit$APHLs$p_v-nullfit$hlfit$APHLs$p_v),df=1)

## see data set Loaloa for additional examples