glgm.LA: Maximum Likelihood estimation for generalised linear geostatistical models via the Laplace approximation

Description

This function performs the Laplace method for maximum likelihood estimation of a generalised linear geostatistical model.

Usage

glgm.LA(
  formula,
  units.m = NULL,
  coords,
  times = NULL,
  data,
  ID.coords = NULL,
  kappa,
  kappa.t = 0.5,
  fixed.rel.nugget = NULL,
  start.cov.pars,
  method = "nlminb",
  messages = TRUE,
  family,
  return.covariance = TRUE
)

Arguments

formula

an object of class formula (or one that can be coerced to that class): a symbolic description of the model to be fitted.

units.m

an object of class formula indicating the binomial denominators in the data.

coords

an object of class formula indicating the spatial coordinates in the data.

times

an object of class formula indicating the times in the data, used in the spatio-temporal model.

data

a data frame containing the variables in the model.

ID.coords

vector of ID values for the unique set of spatial coordinates obtained from create.ID.coords. These must be provided if, for example, spatial random effects are defined at household level but some of the covariates are at individual level. Warning: the household coordinates must all be distinct otherwise see jitterDupCoords. Default is NULL.

kappa

fixed value for the shape parameter of the Matern covariance function.

kappa.t

fixed value for the shape parameter of the Matern covariance function in the separable double-Matern spatio-temporal model.

fixed.rel.nugget

fixed value for the relative variance of the nugget effect; fixed.rel.nugget=NULL if this should be included in the estimation. Default is fixed.rel.nugget=NULL.

start.cov.pars

a vector of length two with elements corresponding to the starting values of phi and the relative variance of the nugget effect nu2, respectively, that are used in the optimization algorithm. If nu2 is fixed through fixed.rel.nugget, then start.cov.pars represents the starting value for phi only.

method

method of optimization. If method="BFGS" then the maxBFGS function is used; otherwise method="nlminb" to use the nlminb function. Default is method="BFGS".

messages

logical; if messages=TRUE then status messages are printed on the screen (or output device) while the function is running. Default is messages=TRUE.

family

character, indicating the conditional distribution of the outcome. This should be "Gaussian", "Binomial" or "Poisson".

return.covariance

logical; if return.covariance=TRUE then a numerical estimation of the covariance function for the model parameters is returned. Default is return.covariance=TRUE.

Value

An object of class "PrevMap". The function summary.PrevMap is used to print a summary of the fitted model. The object is a list with the following components:

estimate: estimates of the model parameters; use the function coef.PrevMap to obtain estimates of covariance parameters on the original scale.

covariance: covariance matrix of the MCML estimates.

log.lik: maximum value of the log-likelihood.

y: binomial observations.

units.m: binomial denominators.

D: matrix of covariates.

coords: matrix of the observed sampling locations.

times: vector of the time points used in a spatio-temporal model.

method: method of optimization used.

ID.coords: set of ID values defined through the argument ID.coords.

kappa: fixed value of the shape parameter of the Matern function.

kappa.t: fixed value for the shape parameter of the Matern covariance function in the separable double-Matern spatio-temporal model.

fixed.rel.nugget: fixed value for the relative variance of the nugget effect.

call: the matched call.

Details

This function performs parameter estimation for a generealized linear geostatistical model. Conditionally on a zero-mean stationary Gaussian process $S(x)$ and mutually independent zero-mean Gaussian variables $Z$ with variance tau2, the observations y are generated from a GLM with link function $g(.)$ and linear predictor $$\eta = d'\beta + S(x) + Z,$$ where $d$ is a vector of covariates with associated regression coefficients $\beta$. The Gaussian process $S(x)$ has isotropic Matern covariance function (see matern) with variance sigma2, scale parameter phi and shape parameter kappa. The shape parameter is treated as fixed. The relative variance of the nugget effect, nu2=tau2/sigma2, can also be fixed through the argument fixed.rel.nugget; if fixed.rel.nugget=NULL, then the relative variance of the nugget effect is also included in the estimation.

Laplace Approximation The Laplace approximation (LA) method uses a second-order Taylor expansion of the integrand expressing the likelihood function. The resulting approximation of the likelihood is then maximized by a numerical optimization as defined through the argument method.

Using a two-level model to include household-level and individual-level information. When analysing data from household sruveys, some of the avilable information information might be at household-level (e.g. material of house, temperature) and some at individual-level (e.g. age, gender). In this case, the Gaussian spatial process $S(x)$ and the nugget effect $Z$ are defined at hosuehold-level in order to account for extra-binomial variation between and within households, respectively.

References

Diggle, P.J., Giorgi, E. (2019). Model-based Geostatistics for Global Public Health. CRC/Chapman & Hall.

Giorgi, E., Diggle, P.J. (2017). PrevMap: an R package for prevalence mapping. Journal of Statistical Software. 78(8), 1-29. doi: 10.18637/jss.v078.i08

Christensen, O. F. (2004). Monte carlo maximum likelihood in model-based geostatistics. Journal of Computational and Graphical Statistics 13, 702-718.

Higdon, D. (1998). A process-convolution approach to modeling temperatures in the North Atlantic Ocean. Environmental and Ecological Statistics 5, 173-190.