GRASS logo

NAME

t.drought - Computes gridded drought indices (SPI, SPEI) as space-time raster datasets, from precipitation/PET STRDS imported via t.in.era5 if not already present.

KEYWORDS

temporal, hydrology, climate, drought

SYNOPSIS

t.drought
t.drought --help
t.drought indices=string[,string,...] start=string end=string [fit_start=string] [fit_end=string] [aggregation=string] [custom_days=integer] [scales=integer[,integer,...]] [region=name] [precipitation=name] [pet=name] output_prefix=string [cache_dir=name] [area=north,west,south,east] [--help] [--verbose] [--quiet] [--ui]

Flags:

--help
Print usage summary
--verbose
Verbose module output
--quiet
Quiet module output
--ui
Force launching GUI dialog

Parameters:

indices=string[,string,...] [required]
Drought indices to compute (cdi, lfi, rdri_agro are recognized but not yet implemented -- see t.drought.md ROADMAP)
Options: spi, spei, cdi, lfi, rdri_agro
Default: spi,spei
start=string [required]
Start date of the output period, YYYY-MM-DD
end=string [required]
End date of the output period, YYYY-MM-DD (inclusive)
fit_start=string
Start date of the calibration/reference period used to fit each index's distribution (default: start=). Use as long a baseline as you have data for -- WMO recommends >=30 years -- since start=/end= alone is usually too short for a stable fit.
fit_end=string
End date of the calibration/reference period (default: end=)
aggregation=string
Temporal aggregation level of one index period
Options: daily, weekly, monthly, yearly, custom
Default: monthly
custom_days=integer
Length in days of one aggregation period; required when aggregation=custom
scales=integer[,integer,...]
Accumulation scales, in number of aggregation periods (with aggregation=monthly, 1,3,6,12,24,48 give the standard SPI-1/SPI-3/.../SPI-48 series; with other aggregation levels these are generalized N-period accumulations, not literal months)
Default: 1,3,6,12,24,48
region=name
Named region to process into (g.region region=); default is the current computational region
precipitation=name
Existing precipitation STRDS (mm per day); if not given, imported via t.in.era5
pet=name
Existing potential evapotranspiration STRDS (mm per day), needed for spei; if not given, imported via t.in.era5 (ERA5 reanalysis PET)
output_prefix=string [required]
STRDS name prefix; outputs are <output_prefix>_<index><scale>, e.g. drought_spi3
Default: drought
cache_dir=name
Directory to cache t.in.era5 downloads in (only used when precipitation=/pet= are not given); default a temporary directory
area=north,west,south,east
Bounding box in WGS84 degrees for t.in.era5 downloads (only used when precipitation=/pet= are not given); default derived from the region

Table of contents

DESCRIPTION

t.drought computes gridded (per-pixel) drought indices at one or more accumulation scales, over a chosen temporal aggregation level, and registers each <output_prefix>_<index><scale> result as its own space-time raster dataset (STRDS), e.g. drought_spi3, drought_spei12.

If precipitation= (and, for SPEI, pet=) are not given, the required STRDS are imported automatically via t.in.era5 -- pulling exactly the date range needed (the requested period, extended back far enough to cover the largest accumulation scale, and the calibration/reference period if it extends further back). t.in.era5's potential_evaporation variable (ERA5 reanalysis PET) is used for SPEI's water balance term.

INDICES

IndexStatus
spiImplemented -- Standardized Precipitation Index
speiImplemented -- Standardized Precipitation-Evapotranspiration Index
cdiNot yet implemented (see ROADMAP)
lfiNot yet implemented (see ROADMAP)
rdri_agroNot yet implemented (see ROADMAP)

Requesting cdi, lfi or rdri_agro in indices= currently fails with a clear error rather than silently doing nothing.

SPI

