Drought Scan
Overview
Drought Scan is a Python library implementing a multi-temporal and basin-scale approach for drought analysis. It is designed to provide advanced tools for evaluating drought severity and trends at the river basin scale by integrating meteorological and hydrological data.
The methodology is described in the article:
Building a framework for a synoptic overview of drought (Read the article),
and is continuously developed within the activities of Drought Central (DroughtCentral).
Key Features
- Calculation of standardized drought indices (e.g., SPI, SQI, SPEI, SPETI, STI) via parametric (zero-inflated Gamma, Pearson III, z-score) or non-parametric (KDE) methods — or your own, registered once.
- Integration of precipitation, streamflow, PET, temperature, and teleconnection data for basin-level analysis.
- Multi-temporal scales for flexibility in drought assessment.
- Calibration of the multi-scale index (SIDI) against streamflow, global or seasonal, with block-bootstrap confidence intervals.
- Benchmarks of the integrated index against linear and parametric rainfall–runoff kernels.
- Spatial extension: gridded SPI-like/SIDI maps at every grid point within the basin.
- Statistical diagnostics for distribution selection and goodness-of-fit evaluation.
- Visualization tools for drought monitoring, deficit quantification, and seasonal analysis.
For examples and usage notes see:
- User Guide — How to initialize and use DroughtScan objects.
- Visualization Guide — Plotting methods and customization.
- Spatial Guide — Gridded SPI-like/SIDI maps and their native-unit reverse.
- Statistical Diagnostics — Distribution fitting and standardization tools.
- Common Errors — Troubleshooting guide.
Installation
Option 1:
DroughtScan is available on PyPI. To install the latest stable version:
pip install droughtscan
Option 2: Clone and install locally
Drought Scan can be installed directly from this repository.
Note: DroughtScan requires Python ≥3.9. If multiple Python versions are installed (e.g. 3.10 and 3.12), make sure pip and python refer to the same interpreter. You can check it by running
python --version
pip --version
The following instructions will download the package to your working directory (pwd). If you wish to download the package to a specific path, first navigate to the desired location with the terminal.
git clone https://github.com/PyDipa/DroughtScan.git
cd DroughtScan
pip install .
Option 3: Install directly from GitHub (no local clone)
pip install git+https://github.com/PyDipa/DroughtScan.git
To use a specific python interpreter, say for example Python 3.10, for option 2 use:
python3.10 -m pip install .
for option 3:
python3.10 -m pip install git+https://github.com/PyDipa/DroughtScan.git
Dependencies listed in the repository will be installed automatically in your Python environment during the installation process. Refer to the pyproject.toml file for more details about the DroughtScan package.
What Drought-Scan Does
Drought-Scan provides an end-to-end framework for monitoring and analyzing drought conditions at the basin scale.
It combines statistical drought indices, quantitative analysis, and visualization tools into a single Python package.
Core Capabilities
- Data handling: Organizes meteorological and hydrological time series (precipitation, streamflow, PET, temperature, teleconnections) into a consistent calendar (
m_cal) and spatial framework (shapefiles). - Drought indices:
- SPI (Standardized Precipitation Index) from 1 to K months (default K=36).
- SIDI (Standardized Integrated Drought Index): a weighted multi-scale index, standardized to mean 0 and variance 1.
- CDN (Cumulative Deviation from Normal): integrates long-term memory of anomalies by cumulating the standard index at 1-month scale.
- SQI (Standardized Streamflow Index): SPI-like indicator based on river discharge.
- SPEI / SPETI: Balance- and PET-based drought indices.
- Standardization methods: zero-inflated Gamma (
f_spi), Pearson III (f_spei), Gaussian KDE (f_kde, default), z-score (f_zscore); custom methods viaregister_standardization. Exact forward and inverse transforms (native_to_spi/spi_to_native). - Calibration against streamflow: the K and weighting scheme of the SIDI that best explain SQI₁ (also per season and with a time lag), with block-bootstrap CIs; benchmarks (OLS lag kernels, Nash-type Gamma kernel, IHACRES routing). R² is the squared Pearson correlation throughout.
- Visualization: the three "pillars" of drought monitoring (heatmap, SIDI, CDN), plus deficit/surplus bars, monthly profiles, spatial maps, and precipitation–streamflow diagnostics.
- Spatial extension: SPI-like and SIDI maps (and the native-unit deficit/surplus) at every grid point within the basin, for precipitation, PET, P−PET and temperature, with parallel processing.
Available Classes
| Class | Input | Index | Use case |
|---|---|---|---|
Precipitation |
NetCDF or arrays | SPI | Meteorological drought |
Streamflow |
CSV/Excel or arrays | SQI | Hydrological drought |
Pet |
NetCDF or arrays | SPETI | Evapotranspiration analysis |
Balance |
NetCDF (P + PET) | SPEI | Water balance drought |
Temperature |
NetCDF or arrays | STI | Temperature variability |
Teleindex |
CSV/Excel or arrays | (custom) | Large-scale climate drivers |
All classes share the same base (BaseDroughtAnalysis) and produce the same core outputs: ts, m_cal, spi_like_set, SIDI, CDN. Some analyses only apply to some classes — see the capability table in the User Guide §8.
Core Attributes
ts: monthly time series (precipitation, streamflow, etc.).m_cal: calendar aligned with the time series, shape (N, 2) with [month, year].spi_like_set: set of SPI-like indices at scales 1–K, shape (K, N).SIDI: Standardized Integrated Drought Index, shape (N, 5) for 5 weighting schemes.CDN: Cumulative Deviation from Normal, shape (N,).basin_name: name of the basin under analysis.index_name: name of the standardized index (e.g., 'SPI', 'SQI').shape: basin geometry (GeoDataFrame).area_kmq: area of the basin in km².K: maximum SPI scale (default 36).threshold: severity threshold (default −1; +1 forPetandTemperature).weight_index: default SIDI column before any calibration (default 2).calibration_mode:None,'global'or'seasonal'— which calibrationSIDIcarries.Pgrid/PETgrid/Tgrid/prec_grid,pet_grid: input gridded data within the basin (when initialized from NetCDF).
Main Methods
All classes (BaseDroughtAnalysis)
plot_scan(): full overview (heatmap, SIDI, CDN).plot_monthly_profile(): climatology plot (monthly profile) of the input variable.plot_boundary(): basin shapefile on an equal-area projection.normal_values(): "normal" values of the climatology (index = 0, exact inverse).native_to_spi()/spi_to_native(): exact conversion between native units and the index.find_trends(): deficit/surplus over moving windows from the reverse SPI (the numbers behindplot_trends).plot_trends(): CDN with deficit/surplus bars for multiple window sizes.deficit_from_spi()/volume_anomaly_rolling(): statistical and direct physical deficit over a window.plot_spi_fit(): plot the fitted relationship between index values and the raw variable.recalculate_SIDI(): recompute SIDI with a custom K (one value, or one per weighting scheme).export_scan_plot_csv(): export data needed to replicateplot_scanin external tools.severe_events_old(): obsolete, kept only to reproduce Di Paola et al. (2025).
Precipitation, Pet, Balance (drivers of a streamflow)
analyze_correlation(streamflow): R² of SIDI vs SQI₁ for every (K, weighting scheme); optional block bootstrap.analyze_correlation_seasonal(streamflow)/analyze_correlation_seasonal_rolling(streamflow): per season, and on moving windows of years.analyze_correlation_lagged(streamflow, lag): the same with the SIDI leading SQI₁ bylagmonths.set_optimal_SIDI()/set_optimal_SIDI_seasonal(): commit a global or seasonal calibration (mutually exclusive).plot_covariates(streamflow): calibrated SIDI alongside SQI₁.spi_sqi_corr(streamflow)/spi_sqi_corr_lagged(streamflow): month-wise SPIₖ–SQI₁ R² matrix, without or with a time lag.- Benchmarks:
benchmark_convolution(),Dspi_free(),benchmark_nash(),benchmark_ihacres(),analyze_convolution_irf().
Gridded objects (Precipitation, Pet, Balance, Temperature from NetCDF)
spatial_sidi(): gridded SIDI at a target date (follows the committed calibration).spatial_spi(): gridded SPI-like index and its native-unit deficit/surplus.plot_spatial(): maps of SIDI, the SPI-like index, or its reverse.
Precipitation only
ds_balance(streamflow)/ds_balance_all_schemes(streamflow): monthly water balance of the basin — the part of the streamflow anomaly the precipitation accounts for, and the part it does not.import_forecast(): import forecast ensembles.
Streamflow only
gap_filling(precipitation): reconstruct missing streamflow from a calibrated SIDI.plot_annual_ts(DSO): compare annual streamflow with an external driver.BFI(): Baseflow Index (requires the daily file,data_path).
Note: internal methods (prefixed with
_) are used for calculations and should not be called directly.
For detailed reference and examples, see the User Guide and Visualization Guide.
License
DroughtScan is distributed under the GNU GPL v3.0 for academic and non-commercial research use.
For any commercial or revenue-generating application, a separate commercial
license is required. A separate commercial license can be arranged outside this repository
and does not alter the open-source terms of the GPL for this codebase.
For inquiries: arianna.dipaola@cnr.it
Authors
- Arianna Di Paola CNR-IBE, Italy — Lead developer and maintainer; arianna.dipaola@cnr.it
- Massimiliano Pasqui CNR-IBE, Italy — Feedback, scientific guidance, methodological validation and review.
- Ramona Magno CNR-IBE, Italy — Feedback, scientific guidance, methodological validation and review.
- Leandro Rocchi CNR-IBE, Italy — Technical support.
Metadata
Release files for droughtscan 4.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| droughtscan-4.0.0.tar.gz | 193.8 kB | Without provenance | Details for droughtscan-4.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| droughtscan-4.0.0-py3-none-any.whl | Python 3 | none | any | Details for droughtscan-4.0.0-py3-none-any.whl |
Total release size: 387.1 kB
Release files / droughtscan-4.0.0.tar.gz
| Download URL | droughtscan-4.0.0.tar.gz |
|---|---|
| Size | 193.8 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
696663a0f8046e703179d4082e0a3996bd91fe0e315bfebbf1840dab6af9d961
|
|
BLAKE2b-256 checksum How to use checksums |
351007d9e75d440866ad74dda6ee4e5e4c3e5781d5c4c7d550688644977d1441
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.10.20
|
Release files / droughtscan-4.0.0-py3-none-any.whl
| Download URL | droughtscan-4.0.0-py3-none-any.whl |
|---|---|
| Size | 193.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
5d8c4e7eb73dd4f72b58d477ebe9c2cb7c2904c0fdeb69605f4cfa0ba957812b
|
|
BLAKE2b-256 checksum How to use checksums |
5ed0efcc37b2a23859d232580b348c546616beb11aaf46cb54df666037c0dda6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.10.20
|
Security for droughtscan 4.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.