drought-monitor

Calculate SPI (Standardized Precipitation Index) and SPEI (Standardized Precipitation Evapotranspiration Index) for drought monitoring using NASA POWER API precipitation data.

Features

• SPI Calculation: Gamma distribution fitting + inverse normal transform
• SPEI Calculation: Water balance (P - PET) with log-logistic fitting
• Multiple Timescales: 1, 3, 6, 12, 24 months
• Drought Classification: 7 levels from extreme drought to extremely wet
• Trend Analysis: Linear regression on SPI time series
• Local CSV Mode: Offline processing with pre-downloaded data
• NASA POWER Integration: Auto-fetch global precipitation data (no API key)

Usage

# Calculate 3-month SPI for a location
python scripts\drought-monitor.py spi --lat 39.9042 --lon 116.4074 --start 2020-01-01 --end 2023-12-31 --scale 3

# Calculate 12-month SPEI from local water balance CSV
python scripts\drought-monitor.py spei --input water_balance.csv --scale 12

# Generate drought report
python scripts\drought-monitor.py report --input spi_3m.csv --output report.json

Parameters

Parameter	Description	Default
--lat	Latitude (-90 to 90)	Required
--lon	Longitude (-180 to 180)	Required
--start	Start date (YYYY-MM-DD)	Required
--end	End date (YYYY-MM-DD)	Required
--scale	SPI/SPEI timescale in months	3
--input	Local CSV for offline mode	None
--output	Output file path	Auto-generated

Installation

pip install requests>=2.28.0 tqdm numpy scipy pandas
# Or: pip install -r scripts/requirements.txt

Dependencies

Package	Purpose
scipy	Gamma/log-logistic distribution fitting
numpy	Numerical computation
pandas	CSV I/O and time series handling
requests	NASA POWER API calls
tqdm	Progress bars

Data Source

