Compute Standardized Precipitation-Evapotranspiration Index (SPEI)

sus_climate_compute_spei() calculates the Standardized Precipitation- Evapotranspiration Index (SPEI; Vicente-Serrano et al., 2010) at multiple timescales from monthly precipitation and potential evapotranspiration (PET) already aggregated to municipalities.

SPEI extends sus_climate_compute_spi() by accounting for atmospheric water demand (temperature-driven evapotranspiration) in addition to precipitation supply. It uses the climatic water balance D = P - PET and fits a 3-parameter log-logistic distribution, making it sensitive to warming- amplified drought. Health applications in Brazil:

Drought (SPEI-3 to SPEI-12): malnutrition, diarrhoeal disease, heat-amplified mortality, vector-borne diseases in the semi-arid Northeast and Amazônia
Wet spells (positive SPEI): leptospirosis, hepatitis A, dengue

PET options (choose one):

pet_method = "column" (default): pass a pre-computed PET column via pet_var. ERA5-Land potential evapotranspiration ("evap") or the FAO Penman-Monteith result are ideal.
pet_method = "thornthwaite": compute PET internally using only monthly mean temperature (temp_var). Suitable when only temperature data is available (e.g., INMET or ERA5 T2m).

Usage

sus_climate_compute_spei(
  df,
  rain_var = "rainfall_chirps_mm",
  pet_var = "pet_mm",
  pet_method = c("column", "thornthwaite"),
  temp_var = "tair_dry_bulb_c",
  scales = c(1L, 3L, 6L, 12L),
  ref_start = NULL,
  ref_end = NULL,
  min_n = 24L,
  lang = "pt",
  verbose = TRUE
)

Arguments

df

A climasus_df at stage = "climate" with monthly data. Must contain code_muni (character), date (Date, first day of each month), and the precipitation column named by rain_var.

rain_var

Character. Name of the monthly precipitation column (mm). Default "rainfall_chirps_mm". Other common value: "rainfall_mm".

pet_var

Character. Name of the monthly potential evapotranspiration column (mm). Used when pet_method = "column". Default "pet_mm". Ignored when pet_method = "thornthwaite".

pet_method

Character. How to obtain PET values. One of:

"column" (default): use the column named by pet_var directly.
"thornthwaite": compute Thornthwaite (1948) PET from monthly mean temperature in the column named by temp_var. Only needs temperature; less accurate than energy-balance methods but practical when only INMET or ERA5 T2m is available.

temp_var

Character. Name of the monthly mean temperature column (°C). Used only when pet_method = "thornthwaite". Default "tair_dry_bulb_c".

scales

Integer vector. SPEI timescales in months. Default c(1L, 3L, 6L, 12L).

ref_start

Date or NULL. Start of the calibration period for log-logistic distribution fitting. NULL uses all available data. WMO recommends at least 30 years.

ref_end

Date or NULL. End of the calibration period. NULL uses all available data.

min_n

Integer. Minimum number of non-NA values required to fit the log-logistic distribution per location. Default 24L (2 years). Locations with fewer values receive NA.

lang

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

verbose

Logical. Print progress messages. Default TRUE.

Value

The input climasus_df with additional columns:

spei_{s}mo — SPEI at timescale s months (numeric, dimensionless). For example, scales = c(3, 6, 12) adds spei_3mo, spei_6mo, spei_12mo.

Metadata: stage = "climate", type = "spei".

SPEI vs SPI

SPEI is more sensitive to climate change because rising temperatures increase PET even when precipitation is unchanged. Use SPEI-3 for short-term drought and health outcomes with 1-4 week lag (diarrhoea, dengue). Use SPEI-6 or SPEI-12 for water supply and agricultural drought (malnutrition, livelihood loss).

Algorithm

For each municipality and timescale s:

Compute climate water balance: D = P - PET (monthly).
Accumulate over s months via rolling sum.
Fit 3-parameter log-logistic distribution via L-moments (Vicente-Serrano et al., 2010). Falls back to empirical ECDF for numerically unstable cases.
Transform to standard normal.

References

Vicente-Serrano, S.M., Beguería, S., López-Moreno, J.I. (2010). A multiscalar drought index sensitive to global warming: the Standardized Precipitation Evapotranspiration Index. Journal of Climate, 23(7), 1696–1718. doi:10.1175/2009JCLI2909.1

Thornthwaite, C.W. (1948). An approach toward a rational classification of climate. Geographical Review, 38(1), 55–94.

Examples

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

# Option A: SPEI from CHIRPS + Thornthwaite PET (ERA5-Land temperature)
chirps_era5 <- sus_grid_era5(
  years = 1990:2022, vars = c("t2m"), municipalities = mt_mun
) |> sus_grid_join(
  sus_grid_chirps(resolution="monthly", years=1990:2022, municipalities=mt_mun)
)

spei_mt <- sus_climate_compute_spei(
  df         = chirps_era5,
  rain_var   = "rainfall_chirps_mm",
  pet_method = "thornthwaite",
  temp_var   = "tair_dry_bulb_c",
  scales     = c(3L, 6L, 12L),
  lang       = "pt"
)

# Option B: SPEI from pre-computed PET column
spei_mt2 <- sus_climate_compute_spei(
  df       = climate_df,         # has rainfall_mm and pet_mm columns
  rain_var = "rainfall_mm",
  pet_var  = "pet_mm",
  pet_method = "column",
  scales   = c(3L, 6L, 12L)
)

sus_meta(spei_mt, "stage")  # "climate"
sus_meta(spei_mt, "type")   # "spei"
names(spei_mt)              # ..., spei_3mo, spei_6mo, spei_12mo
} # }