Import GHAP High-Resolution Pollution Data for Brazilian Municipalities

sus_grid_pollution_ghap() downloads, crops, spatially aggregates, and caches GHAP (GlobalHighAirPollutants) raster data to Brazilian municipalities. No API key is required.

GHAP provides AI-generated, seamless ground-level air pollutant fields at 1 km (PM2.5, CO) and 10 km (O3) resolution. Files are downloaded as NetCDF from Zenodo, cropped to Brazil, aggregated with area-weighted extraction, and the result is stored as a Parquet cache for fast subsequent access.

Available pollutants and temporal coverage:

PM2.5 ("pm25") – daily, monthly & annual, 2017-2022, 1 km, \(\mu g/m^3\)
O3 ("o3") – annual only, 2000-2020, 10 km, ppb
CO ("co") – annual only, 2019-2022, 1 km, mg/m\(^3\)
NO2 ("no2") – data not yet publicly released

When municipalities is provided the function returns a climasus_df at stage = "climate", type = "pollution_ghap", compatible with sus_climate_anomaly(), sus_climate_aggregate(), and sus_mod_dlnm().

Usage

sus_grid_pollution_ghap(
  pollutants = "pm25",
  resolution = "monthly",
  years = NULL,
  months = 1:12,
  municipalities = NULL,
  raster_area = FALSE,
  agg_fun = "mean",
  crop_brazil = TRUE,
  use_cache = TRUE,
  cache_dir = "~/.climasus4r_cache/ghap",
  lang = "pt",
  verbose = TRUE
)

Arguments

pollutants

Character vector. Pollutants to download. Accepted: "pm25", "o3", "co". Default: "pm25". Note: "no2" is not yet publicly available.

resolution

Character. Temporal aggregation of source files. One of "daily", "monthly", or "annual". Default: "monthly".

"daily" – available for PM2.5 only (2017-2022). Each monthly ZIP (~3 GB) is downloaded, extracted to a temp directory, each daily NetCDF is aggregated, and the result is cached as Parquet. Subsequent calls read from Parquet without re-extracting.
"monthly" – PM2.5 only (2017-2022).
"annual" – PM2.5 (2017-2022), O3 (2000-2020), CO (2019-2022).

O3 and CO automatically fall back to "annual" regardless of this parameter.

years

Integer vector. Years to download. Availability depends on pollutant and resolution:

PM2.5 daily, monthly & annual: 2017-2022
O3 annual: 2000-2020
CO annual: 2019-2022

NULL (default) returns all available years for the selected pollutant.

months

Integer vector (1-12). Months to include when resolution = "monthly". Ignored for annual data. Default: 1:12.

municipalities

An sf object with polygon geometries (e.g., from geobr::read_municipality()). If provided, raster data are aggregated to these polygons and a climasus_df is returned. If NULL, a named character vector of cached NetCDF file paths is returned instead (see raster_area).

raster_area

Only used when municipalities = NULL. One of:

FALSE (default) – return the character vector of cached file paths.
TRUE – return an in-memory terra::SpatRaster, full extent.
an sf POLYGON object – return the SpatRaster cropped and masked to that area.
a 2-letter Brazilian state code (e.g. "MT") – auto-download the state boundary via geobr (cached) and crop/mask to it.

Ignored (file-path behavior takes precedence) if municipalities is provided.

IMPORTANT limitation: for resolution = "daily" requests, each monthly ZIP contains one NetCDF file per day. Extracting and stacking every daily file into the returned raster would require decompressing multi-gigabyte archives on every call, so this option instead extracts and returns only the FIRST available day of each requested pollutant/month as a representative sample – the returned raster is NOT the full daily time series. Users who need the complete daily series should extract the cached ZIP themselves (see the file paths returned when raster_area = FALSE), or request narrower month ranges and read the daily NetCDF files directly. For "monthly" and "annual" resolutions the underlying NetCDF file is read directly (no ZIP involved), but only its first layer is used per requested pollutant/month/year for the same reason: to keep this option lightweight and predictable rather than silently building a large multi-day stack.

agg_fun

Character. Spatial aggregation function applied by exactextractr::exact_extract(). Default: "mean" (area-weighted). Other options: "sum", "median", "min", "max".

crop_brazil

Logical. Crop global rasters to Brazil's bounding box before extraction, significantly reducing memory use. Default TRUE.

use_cache

Logical. If TRUE (default), reuse previously downloaded NetCDF files and previously computed municipality-level Parquet caches.

cache_dir

Character. Root directory for all cached files. Default "~/.climasus4r_cache/ghap". Sub-directories are created per pollutant.

lang

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

verbose

Logical. Print progress messages. Default TRUE.

Value

If municipalities is provided: a climasus_df tibble with columns code_muni, date, and one column per pollutant (e.g., pm25_mean, o3_mean). Metadata: stage = "climate", type = "pollution_ghap".
If municipalities = NULL: a named character vector of paths to the cached NetCDF files, or, per raster_area, an in-memory terra::SpatRaster with one layer per requested pollutant/month, each layer being a single representative day (see raster_area for details and limitations), optionally cropped and masked to an area of interest.

Data source

Wei, J. et al. (2023). Estimating 1-km-resolution PM2.5 concentrations across China using the space-time random forest approach. Remote Sensing of Environment, 231, 111221. DOI: doi:10.5281/zenodo.10800980
Wei, J. et al. GlobalHighAirPollutants (GHAP) v2. Zenodo. CC-BY 4.0.
PM2.5: doi:10.5281/zenodo.10800980 | O3: doi:10.5281/zenodo.10208188 | CO: doi:10.5281/zenodo.14207363

Packages required

Spatial aggregation requires terra and exactextractr (both in Suggests). The Parquet cache requires arrow (in Imports). Install with install.packages(c("terra", "exactextractr")).

Examples

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

# PM2.5 monthly for Mato Grosso, Jan-Mar 2020
ghap <- sus_grid_pollution_ghap(
  pollutants    = "pm25",
  resolution    = "monthly",
  years         = 2020,
  months        = 1:3,
  municipalities = mt_mun,
  lang          = "pt"
)

sus_meta(ghap, "stage")  # "climate"
sus_meta(ghap, "type")   # "pollution_ghap"

# O3 annual, all available years
ghap_o3 <- sus_grid_pollution_ghap(
  pollutants    = "o3",
  resolution    = "annual",
  municipalities = mt_mun,
  lang          = "en"
)
} # }