• NASA POWER (https://power.larc.nasa.gov/) — Public Domain
• Parameter: PRECTOTCORR (corrected precipitation, mm/day)
• Coverage: Global, 1984-present
• No API key required

Output Format

CSV output columns:

Column	Description
date	Monthly date (YYYY-MM)
precipitation	Monthly precipitation total (mm)
spi	SPI value (standardized)
classification	Drought/wet classification label

Batch / Multi-Location Support

# Loop over multiple locations in shell
for lat_lon in "39.9 116.4" "31.2 121.5" "23.1 113.3"; do
  set -- $lat_lon
  python scripts\drought-monitor.py spi --lat $1 --lon $2 --start 2020-01-01 --end 2023-12-31 --scale 3 --output "spi_${1}_${2}.csv"
done

Error Handling

Error	Cause	Solution
ConnectionError	Network issue	Check internet, retry
HTTP 429	Rate limit	Wait 60s, retry
ValueError	Invalid input (e.g., bad date)	Check parameter format
Empty output	No data for location/dates	Try different parameters
ModuleNotFoundError	Missing dep	Run pip install

Minimum Data Length

For reliable SPI/SPEI calculation, at least 20–30 years of monthly data is recommended. Shorter records may produce unreliable distribution fitting, especially for 12- and 24-month scales.

Trend Analysis Example

# After computing SPI, run trend analysis
python scripts\drought-monitor.py report --input spi_3m.csv --output trend.json

The report subcommand performs linear regression on the SPI time series and outputs slope, p-value, and trend direction.

Raw Data Export

To export the raw precipitation time series without SPI calculation, use:

python scripts\drought-monitor.py spi --lat 39.9042 --lon 116.4074 --start 2020-01-01 --end 2023-12-31 --scale 3 --export-raw

This produces an additional raw_precipitation.csv with daily/monthly precipitation.

Custom Classification Thresholds

The default thresholds follow McKee et al. (1993). To customize, pass --thresholds:

python scripts\drought-monitor.py spi --lat 39.9042 --lon 116.4074 --start 2020-01-01 --end 2023-12-31 --scale 3 --thresholds "0.5,1.0,1.5,2.0"

The 4 values define boundaries between: normal / moderate / severe / extreme (symmetric for wet/dry).

SPI Local CSV Mode

# Offline mode with pre-downloaded precipitation CSV
# CSV format: date (YYYY-MM-DD), precipitation (mm)
python scripts\drought-monitor.py spi --input precip.csv --scale 6

Citation

If you use this tool, please cite the SPI methodology:

@article{mckee1993relationship,
  title={The relationship of drought frequency and duration to time scales},
  author={McKee, Thomas B and Doesken, Nolan J and Kleist, John and others},
  journal={Proceedings of the 8th Conference on Applied Climatology},
  volume={17},
  number={22},
  pages={179--183},
  year={1993}
}

Visualization Guidance

• Time series plot: Plot SPI values over time with color-coded drought classification bands
• Drought map: Interpolate SPI values across multiple stations using IDW or Kriging for spatial drought maps
• Trend line: Overlay linear regression trend on SPI time series

import pandas as pd
import matplotlib.pyplot as plt

df = pd.read_csv("spi_3m.csv")
fig, ax = plt.subplots(figsize=(12, 4))
ax.fill_between(df["date"], df["spi"], 0, where=df["spi"]<0, color="red", alpha=0.3, label="Drought")
ax.fill_between(df["date"], df["spi"], 0, where=df["spi"]>=0, color="blue", alpha=0.3, label="Wet")
ax.plot(df["date"], df["spi"], color="black", linewidth=0.8)
ax.axhline(y=0, color="gray", linestyle="--")
ax.legend()
plt.xticks(rotation=45)
plt.tight_layout()
plt.savefig("spi_timeseries.png", dpi=150)

Drought Classification

SPI/SPEI Value	Classification
> 2.0	Extremely wet
1.5 to 2.0	Very wet
1.0 to 1.5	Moderate wet
-1.0 to 1.0	Normal
-1.5 to -1.0	Moderate drought
-2.0 to -1.5	Severe drought
< -2.0	Extreme drought

Troubleshooting

Error	Cause	Solution
ConnectionError	Network issue	Check internet, retry
HTTP 429	Rate limit	Wait 60s, retry
ValueError	Invalid input	Check parameter format
Empty output	No data	Try different parameters
ModuleNotFoundError	Missing dep	Run pip install

---

Advanced Usage

Batch SPI for Multiple Locations

while IFS=',' read -r id lat lon; do
  python scripts\drought-monitor.py spi     --lat $lat --lon $lon --scale 3     --start 2020-01-01 --end 2023-12-31     --output spi_${id}.csv
  sleep 1
done < locations.csv

CI/CD Integration (GitHub Actions)

# .github/workflows/drought-monitor.yml
name: Drought Monitoring
on:
  schedule:
    - cron: '0 6 1 * *'  # Monthly
jobs:
  spi:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: pip install requests scipy pandas
      - run: |
          python scripts\drought-monitor.py spi \
            --lat 39.9 --lon 116.4 --scale 3 \
            --start $(date -d '1 year ago' +%Y-%m-%d) \
            --end $(date +%Y-%m-%d) \
            --output data/beijing_spi3.csv

PostgreSQL Import

python scripts\drought-monitor.py spi   --lat 39.9 --lon 116.4 --scale 3   --start 2020-01-01 --end 2023-12-31   --output spi.csv

psql -d gis_db -c "\COPY spi_index(station_id, date, spi) FROM 'spi.csv' CSV HEADER"

Performance Tips

• --scale 1 for monthly agricultural drought; --scale 12 for long-term hydrological
• Add sleep 1 between location queries to respect NASA POWER rate limits
• Use --export-raw to get precipitation data without SPI calculation

---

中文说明

基于 NASA POWER API 降水数据计算 SPI（标准化降水指数）和 SPEI（标准化降水蒸散指数），用于干旱监测。

安装

pip install requests>=2.28.0 tqdm numpy scipy pandas
# 或: pip install -r scripts/requirements.txt

依赖

包	用途
scipy	Gamma/log-logistic 分布拟合
numpy	数值计算
pandas	CSV 读写和时间序列处理
requests	NASA POWER API 调用
tqdm	进度条

输出格式

CSV 输出列：

列名	说明
date	月度日期（YYYY-MM）
precipitation	月降水量（mm）
spi	SPI 值（标准化）
classification	干旱/湿润等级标签

批量/多位置支持

# Shell 循环处理多个位置
for lat_lon in "39.9 116.4" "31.2 121.5" "23.1 113.3"; do
  set -- $lat_lon
  python scripts\drought-monitor.py spi --lat $1 --lon $2 --start 2020-01-01 --end 2023-12-31 --scale 3 --output "spi_${1}_${2}.csv"
done

错误处理

错误	原因	解决方案
ConnectionError	网络问题	检查网络，重试
HTTP 429	速率限制	等待 60 秒后重试
ValueError	无效输入	检查参数格式
空输出	无数据	尝试不同参数
ModuleNotFoundError	缺少依赖	运行 pip install

最小数据长度

为获得可靠的 SPI/SPEI 计算结果，建议使用至少 20-30 年的月数据。较短的记录可能导致分布拟合不可靠，尤其是 12 和 24 个月尺度。

趋势分析示例

# 计算 SPI 后运行趋势分析
python scripts\drought-monitor.py report --input spi_3m.csv --output trend.json

report 子命令对 SPI 时间序列执行线性回归，输出斜率、p 值和趋势方向。

原始数据导出

导出未经 SPI 计算的原始降水时间序列：

python scripts\drought-monitor.py spi --lat 39.9042 --lon 116.4074 --start 2020-01-01 --end 2023-12-31 --scale 3 --export-raw

将生成包含日/月降水量的 raw_precipitation.csv。

自定义分级阈值

默认阈值遵循 McKee et al. (1993)。自定义阈值使用 --thresholds：

python scripts\drought-monitor.py spi --lat 39.9042 --lon 116.4074 --start 2020-01-01 --end 2023-12-31 --scale 3 --thresholds "0.5,1.0,1.5,2.0"

4 个值定义正常/中度/严重/极端之间的分界（湿润/干旱对称）。

SPI 本地 CSV 模式

# 离线模式，使用预下载的降水 CSV
# CSV 格式：date (YYYY-MM-DD), precipitation (mm)
python scripts\drought-monitor.py spi --input precip.csv --scale 6

引用格式

如果使用本工具，请引用 SPI 方法论：

@article{mckee1993relationship,
  title={The relationship of drought frequency and duration to time scales},
  author={McKee, Thomas B and Doesken, Nolan J and Kleist, John and others},
  journal={Proceedings of the 8th Conference on Applied Climatology},
  volume={17},
  number={22},
  pages={179--183},
  year={1993}
}

可视化指南

• 时间序列图：绘制 SPI 时间序列，按干旱等级着色
• 干旱地图：对多个站点的 SPI 值进行 IDW 或 Kriging 插值，生成空间干旱分布图
• 趋势线：在 SPI 时间序列上叠加线性回归趋势线

import pandas as pd
import matplotlib.pyplot as plt

df = pd.read_csv("spi_3m.csv")
fig, ax = plt.subplots(figsize=(12, 4))
ax.fill_between(df["date"], df["spi"], 0, where=df["spi"]<0, color="red", alpha=0.3, label="干旱")
ax.fill_between(df["date"], df["spi"], 0, where=df["spi"]>=0, color="blue", alpha=0.3, label="湿润")
ax.plot(df["date"], df["spi"], color="black", linewidth=0.8)
ax.axhline(y=0, color="gray", linestyle="--")
ax.legend()
plt.xticks(rotation=45)
plt.tight_layout()
plt.savefig("spi_timeseries.png", dpi=150)

故障排除

错误	原因	解决方案
ConnectionError	网络问题	检查网络，重试
HTTP 429	速率限制	等待 60 秒后重试
ValueError	无效输入	检查参数格式
空输出	无数据	尝试不同参数
ModuleNotFoundError	缺少依赖	运行 pip install

基于 NASA POWER API 降水数据计算 SPI（标准化降水指数）和 SPEI（标准化降水蒸散指数），用于干旱监测。

功能特性

• SPI 计算：伽马分布拟合 + 正态逆变换
• SPEI 计算：水分平衡（P - PET）+ Log-logistic 拟合
• 多时间尺度：1、3、6、12、24 个月
• 干旱分级：从极端干旱到极端湿润共 7 级
• 趋势分析：SPI 时间序列线性回归
• 本地 CSV 模式：支持离线处理已有数据
• NASA POWER 集成：自动获取全球降水数据（无需 API key）

使用方法

# 计算北京 3 个月 SPI
python scripts\drought-monitor.py spi --lat 39.9042 --lon 116.4074 --start 2020-01-01 --end 2023-12-31 --scale 3

# 从本地 CSV 计算 12 个月 SPEI
python scripts\drought-monitor.py spei --input water_balance.csv --scale 12

# 生成干旱报告
python scripts\drought-monitor.py report --input spi_3m.csv --output report.json

数据来源

• NASA POWER (https://power.larc.nasa.gov/) — 公共领域
• 参数：PRECTOTCORR（校正降水量，mm/天）
• 覆盖范围：全球，1984 年至今
• 无需 API key

干旱分级标准

SPI/SPEI 值	等级
> 2.0	极端湿润
1.5 至 2.0	非常湿润
1.0 至 1.5	中度湿润
-1.0 至 1.0	正常
-1.5 至 -1.0	中度干旱
-2.0 至 -1.5	严重干旱
< -2.0	极端干旱