Two-Stage Multi-City Pooling of DLNM Estimates — sus_mod

Performs a two-stage multivariate meta-analysis to pool Distributed Lag Non-linear Model (DLNM) estimates across multiple cities or regions. Stage 1 city-specific estimates (coefficients and variance-covariance matrices from sus_mod_dlnm()) are combined using multivariate random-effects meta-analysis via mvmeta, producing pooled exposure-response and lag-response curves, heterogeneity statistics, and Best Linear Unbiased Predictors (BLUPs) for each city.

Usage

sus_mod_pool(
  fits,
  exposure_range = NULL,
  n_grid = 100L,
  pred_at = c(0.75, 0.9, 0.95, 0.99),
  blup = TRUE,
  method = "reml",
  lang = "pt",
  verbose = TRUE
)

Arguments

fits: A named list of climasus_dlnm objects, one per city or region. All fits must have been produced with the same climate_col, argvar, arglag, and lag_max.
exposure_range: Numeric vector of length 2 specifying the exposure grid range for the pooled prediction. Default NULL uses the combined range across all city datasets.
n_grid: Integer. Number of exposure grid points for the pooled prediction curve. Default 100L.
pred_at: Numeric vector of quantile probabilities (0-1) for the pooled exposure-response summary table. Default c(0.75, 0.90, 0.95, 0.99).
blup: Logical. Compute BLUP city-specific predictions? Default TRUE.
method: Character. mvmeta estimation method: "reml" (default, recommended), "ml", or "fixed" (fixed-effects, no heterogeneity).
lang: Character. Language for messages: "pt" (default), "en", "es".
verbose: Logical. Print progress messages. Default TRUE.

Value

A climasus_pool list with components:

mvmeta_fit: The raw mvmeta model object.
pooled_pred: dlnm::crosspred object with pooled coefficients.
exposure_response: Tibble of pooled RR at quantile grid points.
lag_response: Tibble of pooled RR by lag at the 75th percentile exposure.
blup_preds: Named list of city-specific BLUP crosspred objects (when blup = TRUE).
city_table: Tibble with one row per city showing city-specific and BLUP-adjusted RRs at the 75th percentile.
heterogeneity: Tibble with Cochran Q, df, p-value, and I^2 statistics.
meta: List of metadata: climate_col, outcome_col, lag_max, n_cities, city_names, method, argvar, arglag, ref_value, pred_at, call_time.

Statistical framework

Let $\boldsymbol{\theta}_i$ be the $p$-dimensional vector of cross-basis coefficients for city $i$, estimated with variance $S_i$. The multivariate random-effects model is:

$$\boldsymbol{\theta}_i \sim N(\boldsymbol{\theta}, S_i + \Psi)$$

where $\Psi$ is the between-city covariance matrix estimated by REML. The pooled estimate $\hat{\boldsymbol{\theta}}$ and its variance are passed to dlnm::crosspred() to produce a pooled exposure-response surface identical in format to the single-city output.

BLUPs shrink city-specific estimates toward the pooled mean:

$$\tilde{\boldsymbol{\theta}}_i = \hat{\boldsymbol{\theta}} + \hat\Psi (\hat\Psi + S_i)^{-1} (\hat{\boldsymbol{\theta}}_i - \hat{\boldsymbol{\theta}})$$

Examples

if (FALSE) { # \dontrun{
fits <- list(
  city_a = sus_mod_dlnm(df_a, ...),
  city_b = sus_mod_dlnm(df_b, ...),
  city_c = sus_mod_dlnm(df_c, ...)
)
pool <- sus_mod_pool(fits, lang = "en")
print(pool)
plot_pool <- sus_mod_plot_dlnm(pool, lang = "en")
} # }