Skip to contents

Import CHIRPS Rainfall Data for Brazilian Municipalities

Source: R/sus_grid_chirps.R
sus_grid_chirps.Rd

sus_grid_chirps() downloads CHIRPS v2.0 precipitation data, crops it to Brazil, spatially aggregates to municipalities, and returns a climasus_df compatible with sus_mod_dlnm() and sus_climate_anomaly().

CHIRPS (Climate Hazards Group InfraRed Precipitation with Station data) is a quasi-global, 0.05\(^\circ\) (~5 km) daily rainfall dataset from UCSB CHC covering 1981 to present. It combines satellite imagery with station data and is considered the best freely available high-resolution rainfall product for Brazil – particularly for leptospirosis, diarrheal disease, and dengue analyses where precipitation is the key exposure.

No authentication is required.

Usage

sus_grid_chirps(
  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/chirps",
  lang = "pt",
  verbose = TRUE
)

Arguments

resolution

Character. Temporal resolution of source files:

  • "monthly" (default) – one file per month (~5-20 MB each); returns mm/month.

  • "daily" – one file per day (~3 MB each); returns mm/day. Recommended only for short periods; a full year = 365 downloads.

  • "annual" – one file per year; returns mm/year.

years

Integer vector. Years to download. Coverage: 1981 to present for daily/monthly; 1981-2024 for annual. NULL defaults to the last two complete years.

months

Integer vector (1-12). Months to include for daily and monthly resolutions. Ignored for annual. Default 1:12.

municipalities

An sf POLYGON object (e.g., from geobr::read_municipality()). When provided, rasters are aggregated and a climasus_df is returned. If NULL, a named character vector of cached file paths is returned instead (see raster_area).

raster_area

Controls what is returned when municipalities = NULL. One of:

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

  • TRUE – return an in-memory terra::SpatRaster (one layer per date, named by date), full extent.

  • an sf POLYGON object – return the SpatRaster cropped and masked to that area (e.g. a municipality or state from geobr::read_municipality()/geobr::read_state()).

  • a 2-letter Brazilian state code (e.g. "MT") – the state boundary is auto-downloaded via geobr (cached) and used to crop and mask the SpatRaster.

Ignored (with the file-path/tibble behavior taking precedence) if municipalities is provided.

agg_fun

Character. Spatial aggregation function for exactextractr::exact_extract(). Default "mean" (area-weighted mean). For rainfall totals over a municipality use "sum".

crop_brazil

Logical. Crop global rasters to Brazil's bounding box before aggregation. Reduces memory usage significantly. Default TRUE.

use_cache

Logical. Reuse previously downloaded raster files and aggregated Parquet caches. Default TRUE.

cache_dir

Character. Root cache directory. Default "~/.climasus4r_cache/chirps".

lang

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

verbose

Logical. Print progress messages. Default TRUE.

Value

  • If municipalities is provided: a climasus_df with columns code_muni (character), date (Date), and rainfall_chirps_mm (numeric). Metadata: stage = "climate", type = "chirps".

  • If municipalities = NULL: a named character vector of paths to the cached GeoTIFF/gz files, or (per raster_area) an in-memory terra::SpatRaster with one layer per date, optionally cropped and masked to an area of interest.

Units

  • Daily: mm/day

  • Monthly: mm/month (cumulative)

  • Annual: mm/year (cumulative)

CHIRPS missing/no-data value (-9999) is automatically converted to NA.

Data source

Funk, C. et al. (2015). The climate hazards infrared precipitation with stations – a new environmental record for monitoring extremes. Scientific Data, 2, 150066. doi:10.1038/sdata.2015.66
Data: https://data.chc.ucsb.edu/products/CHIRPS-2.0/

Packages required

Spatial aggregation requires terra and exactextractr (both in Suggests). Install with install.packages(c("terra", "exactextractr")).

See also

sus_grid_era5(), sus_climate_anomaly(), sus_mod_dlnm()

Examples

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

# Monthly rainfall for Mato Grosso, 2020
chirps <- sus_grid_chirps(
  resolution    = "monthly",
  years         = 2020,
  municipalities = mt_mun,
  lang          = "pt"
)
sus_meta(chirps, "stage")  # "climate"
sus_meta(chirps, "type")   # "chirps"

# Daily rainfall, fire season
chirps_daily <- sus_grid_chirps(
  resolution    = "daily",
  years         = 2020,
  months        = 7:9,
  municipalities = mt_mun,
  agg_fun       = "mean",
  lang          = "en"
)

# Annual totals for all Brazil (no spatial aggregation)
paths <- sus_grid_chirps(
  resolution = "annual",
  years      = 2018:2022
)
} # }