For each accumulation scale (see scales= below), precipitation is summed over a rolling window of that many aggregation periods. Within the calibration window (fit_start=/fit_end=), the accumulated values for each "season group" (see AGGREGATION LEVELS) are pooled per pixel and fit to a zero-inflated gamma distribution using Thom's approximate MLE (WMO 2012), vectorized per pixel. Each output period's accumulated value is then mapped through that pixel/season-group's fitted CDF and transformed to a standard-normal z-score -- the SPI value.

SPEI

Identical procedure, but on the water balance (precipitation minus PET) instead of raw precipitation, fit to a 3-parameter log-logistic distribution via unbiased probability-weighted moments (the ub-pwm estimator used by the R SPEI package's parglo(), Vicente-Serrano et al. 2010) instead of gamma. This is a closed-form L-moments-style fit, not full MLE -- matches the reference implementation's default, but note it if you are cross-checking against a different SPEI tool that defaults to MLE.

Because the log-logistic PWM fit uses order statistics, it requires a pixel to have a value in every calibration sample for that season group (no gaps) -- a season group with any missing period at a pixel is left unfit (NaN) at that pixel.

AGGREGATION LEVELS

aggregation=monthly (the default) reproduces the traditional station-based SPI-1/-3/-6/-12/-24/-48 series when scales= is left at its default 1,3,6,12,24,48 (accumulation scale = number of calendar months). Season groups are calendar months (1-12), so a month's fit uses only that same calendar month's history -- capturing seasonality the way standard SPI/SPEI does.

Other aggregation levels generalize the same procedure but the scale number no longer means literal months:

scales=1,3,6,12,24,48 with a non-monthly aggregation still means "1, 3, 6, ... consecutive periods", e.g. with aggregation=weekly a "scale 12" output is a 12-week accumulation, not 12 months -- name it accordingly when interpreting <prefix>_spi12 in that case.

CALIBRATION (fit_start=/fit_end=)

fit_start=/fit_end= define the reference period the gamma/log-logistic distributions are fit against, independent of the output period start=/end=. If omitted they default to start=/end=, which is fine for a quick test but not recommended for real use: WMO guidance for SPI is >=30 years of reference data, and the log-logistic PWM fit in particular is unstable with few samples. A warning is printed for any (scale, season-group) combination with fewer than 8 calibration samples.

t.drought automatically fetches history far enough back from min(start, fit_start) to cover both the calibration period and the largest requested accumulation scale's look-back window.

EXAMPLE

Standard monthly SPI/SPEI-1/3/6/12/24/48 over Iraq's Karkheh basin region for 2020-2023, calibrated against 1991-2023, importing ERA5 data automatically: 
g.region region=karkheh

t.drought indices=spi,spei start=2020-01-01 end=2023-12-31 \
  fit_start=1991-01-01 fit_end=2023-12-31 \
  aggregation=monthly scales=1,3,6,12,24,48 \
  output_prefix=karkheh cache_dir=$HOME/era5_cache
Weekly SPI-4/-8 (4- and 8-week accumulations) from an already-imported precipitation STRDS: 
t.drought indices=spi start=2022-01-01 end=2022-12-31 \
  aggregation=weekly scales=4,8 \
  precipitation=karkheh_precipitation output_prefix=karkheh_wk

ROADMAP

The remaining EDO/GDO-family indices are recognized in indices= but not yet implemented, since each needs a different external data source rather than just t.in.era5:

Each of these needs a download/ingest path built and verified against the actual portal (format, resolution, access terms) before it can be wired into t.drought the way t.in.era5 is for SPI/SPEI.

REQUIREMENTS

SEE ALSO

t.in.era5

AUTHORS

Yann Chemin

SOURCE CODE

Available at: t.drought source code (history)

Accessed: Sunday Sep 13 08:29:34 2026

Main index | Temporal index | Topics index | Keywords index | Graphical index | Full index

© 2003-2026 GRASS Development Team, GRASS 8.5.1dev Reference Manual