IPCC 3-Pillar Composite Vulnerability Index for Climate-Health Analysis

Builds a city-level composite vulnerability index following the IPCC AR6 vulnerability framework: Vulnerability = f(Exposure + Sensitivity - Adaptive Capacity). Each pillar is constructed from a user-supplied data frame of city-level numeric indicators. Indicators are normalized (min-max or z-score), weighted within pillars, and combined into a final score ∈ [0, 1] where 1 = most vulnerable.

Usage

sus_mod_vulnerability_index(
  exposure_df = NULL,
  sensitivity_df = NULL,
  adaptive_capacity_df = NULL,
  fits = NULL,
  city_col = "city",
  normalize = "minmax",
  weights = NULL,
  pillar_weights = c(exposure = 1, sensitivity = 1, adaptive_capacity = 1),
  hot_percentile = 0.99,
  cold_percentile = 0.01,
  lang = "pt",
  verbose = TRUE
)

Arguments

exposure_df: A data frame with one row per city and numeric columns representing exposure indicators (higher value = more hazard). Typically derived by summarising a climasus_df produced by sus_climate_aggregate(). Must contain the column named city_col.
sensitivity_df: A data frame with numeric sensitivity indicators (higher value = more sensitive population). Can include demographic columns (% elderly, % children), health-outcome rates, or any other stratum-level vulnerability marker. If fits is also provided, the DLNM-derived metrics are merged into this data frame.
adaptive_capacity_df: A data frame with numeric adaptive capacity indicators (higher value = more adaptive capacity = less vulnerable). This pillar is inverted internally before computing VI. Typical columns come from sus_census_join() (e.g., HDI, literacy rate, piped-water coverage) or sus_spatial_join() (e.g., hospital density per capita).
fits: Optional named list of climasus_dlnm objects (one per city, names = city identifiers). When provided, the function extracts dlnm_hot_rr (cumulative RR at hot_percentile), dlnm_cold_rr (cumulative RR at cold_percentile), and dlnm_sensitivity_index for each city and merges them into the sensitivity pillar.
city_col: Character. Name of the city identifier column present in every supplied data frame. Default "city".
normalize: Character. Normalization method: "minmax" (default, maps each indicator to [0, 1]) or "zscore" (standardizes by mean and SD — useful for heterogeneous indicator scales but requires back- transformation for interpretation).
weights: Named numeric vector. Within-pillar indicator weights. Names must match indicator column names in the respective data frame. Indicators not listed receive weight 1. Weights are normalized to sum to 1 within each pillar. Example: c(pct_elderly = 2, pct_children = 1) doubles the influence of elderly share in the sensitivity pillar.
pillar_weights: Named numeric vector with elements exposure, sensitivity, and adaptive_capacity. Controls the relative contribution of each pillar to the final VI. Default c(1, 1, 1) (equal weights). Absent pillars automatically receive weight 0.
hot_percentile: Numeric in (0, 1). Quantile used as the "hot" threshold for DLNM extraction. Default 0.99. Only used when fits is provided.
cold_percentile: Numeric in (0, 1). Quantile used as the "cold" threshold for DLNM extraction. Default 0.01. Only used when fits is provided.
lang: Character. Language for messages: "pt" (default), "en", "es".
verbose: Logical. Print progress messages. Default TRUE.

Value

A climasus_vi object (named list) with:

$vi_table: Tibble sorted by vi_rank (1 = most vulnerable). Columns: city identifier, vi_score ∈ [0, 1], exposure_score, sensitivity_score, adaptive_capacity_score (raw, before inversion), vi_rank (integer), vi_percentile (0–100, higher = more vulnerable relative to peers).
$pillar_scores: Long-format tibble with columns city identifier, pillar ("exposure", "sensitivity", "adaptive_capacity"), and score (raw pillar score before AC inversion).
$normalized_indicators: Wide tibble: city identifier + all normalized indicator values, prefixed by pillar (exp_*, sen_*, ac_*).
$raw_indicators: Wide tibble: city identifier + all original (un-normalized) indicator values, prefixed by pillar.
$weights: Named list with within-pillar normalized weights for exposure, sensitivity, and adaptive_capacity, plus the normalized pillar weights vector.
$gini_coefficient: Gini coefficient of the VI distribution across cities (0 = perfect equality, 1 = all burden on one city).
$meta: Named list of all parameters used in this call.

Details

Exposure quantifies how much climate hazard a city experiences (e.g., mean maximum temperature, number of heat-wave days, threshold exceedances from sus_climate_aggregate()). Sensitivity captures how responsive local health outcomes are to the hazard (e.g., percentage elderly, chronic-disease rates, DLNM-derived cumulative RRs from sus_mod_dlnm()). Adaptive Capacity reflects ability to cope (e.g., HDI, piped-water coverage, healthcare density from sus_census_join() or sus_spatial_join()). Providing fits — a named list of climasus_dlnm objects — automatically extracts heat and cold RRs plus a sensitivity index and merges them into the sensitivity pillar.

Formula

Each indicator column $x_{ij}$ is normalized to $\tilde{x}_{ij}$ ∈ [0, 1] (min-max) or $\in \mathbb{R}$ (z-score). The pillar score for city $i$ is the within-pillar weighted mean of its normalized indicators. The adaptive-capacity pillar is inverted before combining (higher capacity ↔ lower vulnerability):

$$VI_i = \frac{w_E \cdot E_i + w_S \cdot S_i + w_{AC} \cdot (1 - AC_i)} {w_E + w_S + w_{AC}}$$

Missing pillar scores for a city are omitted and remaining weights re-normalized, so partial data does not force full exclusion.

References

IPCC (2022). Sixth Assessment Report — Working Group II. Chapter 16: Key Risks across Sectors and Regions. Cambridge University Press.

Turner, B.L., et al. (2003). A framework for vulnerability analysis in sustainability science. PNAS, 100(14), 8074–8079. doi:10.1073/pnas.1231335100

Cutter, S.L., et al. (2003). Social vulnerability to environmental hazards. Social Science & Medicine, 56(11), 2301–2322. doi:10.1016/S0277-9536(02)00605-X

Examples

if (FALSE) { # \dontrun{
# ── Minimal example with two pillars ─────────────────────────────────────
exposure_df <- data.frame(
  city = c("fortaleza", "recife", "salvador"),
  mean_tmax = c(32.1, 30.5, 31.2),
  heat_wave_days = c(45, 30, 38)
)
adaptive_capacity_df <- data.frame(
  city = c("fortaleza", "recife", "salvador"),
  hdi  = c(0.754, 0.772, 0.759),
  pct_piped_water = c(72.1, 68.4, 74.3)
)
vi <- sus_mod_vulnerability_index(
  exposure_df          = exposure_df,
  adaptive_capacity_df = adaptive_capacity_df,
  lang = "pt"
)
print(vi)
tidy(vi)

# ── Full 3-pillar with DLNM auto-extraction ───────────────────────────────
dlnm_fits <- list(
  fortaleza = sus_mod_dlnm(df_fortaleza, ...),
  recife    = sus_mod_dlnm(df_recife, ...)
)
vi_full <- sus_mod_vulnerability_index(
  exposure_df          = exposure_df,
  fits                 = dlnm_fits,          # auto-extracted to sensitivity
  adaptive_capacity_df = adaptive_capacity_df,
  weights              = c(mean_tmax = 2),   # double-weight temperature
  pillar_weights       = c(exposure = 1.5, sensitivity = 1, adaptive_capacity = 1),
  lang = "en"
)
} # }