Climate Anomaly Computation vs. INMET Climatological Normals

Computes climate anomalies by comparing observed meteorological data from sus_climate_inmet() against 30-year climatological normals from sus_climate_normals(). Three anomaly types are supported: absolute (obs − normal), relative ((obs − normal) / |normal| × 100 %), and standardized z-score ((obs − normal) / σ_obs). The result is a climasus_df ready for epidemiological modelling with sus_mod_dlnm(), sus_climate_compute_heatwaves(), or sus_mod_vulnerability_index().

Usage

sus_climate_anomaly(
  observed,
  normals,
  vars = NULL,
  method = c("absolute", "relative", "standardized", "all"),
  time_scale = c("monthly", "decadal"),
  station_col = "station_code",
  date_col = "date",
  lang = c("pt", "en", "es"),
  verbose = TRUE
)

Arguments

observed: A climasus_df from sus_climate_inmet() or sus_climate_aggregate(). At minimum must contain: a station identifier column (see station_col), a date column (see date_col), and at least one climate variable column covered by the vars mapping.
normals: A climasus_df from sus_climate_normals(). Must contain columns codigo, mes, decada, var_code, and valor. Run sus_climate_normals_meta() to see available var_code values.
vars: Named character vector mapping observed column names to normals var_code values, e.g. c(tair_max_c = "t_max", rainfall_mm = "precipitation"). NULL (default) auto-detects variables using the built-in map for standard INMET columns.
method: Character. Anomaly computation method: "absolute" (default), "relative", "standardized", or "all".
time_scale: Character. Temporal resolution for the anomaly: "monthly" (default) averages normals across the three decades of each month and aggregates observations by calendar month; "decadal" preserves the 10-day decade structure of INMET normals and is more precise for variables such as temperature extremes and precipitation.
station_col: Character. Name of the station identifier column in observed. Default "station_code". Must contain INMET codes matching the codigo column in normals.
date_col: Character. Name of the date or datetime column in observed. Default "date". Accepts Date or POSIXct.
lang: Character. Language for messages: "pt" (default), "en", "es".
verbose: Logical. Print progress messages. Default TRUE.

Value

A climasus_df at stage "climate" and type "anomaly". One row per station × year × month (or × decade when time_scale = "decadal"). Key columns:

station_col: Station identifier (same as station_col argument).
year: Calendar year of the observation.
month_num: Month number (1–12).
month_name: Portuguese month name, ASCII.
decade_num: Decade within month (1, 2, or 3). Present only when time_scale = "decadal".
{v}_obs: Observed monthly/decadal value (mean or sum depending on variable type).
{v}_normal: Climatological normal value.
{v}_anomaly: Absolute anomaly: obs − normal.
{v}_anomaly_pct: Relative anomaly (\ |normal| × 100. Only when method ∈ c("relative", "all").
{v}_anomaly_std: Standardized anomaly (z-score): (obs − normal) / σ_obs, where σ is the inter-annual SD of monthly observations for each station × month. Only when method ∈ c("standardized", "all").

Why anomalies matter for climate-health with DATASUS

Multi-city comparability: standardized anomalies make DLNM exposure-response curves poolable across cities with very different baseline climates (Manaus vs. Porto Alegre).
Extreme event attribution: anomaly peaks pinpoint the dates to correlate with DATASUS hospitalization or mortality surges.
Climate trend detection: a positive trend in temperature anomalies captures local warming for the IPCC Exposure pillar in sus_mod_vulnerability_index().
Vector-borne and waterborne diseases: precipitation anomalies detect flood/drought episodes — with a 2–4 week lag — relevant to dengue, leptospirosis, and diarrheal disease in SINAN.
Thermal comfort indices: anomaly-adjusted temperature feeds DLNM models without confounding by mean inter-city temperature differences.

Anomaly methods

Method	Formula	Primary use
`"absolute"`	obs − normal	Temperature anomalies (°C)
`"relative"`	(obs − normal) / \|normal\| × 100	Precipitation anomaly (%)
`"standardized"`	(obs − normal) / σ_obs	Multi-city pooling, DLNM input
`"all"`	All three	Exploratory analysis

Examples

if (FALSE) { # \dontrun{
# 1. Download data
obs  <- sus_climate_inmet(years = 2018:2023, uf = "RJ")
norm <- sus_climate_normals(period = "1991-2020",
                             target_var = c("t_max", "t_min",
                                            "t_mean_comp", "precipitation"))

# 2. Monthly absolute anomalies (default)
anom <- sus_climate_anomaly(obs, norm)

# 3. Standardized anomalies for multi-city DLNM pooling
anom_std <- sus_climate_anomaly(obs, norm,
                                 method     = "standardized",
                                 vars       = c(tair_dry_bulb_c = "t_mean_comp"))

# 4. Decadal precipitation anomalies — dengue/leptospirosis lag studies
anom_10d <- sus_climate_anomaly(obs, norm,
                                 method     = "relative",
                                 time_scale = "decadal",
                                 vars       = c(rainfall_mm = "precipitation"))

# 5. All methods at once — exploratory
anom_all <- sus_climate_anomaly(obs, norm, method = "all")
} # }