All model runner options

1.A: Input data

Formatted as a data.frame or data.table::data.table. Should contain at least the following fields:

• indicator: Contains the outcome to be modeled. For binomial or Poission MBG models, this is the numerator. For Gaussian models, this is the observed mean.
• samplesize: Only required for binomial or Poisson data. This is the denominator for each observations.
• sd: Only required for Gaussian models. This is the observed standard deviation for each observation.
• x: The point’s x position, in the same coordinate reference system as the ID raster. For unprojected data, this is the longitude
• y: The points y position, in the same coordinate reference system as the ID raster. For unprojected data, this is the latitude
• cluster_id: A unique identifier for each row in the data

1.B: ID raster

A terra::SpatRaster object meeting the following requirements:

• Has a single layer
• Covers the entire study area
• Contains non-NA pixel values for pixels that should be estimated by the model

An ID raster can be created using the mbg::build_id_raster function.

Before running a model, you could use the terra::extract function to ensure that all points in your input data overlap a non-NA pixel in the ID raster.

3.A: Covariate effects

Relevant settings:

• use_covariates (default TRUE)
• covariate_rasters (default NULL)
• use_stacking (default FALSE)

A covariate effect will only be included if use_covariates is TRUE (the default) and covariate_rasters are passed. The covariate_rasters are an optional list of terra::SpatRaster pixel-level predictive covariates. They can be incorporated into the model in two different ways depending on the value of use_stacking:

3.B: Gaussian process

If the setting use_gp is TRUE (the default), adds a spatially correlated effect:

$$Z \sim GP(0, \Sigma_s)$$ Where $Z$ is a Gaussian process with mean zero and stationary isotropic Matern covariance over space ($\Sigma_s$).

The Gaussian process is informed by priors on the range and variance:

• prior_spde_range (default list(threshold = 0.1, prob_below = 0.05)) Prior on the geostatistical range of the Gaussian process, the distance beyond which there is little or no spatial autocorrelation between pairs of points on the GP. This is a penalized complexity prior expressed as a named list with two items. The threshold is a distance expressed relative to the diameter of the study area: for example, the default threshold of 0.1 corresponds to a geostatistical range equivalent to one-tenth the diameter of the study area. The prob_below is the probability that the true range falls below this threshold. In other words, the default prior is $P(range < \frac{diameter}{10}) = 0.05$
• prior_spde_sigma (default list(threshold = 3, prob_above = 0.05)) Penalized complexity prior on the variance of the Gaussian process, expressed in terms of the standard deviation $\sigma_Z$. The default corresponds to a prior belief that $P(\sigma_Z > 3) = 0.05$

To simplify estimation, the R-INLA package represents the continuous Gaussian process on a 2D spatial mesh. Three more settings control the mesh:

• mesh_max_edge (default c(0.2, 5.0)): The maximum length of a mesh edge in areas where there is little to no data. Expressed in the same units of measurement as the projection used for the id_raster (for unprojected data, this is decimal degrees). The first term is the maximum edge length within the study area, and the second term is the maximum edge length outside the study area (the mesh extends beyond the study area to mitigate edge effects).
• mesh_cutoff (default 0.04): The minimum length of a mesh edge in areas where data is dense. Expressed in the same units of measurement as mesh_max_edge.
• spde_integrate_to_zero (default FALSE): Should the volume under the fitted mesh integrate to zero?

For more details about the INLA approach to approximate Gaussian process regression, see the papers at the bottom of this page.

3.C: Administrative-level effect

This effect is a random intercept grouped by administrative unit. The administrative level (polygon boundaries) of interest can be set by the user. If the effect is on, then the following term is added:

$$\gamma^{admin}_{a_i} \sim N(0, \sigma^2_{admin})$$ In other words, $\vec\gamma^{admin}$ is an vector of random intercepts with length equal to the total number of administrative units, IID normal with mean 0 and variance $\sigma^2_{admin}$. All observations $i$ in the same administrative division $a$ share the same intercept $\gamma^{admin}_{a_i}$.

Relevant settings:

• use_admin_effect (default FALSE): Should the administrative-level effect be included in the model?
• prior_admin_effect (default list(threshold = 3, prob_above = 0.05)): A prior applied to the administrative effect variance, expressed in terms of the standard deviation. The default settings correspond to the prior belief that $P(\sigma_{admin} > 3) = 0.05$
• admin_bounds (default NULL): Administrative bounds that will be used to group observations.
• admin_bounds_id (default NULL): Unique identifier field for admin_bounds

3.D: Nugget

The nugget is an independently and identically distributed (IID) normal effect applied to each observation. It corresponds to “irreducible variation” not captured by any other model effect:

$$\gamma^{Nugget}_i \sim N(0, \sigma^2_{nugget})$$

Relevant settings:

• use_nugget (default TRUE): Should the nugget effect be included in model fitting?
• prior_nugget (default list(threshold = 3, prob_above = 0.05)): A prior applied to the nugget variance, expressed in terms of the standard deviation. The default settings correspond to the prior belief that $P(\sigma_{nugget} > 3) = 0.05$
• nugget_in_predict (default TRUE): If TRUE, independent samples from $N(0, \sigma^2_{nugget})$ are added to each pixel-level predictive draw.