STCAR_INLA: Fit a (scalable) spatio-temporal Poisson mixed model to areal...

In spatialstatisticsupna/bigDM: Scalable Bayesian Disease Mapping Models for High-Dimensional Data

Fit a (scalable) spatio-temporal Poisson mixed model to areal count data.

Description

Fit a spatio-temporal Poisson mixed model to areal count data, where several CAR prior distributions for the spatial random effects, first and second order random walk priors for the temporal random effects, and different types of spatio-temporal interactions described in \insertCiteknorrheld2000;textualbigDM can be specified. The linear predictor is modelled as

\log{r_{it}}=\alpha + \mathbf{x_{it}}^{'}\mathbf{\beta} + \xi_i+\gamma_t+\delta_{it}, \quad \mbox{for} \quad i=1,\ldots,n; \quad t=1,\ldots,T

where \alpha is a global intercept, \mathbf{x_{it}}^{'}=(x_{it1},\ldots,x_{itp}) is a p-vector of standardized covariates in the i-th area and time period t, \mathbf{\beta}=(\beta_1,\ldots,\beta_p) is the p-vector of fixed effects coefficients, \xi_i is a spatially structured random effect, \gamma_t is a temporally structured random effect, and \delta_{it} is the space-time interaction effect. If the interaction term is dropped, an additive model is obtained. To ensure model identifiability, sum-to-zero constraints are imposed over the random effects of the model. Details on the derivation of these constraints can be found in \insertCitegoicoa2018spatio;textualbigDM.

As in the CAR_INLA function, three main modelling approaches can be considered:

• the usual model with a global spatial random effect whose dependence structure is based on the whole neighbourhood graph of the areal units (model="global" argument)

• a Disjoint model based on a partition of the whole spatial domain where independent spatial CAR models are simultaneously fitted in each partition (model="partition" and k=0 arguments)

• a modelling approach where k-order neighbours are added to each partition to avoid border effects in the Disjoint model (model="partition" and k>0 arguments).

For both the Disjoint and k-order neighbour models, parallel or distributed computation strategies can be performed to speed up computations by using the 'future' package \insertCitebengtsson2020unifyingbigDM.

Inference is conducted in a fully Bayesian setting using the integrated nested Laplace approximation (INLA; \insertCiterue2009approximate;textualbigDM) technique through the R-INLA package (https://www.r-inla.org/). For the scalable model proposals \insertCiteorozco2022bigDM, approximate values of the Deviance Information Criterion (DIC) and Watanabe-Akaike Information Criterion (WAIC) can also be computed.

The function allows also to use the new hybrid approximate method that combines the Laplace method with a low-rank Variational Bayes correction to the posterior mean \insertCitevanNiekerk2023bigDM by including the inla.mode="compact" argument.

Usage

STCAR_INLA(
  carto = NULL,
  data = NULL,
  ID.area = NULL,
  ID.year = NULL,
  ID.group = NULL,
  O = NULL,
  E = NULL,
  X = NULL,
  W = NULL,
  spatial = "Leroux",
  temporal = "rw1",
  interaction = "TypeIV",
  model = "partition",
  k = 0,
  strategy = "simplified.laplace",
  scale.model = NULL,
  PCpriors = FALSE,
  merge.strategy = "original",
  compute.intercept = NULL,
  compute.DIC = TRUE,
  n.sample = 1000,
  compute.fitted.values = FALSE,
  save.models = FALSE,
  plan = "sequential",
  workers = NULL,
  inla.mode = "classic",
  num.threads = NULL
)

Arguments

carto	object of class SpatialPolygonsDataFrame or sf. This object must contain at least the variable with the identifiers of the spatial areal units specified in the argument ID.area.
data	object of class data.frame that must contain the target variables of interest specified in the arguments ID.area, ID.year, O and E.
ID.area	character; name of the variable that contains the IDs of spatial areal units. The values of this variable must match those given in the carto and data variable.
ID.year	character; name of the variable that contains the IDs of time points.
ID.group	character; name of the variable that contains the IDs of the spatial partition (grouping variable). Only required if model="partition".
O	character; name of the variable that contains the observed number of disease cases for each areal and time point.
E	character; name of the variable that contains either the expected number of disease cases or the population at risk for each areal unit and time point.
X	a character vector containing the names of the covariates within the data object to be included in the model as fixed effects, or a matrix object playing the role of the fixed effects design matrix. If X=NULL (default), only a global intercept is included in the model as fixed effect.
W	optional argument with the binary adjacency matrix of the spatial areal units. If NULL (default), this object is computed from the carto argument (two areas are considered as neighbours if they share a common border).
spatial	one of either "Leroux" (default), "intrinsic", "BYM" or "BYM2", which specifies the prior distribution considered for the spatial random effect.
temporal	one of either "rw1" (default) or "rw2", which specifies the prior distribution considered for the temporal random effect.
interaction	one of either "none", "TypeI", "TypeII", "TypeIII" or "TypeIV" (default), which specifies the prior distribution for the space-time interaction random effect.
model	one of either "global" or "partition" (default), which specifies the Global model or one of the scalable model proposal's (Disjoint model and k-order neighbourhood model, respectively).
k	numeric value with the neighbourhood order used for the partition model. Usually k=2 or 3 is enough to get good results. If k=0 (default) the Disjoint model is considered. Only required if model="partition".
strategy	one of either "gaussian", "simplified.laplace" (default), "laplace" or "adaptive", which specifies the approximation strategy considered in the inla function.
scale.model	logical value (default NULL); if TRUE the structure matrices of the model are scaled so their generalized variances are equal to 1. It only works if arguments spatial="intrinsic" or spatial="BYM2" are specified.
PCpriors	logical value (default FALSE); if TRUE then penalised complexity (PC) priors are used for the precision parameter of the spatial random effect. It only works if arguments spatial="intrinsic" or spatial="BYM2" are specified.
merge.strategy	one of either "mixture" or "original" (default), which specifies the merging strategy to compute posterior marginal estimates of the linear predictor. See mergeINLA for further details.
compute.intercept	CAUTION! This argument is deprecated from version 0.5.2.
compute.DIC	logical value; if TRUE (default) then approximate values of the Deviance Information Criterion (DIC) and Watanabe-Akaike Information Criterion (WAIC) are computed.
n.sample	numeric; number of samples to generate from the posterior marginal distribution of the linear predictor when computing approximate DIC/WAIC values. Default to 1000.
compute.fitted.values	logical value (default FALSE); if TRUE transforms the posterior marginal distribution of the linear predictor to the exponential scale (risks or rates). CAUTION: This method might be time consuming.
save.models	logical value (default FALSE); if TRUE then a list with all the inla submodels is saved in '/temp/' folder, which can be used as input argument for the mergeINLA function.
plan	one of either "sequential" or "cluster", which specifies the computation strategy used for model fitting using the 'future' package. If plan="sequential" (default) the models are fitted sequentially and in the current R session (local machine). If plan="cluster" the models are fitted in parallel on external R sessions (local machine) or distributed in remote computing nodes.
workers	character or vector (default NULL) containing the identifications of the local or remote workers where the models are going to be processed. Only required if plan="cluster".
inla.mode	one of either "classic" (default) or "compact", which specifies the approximation method used by INLA. See help(inla) for further details.
num.threads	maximum number of threads the inla-program will use. See help(inla) for further details.

Details

For a full model specification and further details see the vignettes accompanying this package.

Value

This function returns an object of class inla. See the mergeINLA function for details.

References

\insertRef

goicoa2018spatiobigDM

\insertRef

knorrheld2000bigDM

\insertRef

orozco2020bigDM

\insertRef

orozco2022bigDM

\insertRef

vanNiekerk2023bigDM

Examples

## Not run: 
if(require("INLA", quietly=TRUE)){

  ## Load the sf object that contains the spatial polygons of the municipalities of Spain ##
  data(Carto_SpainMUN)
  str(Carto_SpainMUN)

  ## Create province IDs ##
  Carto_SpainMUN$ID.prov <- substr(Carto_SpainMUN$ID,1,2)

  ## Load simulated data of lung cancer mortality data during the period 1991-2015 ##
  data("Data_LungCancer")
  str(Data_LungCancer)

  ## Disjoint model with a BYM2 spatial random effect, RW1 temporal random effect and      ##
  ## Type I interaction random effect using 4 local clusters to fit the models in parallel ##
  Disjoint <- STCAR_INLA(carto=Carto_SpainMUN, data=Data_LungCancer,
                         ID.area="ID", ID.year="year", O="obs", E="exp", ID.group="ID.prov",
                         spatial="BYM2", temporal="rw1", interaction="TypeI",
                         model="partition", k=0, strategy="gaussian",
                         plan="cluster", workers=rep("localhost",4))
  summary(Disjoint)

  ## 1st-order nb. model with a BYM2 spatial random effect, RW1 temporal random effect and ##
  ## Type I interaction random effect using 4 local clusters to fit the models in parallel ##
  order1 <- STCAR_INLA(carto=Carto_SpainMUN, data=Data_LungCancer,
                       ID.area="ID", ID.year="year", O="obs", E="exp", ID.group="ID.prov",
                       spatial="BYM2", temporal="rw1", interaction="TypeI",
                       model="partition", k=1, strategy="gaussian",
                       plan="cluster", workers=rep("localhost",4))
  summary(order1)
}

## End(Not run)

spatialstatisticsupna/bigDM documentation built on Aug. 22, 2024, 12:35 p.m.