Skip to contents

Compute Standardized Precipitation Index (SPI)

Source: R/sus_climate_compute_spi.R
sus_climate_compute_spi.Rd

sus_climate_compute_spi() calculates the Standardized Precipitation Index (SPI; McKee et al., 1993) at multiple timescales from monthly cumulative precipitation already aggregated to municipalities.

SPI is a dimensionless index of precipitation anomaly relative to a long-term distribution: negative values indicate drought (SPI \(\le\) -1 = moderate, \(\le\) -1.5 = severe, \(\le\) -2 = extreme) and positive values indicate wet conditions. Multi-scale SPI is a leading indicator for several health outcomes in Brazil:

  • Drought (SPI-3, SPI-6): diarrhoeal disease, malnutrition, vector-borne diseases during water scarcity

  • Wet spells (SPI-1, SPI-3): leptospirosis, hepatitis A, dengue

The function requires monthly precipitation data (one row per municipality × month). The best upstream source is sus_grid_chirps() with resolution = "monthly" (0.05°, 1981–present). INMET-derived rainfall_mm from sus_climate_aggregate() also works.

Usage

sus_climate_compute_spi(
  df,
  var = "rainfall_chirps_mm",
  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 precipitation. Must contain code_muni (character), date (Date, first day of each month), and the column named by var.

var

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

scales

Integer vector. SPI timescales in months. Default c(1L, 3L, 6L, 12L). Common choices: 1 (soil moisture), 3 (short-term), 6 (agriculture/water supply), 12 (groundwater/streamflow).

ref_start

Date or NULL. Start of the calibration period for gamma distribution fitting. NULL (default) uses all available data. WMO recommends at least 30 years; CHIRPS 1981–2010 is ideal.

ref_end

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

min_n

Integer. Minimum number of non-NA, non-zero precipitation values required to fit the gamma distribution per location. Default 24L (2 years). Locations with fewer values receive NA for all SPI columns.

lang

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

verbose

Logical. Print progress messages. Default TRUE.

Value

The input climasus_df with additional columns:

  • spi_{s}mo — SPI at timescale s months (numeric, dimensionless)

For example, scales = c(1, 3, 6, 12) adds spi_1mo, spi_3mo, spi_6mo, spi_12mo. Metadata: stage = "climate", type = "spi".

SPI classification


 SPI ≥  2.0 : Extremely wet
 SPI   1.5 to  1.99 : Very wet
 SPI   1.0 to  1.49 : Moderately wet
 SPI  -0.99 to  0.99 : Near normal
 SPI  -1.0 to -1.49 : Moderately dry (D1)
 SPI  -1.5 to -1.99 : Severely dry   (D2)
 SPI ≤ -2.0 : Extremely dry (D3-D4)

Algorithm

For each municipality and timescale s:

  1. Compute s-month rolling sum of precipitation using slider::slide_dbl().

  2. Estimate gamma distribution parameters (shape \(\alpha\), rate \(\beta\)) via method of moments from the calibration period, handling zero-inflation with a mixed distribution (McKee et al., 1993).

  3. Transform to standard normal: SPI = qnorm(p0 + (1-p0) * pgamma(x, shape, rate)), where p0 is the proportion of zeros.

References

McKee, T.B., Doesken, N.J., Kleist, J. (1993). The relationship of drought frequency and duration to time scales. Proceedings of the 8th Conference on Applied Climatology. American Meteorological Society.

See also

sus_grid_chirps(), sus_climate_anomaly(), sus_grid_join(), sus_mod_dlnm()

Examples

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

# Download monthly CHIRPS for Mato Grosso, 1990-2022
chirps_mt <- sus_grid_chirps(
  resolution    = "monthly",
  years         = 1990:2022,
  municipalities = mt_mun
)

# Compute SPI at 1-, 3-, 6- and 12-month timescales
spi_mt <- sus_climate_compute_spi(
  df         = chirps_mt,
  var        = "rainfall_chirps_mm",
  scales     = c(1L, 3L, 6L, 12L),
  ref_start  = as.Date("1991-01-01"),
  ref_end    = as.Date("2020-12-31"),
  lang       = "pt"
)

sus_meta(spi_mt, "stage")  # "climate"
sus_meta(spi_mt, "type")   # "spi"
names(spi_mt)              # ..., spi_1mo, spi_3mo, spi_6mo, spi_12mo

# Join to health data
combined <- sus_grid_join(health_mt, spi_mt)
} # }