Join Gridded Environmental Data to Health Data

sus_grid_join() merges the municipality × date output of any sus_grid_*() function (ERA5, CHIRPS, GHAP, CAMS, fires, PRODES, …) with a health climasus_df produced by sus_spatial_join() or sus_data_aggregate(). The result is a single climasus_df at stage = "climate" ready for sus_mod_dlnm(), sus_climate_anomaly(), and sus_mod_vulnerability_index().

This function is the bridge between the gridded environmental pipeline (sus_grid_*) and the health pipeline (sus_data_import → … → sus_spatial_join), equivalent to the role sus_climate_aggregate() plays for station-based INMET data.

Usage

sus_grid_join(
  health_data,
  grid_data,
  by = c("code_muni", "date"),
  type_out = NULL,
  lang = "pt",
  verbose = TRUE
)

Arguments

health_data

A climasus_df at stage "spatial", "aggregate", or "census". Must contain code_muni (character) and date (Date) columns.

grid_data

A climasus_df at stage "climate" produced by any sus_grid_*() function. Must contain code_muni and date columns and at least one environmental variable column.

by

Character vector. Join key columns. Default c("code_muni", "date"). Change to c("code_muni") if joining annual grid data (e.g., PRODES) to monthly health data — the join will broadcast the annual value to all months.

type_out

Character. Overrides sus_meta$type in the result. NULL (default) inherits the type from grid_data.

lang

Character. Message language: "pt" (default), "en", "es".

verbose

Logical. Print progress messages. Default TRUE.

Value

A climasus_df with all columns from health_data plus the environmental variable columns from grid_data. Metadata: stage = "climate", type inherited from grid_data (or type_out). Rows from health_data with no matching grid row receive NA for grid columns.

Temporal granularity mismatch

If health_data has monthly dates (YYYY-MM-01) and grid_data has daily dates, the join will produce NAs for most rows. In that case, first aggregate grid_data to monthly resolution with sus_climate_aggregate() or by passing by = c("code_muni") (annual grid data only) or summarising manually before calling sus_grid_join().

See also

sus_grid_era5(), sus_grid_chirps(), sus_grid_fires(), sus_grid_prodes(), sus_climate_aggregate(), sus_mod_dlnm()

Examples

if (FALSE) { # \dontrun{
library(geobr)
mt_mun <- read_municipality(code_muni = "MT", year = 2020)

# Health data (SIH respiratory hospitalisations)
sih_agg <- sus_data_import(system = "SIH", years = 2020, uf = "MT") |>
  sus_data_clean_encoding() |>
  sus_data_standardize() |>
  sus_data_filter_cid(cid_group = "respiratorio") |>
  sus_data_aggregate() |>
  sus_spatial_join(municipalities = mt_mun)

# Gridded climate data
era5 <- sus_grid_era5(
  years          = 2020,
  municipalities = mt_mun,
  vars           = c("t2m", "tp")
)

# Join: one step to connect health + climate
combined <- sus_grid_join(sih_agg, era5)
sus_meta(combined, "stage")  # "climate"
sus_meta(combined, "type")   # "era5_land"

# Annual deforestation joined to monthly health data (no date in by)
prodes <- sus_grid_prodes(years = 2020, biomes = "Amazon",
                           uf = "MT", municipalities = mt_mun)
combined2 <- sus_grid_join(sih_agg, prodes, by = "code_muni")
} # }