Generate Predictions from a Fitted Space-Time Bayesian Model

Produces approximate predictions at new or future space-time points from a climasus_spacetime_bayes object fitted by sus_mod_spacetime_bayes(). This function is designed for disease surveillance projections and counterfactual scenario analysis (e.g. "what if temperature was 2 °C higher?").

Usage

sus_mod_spacetime_predict(
  fit,
  newdata = NULL,
  horizon = 0L,
  covariates_new = NULL,
  include_ci = TRUE,
  return_samples = FALSE,
  lang = "pt",
  verbose = TRUE
)

Arguments

fit: A climasus_spacetime_bayes object from sus_mod_spacetime_bayes().
newdata: A data.frame with at least columns code_muni (7-digit IBGE code) and time_idx (integer period index, 1-based, matching the encoding used in the original fit) plus any covariate columns required by the model. If NULL and horizon > 0, a synthetic grid is constructed by crossing all fitted municipalities with the next horizon time steps, using covariate values from the last observed period (stored in fit$data_last_obs, if available).
horizon: Non-negative integer. Number of periods ahead to predict when newdata is NULL. If newdata is provided, horizon must be 0L (default).
covariates_new: Named list of covariate overrides for scenario analysis. Each element must be a scalar (applied to all rows) or a vector of length nrow(newdata). Applied after newdata columns are extracted. Default NULL (no overrides).
include_ci: Logical. If TRUE (default), compute 95\ credible intervals via variance propagation from posterior standard deviations in fit$fixed, fit$spatial_re, and fit$temporal_re.
return_samples: Logical. If TRUE, attempt to draw posterior predictive samples from the stored INLA fit object (fit$inla_fit). Requires the model to have been fitted with return_inla_fit = TRUE and the INLA package to be installed. Default FALSE.
lang: Character. Language for CLI messages: "pt" (default), "en", or "es".
verbose: Logical. If TRUE (default), print progress messages via cli.

Value

A named list of class c("climasus_spacetime_pred", "list") with:

$predictions: data.frame with columns code_muni, time_idx, pred_mean, and (if include_ci = TRUE) pred_lower95, pred_upper95.
$n_predicted: Integer. Total number of predicted observations.
$horizon: Integer. Horizon used (0 when newdata is supplied).
$call: The matched call.

If return_samples = TRUE and INLA is available, an additional $samples slot contains raw INLA posterior samples (list from INLA::inla.posterior.sample()).

Algorithm

Because re-running INLA for new data is computationally expensive, this function uses an approximate linear-predictor approach:

Extract posterior mean fixed effects $\hat{\beta}$ and their standard deviations $\sigma_\beta$ from fit$fixed.
For new covariate matrix $X_{\text{new}}$, compute the fixed-effect contribution: $\eta^{(f)} = X_{\text{new}} \hat{\beta}$.
Spatial random effect: reuse fit$spatial_re for municipalities present in the fitted model. For municipalities not in the training data, the spatial random effect is set to NA with a warning.
Temporal random effect: for in-sample time points, reuse fit$temporal_re directly. For future periods (horizon > 0), extrapolate using the last observed increment (RW1: repeat last increment; RW2: project second differences) with uncertainty propagation.
Full linear predictor: $\hat{\eta} = \eta^{(f)} + \phi_i + \gamma_t$.
Variance propagation: $$\text{Var}(\hat{\eta}) \approx x^T V_\beta x + \sigma^2_\phi + \sigma^2_\gamma$$ where $V_\beta = \text{diag}(\sigma_\beta^2)$ (diagonal approximation).
Point prediction: $\hat{\mu} = \exp(\hat{\eta})$ (Poisson / NB) or $\hat{\mu} = \hat{\eta}$ (Gaussian).
95\ $\exp(\hat{\eta} \pm 1.96 \sqrt{\text{Var}(\hat{\eta})})$.

Important: this is an approximation. For exact posterior predictive distributions, re-run sus_mod_spacetime_bayes() with the full dataset including future periods.

Covariate override (scenario analysis)

covariates_new accepts a named list of scalar or vector overrides, e.g.:

covariates_new = list(temp_mean = new_grid$temp_mean + 2)

Overrides are applied to the resolved covariate matrix after newdata columns are extracted, so they can reference vectors of length nrow(newdata).

References

Rue, H., Martino, S., & Chopin, N. (2009). Approximate Bayesian inference for latent Gaussian models by using integrated nested Laplace approximations. Journal of the Royal Statistical Society: Series B, 71(2), 319-392.

Blangiardo, M., & Cameletti, M. (2015). Spatial and Spatio-temporal Bayesian Models with R-INLA. Wiley.

Held, L., & Schrödle, B. (2010). Posterior and cross-validatory predictive checks: a comparison of MCMC and INLA. In Statistical Modelling and Regression Structures (pp. 91-110). Physica-Verlag HD.

Examples

if (FALSE) { # \dontrun{
library(climasus4r)

# Assume `st_fit` is a climasus_spacetime_bayes object
# fitted on monthly data for 2015-2020

# 1. In-sample predictions for validation
pred_insample <- sus_mod_spacetime_predict(
  fit     = st_fit,
  newdata = training_data,
  lang    = "pt"
)
head(pred_insample$predictions)

# 2. Out-of-sample: 6 months ahead
pred_future <- sus_mod_spacetime_predict(
  fit     = st_fit,
  horizon = 6L,
  lang    = "en"
)
pred_future$predictions

# 3. Counterfactual: +2 degrees C scenario
pred_counter <- sus_mod_spacetime_predict(
  fit            = st_fit,
  newdata        = new_grid,
  covariates_new = list(temp_mean = new_grid$temp_mean + 2),
  lang           = "pt"
)
} # }