corrHLfit:

Description

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

Usage

corrHLfit(formula, data, init.corrHLfit = list(), 
          init.HLfit = list(), ranFix = list(), lower = list(), 
          upper = list(), 
          objective = NULL, resid.model = ~1, resid.formula,
          control.dist = list(), control.corrHLfit = list(),
          processed = NULL, family = gaussian(), 
          nb_cores = NULL, ...)

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 examples below). See Details in spaMM for allowed terms in the formula.

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<U+00E9>rn family (see Matern), and lambda and phi are dispersion parameters (see Details in spaMM for the meaning of these parameters). All are optional, but giving values for a dispersion parameter changes the ways it is estimated (see Details). rho may be a vector (see make_scaled_dist) and, in that case, it is possible that some or all of its elements are NA, for which corrHLfit substitute automatically determined values.

init.HLfit

See identically named HLfit argument.

ranFix

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

lower

An optional list of values of parameters specified through init.corrHLfit, used as lower values in calls to optim. See Details for default values.

upper

Same as lower, but upper values.

objective

Can be ignored: default value is determined from other arguments (HLmethod and REMLformula), being "p_bv" for restricted likelihood or "p_v" for marginal likelihood. Non-default values can be given but this is an obsolete and the other arguments should be used.

resid.model, resid.formula

See identically named HLfit arguments.

control.dist

See control.dist in HLCor

control.corrHLfit

This may be used to provide control to the optimizer. In particular, control.corrHLfit$optim should be a list of arguments for optim, e.g. control.corrHLfit = list(optim=list(control=list(ndeps=rep(2e-3,3))))

processed

For programming purposes, not documented.

family

Either a family or a multi value.

nb_cores

Number of cores to use for parallel computations.

…

Optional arguments passed to HLCor, HLfit or designL.from.Corr, for example the distMatrix argument of HLCor. Arguments that do not fit within these functions are detected and a warning is issued.

Value

The return value of an HLCor call, with additional attributes. The HLCor call is evaluated at the estimated correlation parameter values. These values are included in the return object as its $corrPars member. The attributes added by corrHLfit include the original call of the function (which can be retrived by getCall(<fitted object>), and information about the optimization call within corrHLfit.

Details

Under the Mat<U+00E9>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 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.

attr(<fitted object>,"optimInfo")$lower and ...$upper gives the lower and upper bounds for optimization of correlation parameters. These are the default values if the user did not provide explicit values. For the adjacency model, the default values are the inverse of the maximum and minimum eigenvalues of the adjMatrix. For the Mat<U+00E9>rn model, the default values are not so easily summarized: they are intended to cover the range of values for which there is statistical information to distinguish among them.

Examples

Run this code

# Example with an adjacency matrix (autoregressive model):
# see 'adjacency' documentation page

#### Examples with Mat<U+00E9>rn correlations
## A likelihood ratio test based on the ML fits of a full and of a null model.
if (spaMM.getOption("example_maxtime")>1) {
 data(blackcap)
 fullfit <- corrHLfit(migStatus ~ means+ Matern(1|latitude+longitude),data=blackcap,
                    HLmethod="ML") 
 summary(fullfit)
 nullfit <- corrHLfit(migStatus ~ 1 + Matern(1|latitude+longitude),data=blackcap,
                    HLmethod="ML",init.corrHLfit=list(phi=1e-6)) 
 summary(nullfit)
 ## p-value:
 1-pchisq(2*(logLik(fullfit)-logLik(nullfit)),df=1)
}

## see data set Loaloa for additional examples