Skip to contents

Import Palmer Drought Severity Index (PDSI) for Brazilian Municipalities

Source: R/sus_grid_pdsi.R
sus_grid_pdsi.Rd

sus_grid_pdsi() downloads Palmer Drought Severity Index (PDSI) data, crops it to Brazil, spatially aggregates to municipalities, and returns a climasus_df compatible with sus_mod_dlnm() and sus_climate_anomaly().

PDSI (Palmer, 1965) quantifies cumulative moisture departures relative to local climate normals using a two-layer soil water balance model. Values range from approximately -10 (extreme drought) to +10 (extreme wet), with operational categories at -2 (moderate drought) to -4 (extreme drought). Health applications in Brazil:

  • Drought (PDSI < -2): malnutrition, diarrheal disease, mental health stress, vector-borne disease in semi-arid Northeast and Amazonia

  • Wet periods (PDSI > 2): leptospirosis, hepatitis A, flooding

Available sources:

  • "terraclimate" (default): TerraClimate monthly PDSI (Abatzoglou et al., 2018; University of Idaho). Resolution 1/24deg (~4 km), 1950-2025, WGS84, no authentication. One NetCDF file (~165 MB) per year.

  • "noaa_psl": Dai (2011) self-calibrated PDSI from NOAA Physical Sciences Laboratory. Resolution 2.5deg, 1850-2018, single global file (~40 MB). Coarser but longer record.

Usage

sus_grid_pdsi(
  years = NULL,
  months = 1:12,
  source = c("terraclimate", "noaa_psl"),
  municipalities = NULL,
  raster_area = FALSE,
  agg_fun = "mean",
  crop_brazil = TRUE,
  use_cache = TRUE,
  cache_dir = "~/.climasus4r_cache/pdsi",
  lang = "pt",
  verbose = TRUE
)

Arguments

years

Integer vector. Years to download. TerraClimate: 1950-2025. NOAA PSL: 1850-2018. NULL (default) = last two complete years.

months

Integer vector (1-12). Months to include. Default 1:12.

source

Character. Data source: "terraclimate" (default) or "noaa_psl".

municipalities

An sf POLYGON object (e.g., from geobr::read_municipality()). When provided, rasters are aggregated and a climasus_df is returned. If NULL, returns cached NetCDF file paths.

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 (one layer per date), cropped to the same bounding box used elsewhere.

  • an sf POLYGON object – return the SpatRaster further 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) if municipalities is provided.

agg_fun

Character. Spatial aggregation for exactextractr::exact_extract(). Default "mean" (area-weighted).

crop_brazil

Logical. Crop global rasters to Brazil's bounding box. Default TRUE.

use_cache

Logical. Reuse cached NetCDF files and Parquet results. Default TRUE.

cache_dir

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

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, date (Date, first day of month), and pdsi (numeric, unitless). Metadata: stage = "climate", type = "pdsi".

  • If municipalities = NULL: a named character vector of cached NetCDF file paths, or, per raster_area, an in-memory terra::SpatRaster with one layer per date, optionally cropped and masked to an area of interest.

PDSI classification


 PDSI >= +4.0 : Extremely wet
 PDSI  +3.0 to +3.99 : Very wet
 PDSI  +2.0 to +2.99 : Moderately wet
 PDSI  -1.99 to +1.99 : Near normal
 PDSI  -2.0 to -2.99 : Moderate drought  (D1)
 PDSI  -3.0 to -3.99 : Severe drought    (D2)
 PDSI <= -4.0 : Extreme drought           (D3-D4)

Data sources

Packages required

terra and exactextractr (both in Suggests) are required when municipalities is provided.

See also

sus_climate_compute_spi(), sus_climate_compute_spei(), sus_grid_chirps(), sus_grid_join(), sus_mod_dlnm()

Examples

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

# TerraClimate PDSI for Mato Grosso, 2015-2022
pdsi_mt <- sus_grid_pdsi(
  years          = 2015:2022,
  months         = 1:12,
  municipalities = mt_mun,
  lang           = "pt"
)
sus_meta(pdsi_mt, "stage")  # "climate"
sus_meta(pdsi_mt, "type")   # "pdsi"

# Longer history with NOAA PSL (2.5 deg)
pdsi_hist <- sus_grid_pdsi(
  years          = 1960:2018,
  source         = "noaa_psl",
  municipalities = mt_mun,
  lang           = "en"
)

# Join to health data for DLNM
combined <- sus_grid_join(sih_mt, pdsi_mt)
} # }