Skip to contents

Import ERA5-Land Daily Climate Data for Brazilian Municipalities

Source: R/sus_grid_era5.R
sus_grid_era5.Rd

sus_grid_era5() downloads pre-processed ERA5-Land daily climate aggregates for Latin America from Zenodo and, optionally, spatially aggregates them to Brazilian municipalities. No API key is required.

The data source is the ERA5-Land Daily Aggregates for Latin America project (Saldanha, rfsaldanha.github.io), which provides NetCDF files (one per variable x month x year) at ~10 km spatial resolution for 1950-2025. Files are hosted on Zenodo under CC-BY 4.0.

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

Usage

sus_grid_era5(
  years,
  months = 1:12,
  vars = c("t2m", "tp"),
  municipalities = NULL,
  raster_area = FALSE,
  agg_fun = "mean",
  use_cache = TRUE,
  cache_dir = "~/.climasus4r_cache/era5",
  parallel = FALSE,
  workers = 2,
  lang = "pt",
  verbose = TRUE
)

Arguments

years

Numeric vector of years to import. Must be between 1950 and 2025. Example: 2010:2023, c(2019, 2021).

months

Integer vector of months to import (1-12). Default: 1:12 (all months).

vars

Character vector of variable aliases to download. Allowed values:

  • "t2m" – 2 m temperature mean (-> tair_dry_bulb_c, degC)

  • "t2m_max" – 2 m temperature maximum (-> tair_max_c, degC)

  • "t2m_min" – 2 m temperature minimum (-> tair_min_c, degC)

  • "td2m" – 2 m dewpoint temperature mean (-> dew_point_c, degC)

  • "u10" – 10 m u-component of wind mean (-> ws_10m_u_m_s, m/s)

  • "v10" – 10 m v-component of wind mean (-> ws_10m_v_m_s, m/s)

  • "sp" – surface pressure mean (-> patm_hpa, hPa)

  • "tp" – total precipitation daily sum (-> rainfall_mm, mm)

  • "all" – all variables above

Default: c("t2m", "tp").

municipalities

An sf object with polygon geometries representing the areas to which raster data will be aggregated (typically Brazilian municipalities from geobr::read_municipality()). Must contain a column identifying each polygon – the function auto-detects code_muni, CD_MUN, or CD_GEOCMU. If NULL, returns a named list of downloaded NetCDF file paths instead of a climasus_df.

raster_area

Only used when municipalities = NULL. One of:

  • FALSE (default) – return the character vector of cached file paths.

  • TRUE – return an in-memory multi-layer terra::SpatRaster (layers named by date and variable), full extent – useful for plotting with sus_grid_plot().

  • 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 (silently) when municipalities is provided.

agg_fun

Character. Spatial aggregation function applied over raster pixels within each polygon. Any function supported by exactextractr::exact_extract(): "mean" (default, area-weighted), "sum", "median", "min", "max". For precipitation, "mean" gives the representative areal value.

use_cache

Logical. If TRUE (default), downloaded NetCDF files are stored in cache_dir and reused on subsequent calls.

cache_dir

Character. Directory for cached NetCDF files. Default: "~/.climasus4r_cache/era5". Created automatically if needed.

parallel

Logical. If TRUE, downloads run in parallel using the active future::plan(). Do not set a plan inside this function; configure it beforehand. Default: FALSE.

workers

Integer. Number of parallel workers when parallel = TRUE. Default: 2.

lang

Character. Language for messages: "pt" (default), "en", or "es".

verbose

Logical. If TRUE (default), prints progress messages.

Value

  • If municipalities is provided: a climasus_df tibble with columns code_muni (character), date (Date), and one column per requested variable (e.g., tair_dry_bulb_c, rainfall_mm). Metadata: stage = "climate", type = "era5_land".

  • If municipalities = NULL: a named character vector of paths to the downloaded NetCDF files (named by "{year}_{month}_{var}"), or, per raster_area, an in-memory multi-layer terra::SpatRaster with layers named "{indicator}_{date}", optionally cropped and masked to an area of interest.

Data Source

Saldanha, R. ERA5-Land Daily Aggregates for Latin America (1950-2025). Zenodo. https://zenodo.org/doi/10.5281/zenodo.10013254. CC-BY 4.0.

Unit Conversions Applied

  • Temperature (K -> degC): subtract 273.15

  • Precipitation (m -> mm): multiply by 1000

  • Pressure (Pa -> hPa): divide by 100

  • Wind components (m/s): no conversion needed

See also

sus_climate_anomaly(), sus_climate_aggregate(), sus_mod_dlnm()

Examples

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

# Temperature and precipitation for Mato Grosso, Q1 2020
era5 <- sus_grid_era5(
  years          = 2020,
  months         = 1:3,
  vars           = c("t2m", "tp"),
  municipalities = mt_mun,
  lang           = "pt"
)

sus_meta(era5, "stage")  # "climate"
sus_meta(era5, "type")   # "era5_land"

# All variables, no spatial aggregation (returns file paths)
paths <- sus_grid_era5(years = 2020, months = 1, vars = "all")
} # }