Fit Multiple INLA Models
Description
This function fits a set of INLA model formulas, provided in a GHRformulas object, to a specified dataset. For each fitted model, it extracts a range of outputs, including goodness-of-fit (GoF) metrics and other model outputs (fitted values, fixed effects, random effects). Results are extracted and stored in a GHRmodels object.
fit_models(
formulas,
data,
family,
name = "mod",
offset_var = NULL,
control_compute = list(config = FALSE, vcov = FALSE),
control_inla = list(strategy = "adaptive"),
control_family = list(),
ppd_samples = 500,
keep_ppd = FALSE,
keep_inlamod = FALSE,
nthreads = 1,
progress = FALSE,
verbose = FALSE,
offset = NULL
)Arguments
formulas: Either aGHRformulasobject containing multiple INLA model formulas, or a character vector of formulas (in this case,as_GHRformulas()will be executed internally).data: A data frame containing the variables used in the model formulas.family: A character string specifying the likelihood family. Currently available options include"poisson","nbinomial","gaussian","zeroinflatedpoisson0", and"zeroinflatednbinomial0".name: Either a single character string to label each fitted model by attaching a count (e.g.,"mod") if there is more than one formula, or a character vector with the the same number of"formulas".offset_var: A character string specifying the name of the offset variable indata. IfNULL(default), no offset is applied. Internally,offset_varis transformed according to the link function of the corresponding family: identity for"gaussian"and log for the rest of families.control_compute: A named list controlling additional computation options passed to INLA’scontrol.compute:config: Logical indicating whether to store extra internal configuration (e.g., enabling posterior predictive checks like CRPS). Defaults toFALSE.vcov: Logical indicating whether to return the variance-covariance (correlation) matrix of fixed effects. Defaults toFALSE.
Note that other elements of
control.computecannot be modified.control_inla: Parameters passed tocontrol.inlainINLA::inla. See?INLA::control.inlato see all available options. By default, uses the adaptive strategy.control_family: Parameters passed tocontrol.familyinINLA::inla. See?INLA::control.familyto see all available options.ppd_samples: Numeric indicating the number of posterior predictive samples to draw. Only used ifconfig=TRUE, defaults to 500.keep_ppd: Default is FALSE (do not keep ppd). If TRUE (requires alsoconfig=TRUE), the posterior predictive distribution for all data samples is saved in the object, which can be useful forplot_ppd().keep_inlamod: Logical. Default is FALSE. If TRUE, the fitted INLA model objects are stored in the output list, which may result in a substantially larger object.nthreads: An integer specifying the maximum number of threads for parallel computation. Default is1.progress: Logical; ifTRUE, displays progression while fitting models. Default isFALSE.verbose: Logical; ifTRUE, run INLA in verbose mode (useful for debugging). Default isFALSE.offset: Deprecated, use offset_var instead.
Details
This function iterates over each formula in the GHRformulas object and fits the corresponding INLA model using the internal function .fit_single_model(). For each fitted model, it extracts the fitted values, fixed effects, and random effects summaries. Then, it calculates a series of model evaluation metrics using the .gof_single_model() internal function.
Because the first formula is used as the reference model for all comparison metrics (see Section B below), if it fails to fit, fit_models() stops and no results are returned for any model. However, if a formula after the first fit fails, a message is printed and that model is skipped (GoF row is filled with NA and object components are left empty).
The goodness-of-fit (GoF) metrics are organized into two categories:
- Model-Specific Goodness-of-Fit Metrics
These are computed separately for each model:
Deviance Information Criterion (DIC)
DIC = \bar{D} + p_{D}where
\bar{D}is the posterior mean deviance andp_{D}is the effective number of parameters. Lower DIC values indicate a better model fit, balancing goodness-of-fit and model complexity.Watanabe-Akaike Information Criterion (WAIC)
WAIC = -2\left(\mathrm{lppd} - p_{\mathrm{WAIC}}\right)WAIC evaluates predictive accuracy and penalizes model complexity through the log pointwise predictive density (
\mathrm{lppd}). Lower values imply better generalization.Log Mean Score (LMS)
LMS = \frac{1}{n} \sum_{i=1}^n \left( -\log(\mathrm{CPO}_i) \right)LMS assesses the average negative log-predictive density using Conditional Predictive Ordinates (CPO). Lower LMS values indicate stronger predictive performance by penalizing models that assign low probability to observed outcomes.
Mean Absolute Error (MAE)
MAE = \frac{1}{n} \sum_{i=1}^n \left| y_i - \hat{y}_i \right|Average absolute difference between observed and a point estimate of the predictions. As a point estimate, it uses the
summary.fitted.valuesprovided by INLA whenconfig = FALSEand the mean of the ppd ifconfig = TRUE. MAE is more robust to outliers than RMSE. Lower MAE values indicate improved model fit.Root Mean Squared Error (RMSE)
RMSE = \sqrt{ \frac{1}{n} \sum_{i=1}^n (y_i - \hat{y}_i)^2 }Root average squared difference between observed and a point estimate of the predictions. As a point estimate, it uses the
summary.fitted.valuesprovided by INLA whenconfig = FALSEand the mean of the ppd ifconfig = TRUE. RMSE penalizes larger errors more heavily. Lower RMSE values reflect better model fit.Continuous Ranked Probability Score (CRPS)
\mathrm{CRPS}(F, y) = \int_{-\infty}^{\infty} \left[F(t) - \mathbf{1}\{y \leq t\}\right]^2 dtThe intergral is approximated with the empirical CRPS (see crps_empirical ):
\mathrm{CRPS} = \frac{1}{n} \sum_{i=1}^n |x_i - y| - \frac{1}{2n^2} \sum_{i=1}^n \sum_{j=1}^n |x_i - x_j|CRPS assesses how well the entire posterior predictive distribution aligns with the observed outcome. The median CRPS across observations is returned. Lower scores suggest better calibrated predictive distributions. Only available when
config = TRUE.
- Model Comparison Metrics (relative to the first model)
The first model in the list is treated as the baseline for model comparisons. All other models are evaluated against it using the following metrics:
Difference in DIC and WAIC
Stored as
dic_vs_firstandwaic_vs_first. These represent how much higher (or lower) each model’s DIC/WAIC is compared to the first model. Additionally, 95% credible intervals for these differences are stored as*_vs_first_lciand*_vs_first_uci.Difference in MAE and RMSE
Stored as
mae_vs_firstandrmse_vs_first. These reflect the absolute difference in prediction error compared to the first model. No credible intervals are computed for these metrics.Continuous Ranked Probability Score Skill Score (CRPSS)
\mathrm{CRPSS} = 1 - \frac{\mathrm{CRPS}_{\text{model}}}{\mathrm{CRPS}_{\text{baseline}}}Indicates how much better the predictive distribution of the current model is relative to the baseline model. Values closer to 1 indicate improvement; negative values imply worse performance. Available only when
config = TRUE.Pseudo R-squared based on deviance
R^2 = 1 - \exp\left( \frac{-2}{n} \left( \frac{dev_{\text{model}}}{-2} - \frac{dev_{\text{base}}}{-2} \right) \right)Captures relative deviance reduction compared to the baseline model. Values range from 0 (no improvement) to 1 (strong improvement).
Random Effect Variance
\mathrm{Var}_{re} = \frac{1}{\mathrm{precision}}Quantifies residual variance due to group- or cluster-level effects. Computed only when random effects are defined in the model formula.
Proportional Change in Random Effect Variance
\frac{\mathrm{Var}_{re}}{\mathrm{Var}_{re}^{(1)}} - 1Represents the relative change in group-level variance compared to the baseline model. Helps assess how much variance is explained by added covariates.
re1_var_changerefers to the change in specific random effects (ordered by number) whereasre_meanchangeis the mean change across all random effects.re_meanchangeisNAwhen no random effects are defined or if the variance change of any individual random effect isNA.
Returns
An object of class GHRmodels containing:
$mod_gof: A data frame of model-specific goodness-of-fit metrics.$fitted: A list of fitted values (one element per model). Ifconfig = TRUE, these are derived from the posterior predictive distribution (PPD); otherwise, they are extracted from INLA’ssummary.fitted.values.$fixed: A list of summary tables for fixed effects (one element per model).$random: A list of summary tables for random effects (one element per model).$vcov: A list of variance-covariance (correlation) matrices of fixed effects (one element per model). Populated only whencontrol_compute$vcov = TRUE.$formulas: A character vector of the original model formulas used.$re: A character vector specifying any random effects defined informulas.$outcome: A character string indicating the outcome variable used.$family: A character string indicating the likelihood family used.$data: The original data frame passed to the function.$ppd: (ifkeep_ppd=TRUE) A list of ppd matrices where rows are observations in the same order as indataand columns are ppd samples.$inlamod: (ifkeep_inlamod=TRUE) A list of inla model objects.
See Also
as_GHRformulas converts a set of R-INLA-compatible formulas into a GHRformulas object.
Examples
# Load example dataset
data(dengue_MS)
dengue_MS <- dengue_MS[dengue_MS$year %in% 2010:2012, ]
# Declare formulas
formulas <- c(
"dengue_cases ~ tmin + f(year, model='rw1')",
"dengue_cases ~ pdsi + f(year, model='rw1')"
)
# Fit multiple models
results <- fit_models(
formulas = formulas,
data = dengue_MS,
family = "nbinomial",
name = "TestModel",
offset_var = "pop100000",
nthreads = 2,
progress = TRUE
)
# Inspect goodness-of-fit metrics
results$mod_gof