Skip to contents

Import Soil Moisture Volatility Index (SMVI / Flash Drought) Data

Source: R/sus_grid_smvi.R
sus_grid_smvi.Rd

sus_grid_smvi() downloads the global flash drought inventory based on the Soil Moisture Volatility Index (SMVI; Osman et al., 2024), spatially assigns events to Brazilian municipalities, and returns annual or monthly flash drought statistics as a climasus_df compatible with sus_mod_dlnm() and sus_mod_vulnerability_index().

What is SMVI? SMVI detects flash droughts — rapid, high-impact soil moisture deficits that develop within days to weeks. Unlike SPI/SPEI/PDSI (which measure cumulative drought severity), SMVI captures the speed of soil moisture decline by comparing a 5-day running average of root-zone soil moisture (0–100 cm) against a 20-day running average. A flash drought event begins when the 5-day average drops below the 20-day average AND reaches the 20th percentile deficit threshold.

Why SMVI is different from SPI/SPEI/PDSI:

  • SPI/SPEI/PDSI measure how dry a period is (severity)

  • SMVI measures how fast a drought develops (onset speed) — flash droughts can devastate crops, trigger wildfires, and compromise water supply with little warning

Health connections in Brazil:

  • Malnutrition & food insecurity: flash droughts destroy crops within weeks; 1–3 month lag to increased child malnutrition in semi-arid Northeast and Amazônia

  • Leptospirosis: rapid soil rewetting after flash drought events concentrates rodents near water, increasing transmission; 1–4 week lag

  • Leishmaniasis: drought-driven human migration to water sources increases sandfly contact; 2-year lag documented in Bahia

  • Waterborne disease: water shortage during flash drought increases dependence on unclean sources

Data source: Global Flash Drought Inventory (Osman et al., 2024). Based on NASA GLDAS-2 root-zone soil moisture (1990–2021). No authentication required. Events file (109 MB) covers the full global domain at 0.25° resolution and is downloaded once and cached.

Usage

sus_grid_smvi(
  years = NULL,
  municipalities = NULL,
  aggregate_by = c("year", "month"),
  brazil_only = TRUE,
  use_cache = TRUE,
  cache_dir = "~/.climasus4r_cache/smvi",
  lang = "pt",
  verbose = TRUE
)

Arguments

years

Integer vector. Years to include. Must be within 1990–2021. NULL (default) returns all available years.

municipalities

An sf POLYGON object (e.g., from geobr::read_municipality()). When provided, flash drought events are spatially assigned to municipalities and statistics are aggregated. If NULL, returns the raw event data frame for Brazil filtered to the requested years.

aggregate_by

Character. Temporal resolution of the output when municipalities is provided. One of "year" (default) or "month". Annual aggregation counts flash drought events and their total duration per municipality per year.

brazil_only

Logical. Filter the global dataset to Brazil's bounding box (-75 to -28 lon, -35 to 6 lat) before processing. Default TRUE.

use_cache

Logical. Reuse cached files. Default TRUE.

cache_dir

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

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 — 7-digit IBGE municipality code

    • date — Date (Jan 1 for annual; first day of month for monthly)

    • n_fd_events — integer count of flash drought events

    • fd_total_days — total days under flash drought

    • fd_mean_severity — mean severity (SV) across events

    • fd_max_severity — maximum severity (SV) in the period

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

  • If municipalities = NULL: a climasus_df with raw event data columns: cell_id, Lon, Lat, fstdate, lstdate, SV, duration_days.

Algorithm

SMVI flash drought detection (Osman et al., 2024):

  1. Compute 5-day and 20-day running averages of root-zone soil moisture (RZSM, 0–100 cm) from NASA GLDAS-2 data.

  2. A flash drought onset occurs when the 5-day average drops below the 20-day average.

  3. A flash drought event is confirmed when the RZSM deficit relative to the 20th percentile threshold is exceeded.

  4. Severity (SV) quantifies the cumulative soil moisture deficit during the event.

Data source

Osman, M. et al. (2024). A global flash drought inventory based on soil moisture volatility. Scientific Data, 11, 916. doi:10.1038/s41597-024-03809-9
Data: https://www.hydroshare.org/resource/642ff72592404a17bb85a8a92b4dbcd6/ (CC BY-SA 4.0, no authentication required)

See also

sus_climate_compute_spi(), sus_climate_compute_spei(), sus_grid_pdsi(), sus_grid_join(), sus_mod_dlnm()

Examples

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

# Annual flash drought statistics for Mato Grosso
smvi_mt <- sus_grid_smvi(
  years          = 2000:2021,
  municipalities = mt_mun,
  aggregate_by   = "year",
  lang           = "pt"
)
sus_meta(smvi_mt, "stage")  # "climate"
sus_meta(smvi_mt, "type")   # "smvi"

# Monthly resolution
smvi_mo <- sus_grid_smvi(
  years          = 2015:2021,
  municipalities = mt_mun,
  aggregate_by   = "month"
)

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