A fitting function acting as a convenient interface for HLfit, constructing the correlation matrix of random effects from the arguments, then estimating fixed effects and dispersion parameters using HLfit. Various arguments are available to constrain the correlation structure, covStruct and distMatrix being the more general ones (for any number of random effects), and adjMatrix and corrMatrix being alternatives to covStruct for a single correlated random effect. The uniqueGeo argument is deprecated.
HLCor(formula, data, family = gaussian(), fixed=NULL, ranPars, distMatrix,
adjMatrix, corrMatrix, covStruct=NULL,
method = "REML", verbose = c(inner=FALSE),
control.dist = list(), weights.form = NULL, ...)The return value of an HLfit call, with the following additional attributes:
the HLCor call
Unique geographic locations.
A predictor, i.e. a formula with attributes (see Predictor), or possibly simply a simple formula if an offset is not required.
A list of given values for correlation parameters (some of which are mandatory), and possibly also dispersion parameters (optional, but passed to HLfit if present). ranPars is the old argument, maintained for back compatibility; fixed is the new argument, uniform across spaMM fitting functions. See fixed for further information about these two parameters.
The data frame to be analyzed.
A family object describing the distribution of the response variable. See HLfit for further information.
This argument allows estimation of Matern or Cauchy correlation parameters to be combined with use of an ad hoc distance matrix. When there is a single spatial random effect, it may be a distance matrix between geographic locations, internally used as argument to MaternCorr or CauchyCorr. It then overrides the (by default, Euclidean) distance matrix that would otherwise be deduced from the variables in a Matern(.)) or Cauchy(.) term.
More generally, it may be a list of such matrices. The list format may be necessary when there are several Matern/Cauchy terms, to avoid that all of them are affected by the same distMatrix. NULL list elements may be necessary, e.g.
distMatrix=list("1"=NULL,"2"=<.>)) when a matrix is specified only for the second random effect.
An single adjacency matrix, used if a random effect of the form
y ~ adjacency(1|<location index>) is present. See adjacency for further details.
If adjacency matrices are needed for several random effects, use covStruct.
A matrix C used if a random effect term of the form corrMatrix(1|<stuff>) is present. This allows to analyze non-spatial model by giving for example a matrix of genetic correlations. Each row corresponds to levels of a variable <stuff>. The covariance matrix of the random effects for each level is then \(\lambda\)C, where as usual \(\lambda\) denotes a variance factor for the random effects (if C is a correlation matrix, then \(\lambda\) is the variance, but other cases are possible). See corrMatrix for further details.
If matrices are needed for several random effects, use the covStruct argument.
An interface for specifying correlation structures for different types of random effect (corrMatrix or adjacency). See covStruct for details.
Character: the fitting method to be used, such as "ML", "REML" or "PQL/L". "REML" is the default. Other possible values of HLfit's method argument are handled.
Specification of prior weights by a one-sided formula: use weights.form = ~ pw instead of prior.weights = pw. The effect will be the same except that such an argument, known to evaluate to an object of class "formula", is suitable to enforce safe programming practices (see good-practice).
A vector of booleans. inner controls various diagnostic (possibly messy) messages about the iterations. This should be distinguished from the TRACE element, meaningful in fitme or corrHLfit calls.
A list of arguments that control the computation of the distance argument of the correlation functions. Possible elements are
a set of indices controlling which elements of the rho scale vector scales which dimension(s) of the space in which (spatial)
correlation matrices of random effects are computed. See same argument in make_scaled_dist for details and examples.
method argument of proxy::dist function (by default, "Euclidean", but see make_scaled_dist for other distances such as spherical ones.)
Further arguments passed to HLfit or to mat_sqrt.
For approximations of likelihood, see method. For the possible structures of random effects, see random-effects, but note that HLCor cannot adjust parameters of correlation models (with the exception of conditional autoregressive ones). Any such parameter must be specified by the ranPars argument. More generally, the correlation matrix for random effects can be specified by various combinations of formula terms and other arguments (see Examples):
Matern(1|<...>), using the spatial coordinates in <...>. This will construct a correlation matrix according to the Matérn correlation function (see MaternCorr);
Cauchy(1|<...>), as for Matern (see CauchyCorr);
as provided by distMatrix (see Examples);
corrMatrix(1|<...>) with corrMatrix argument. See corrMatrix for further details.
adjacency(1|<...>) with adjMatrix. See adjacency for further details;
AR1(1|<...>) See AR1 for further details.
Additional example using an adjacency term in autoregressive;
Additional examples using corrMatrix or distMatrix argument in corrMatrix;
MaternCorr, which may be used to specify corrMatrix values.
# Example with an adjacency matrix (autoregressive model):
# see 'adjacency' documentation page
#### Matern correlation using only the Matern() syntax
data("blackcap")
(fitM <- HLCor(migStatus ~ means+ Matern(1|longitude+latitude),data=blackcap,
method="ML", ranPars=list(nu=0.6285603,rho=0.0544659)))
#### Using the 'distMatrix' argument
data("blackcap")
#
# Build distance matrix (here equivalent to the default one for a Matern() term)
MLdistMat <- as.matrix(proxy::dist(blackcap[,c("latitude","longitude")]))
#
(fitD <- HLCor(migStatus ~ means+ Matern(1|longitude+latitude),data=blackcap,
distMatrix=MLdistMat, method="ML", ranPars=list(nu=0.6285603,rho=0.0544659)))
# : result here must be equivalent to the one without the distMatrix.
diff(c(logLik(fitM),logLik(fitD)))
Run the code above in your browser using DataLab