drift-drought 0.1.2__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- drift_drought-0.1.2/.github/workflows/publish.yml +34 -0
- drift_drought-0.1.2/.github/workflows/tests.yml +15 -0
- drift_drought-0.1.2/.gitignore +9 -0
- drift_drought-0.1.2/.readthedocs.yaml +12 -0
- drift_drought-0.1.2/.zenodo.json +19 -0
- drift_drought-0.1.2/CITATION.cff +29 -0
- drift_drought-0.1.2/LICENSE +21 -0
- drift_drought-0.1.2/PKG-INFO +264 -0
- drift_drought-0.1.2/README.md +211 -0
- drift_drought-0.1.2/docs/_static/concept_tree.png +0 -0
- drift_drought-0.1.2/docs/_static/floor_scan.png +0 -0
- drift_drought-0.1.2/docs/_static/mini_benchmark.csv +9 -0
- drift_drought-0.1.2/docs/_static/mini_benchmark.png +0 -0
- drift_drought-0.1.2/docs/_static/mini_benchmark_cubes.csv +321 -0
- drift_drought-0.1.2/docs/_static/pulses_episodes.png +0 -0
- drift_drought-0.1.2/docs/_static/quickstart.png +0 -0
- drift_drought-0.1.2/docs/_static/scenarios.png +0 -0
- drift_drought-0.1.2/docs/api.rst +44 -0
- drift_drought-0.1.2/docs/benchmark.rst +61 -0
- drift_drought-0.1.2/docs/changelog.rst +22 -0
- drift_drought-0.1.2/docs/citing.rst +14 -0
- drift_drought-0.1.2/docs/concepts.rst +84 -0
- drift_drought-0.1.2/docs/conf.py +16 -0
- drift_drought-0.1.2/docs/gallery.rst +58 -0
- drift_drought-0.1.2/docs/index.rst +30 -0
- drift_drought-0.1.2/docs/installation.rst +14 -0
- drift_drought-0.1.2/docs/metrics.rst +61 -0
- drift_drought-0.1.2/docs/quickstart.rst +41 -0
- drift_drought-0.1.2/docs/testing.rst +55 -0
- drift_drought-0.1.2/examples/make_figures.py +168 -0
- drift_drought-0.1.2/examples/quickstart.py +60 -0
- drift_drought-0.1.2/pyproject.toml +44 -0
- drift_drought-0.1.2/src/driftdrought/__init__.py +10 -0
- drift_drought-0.1.2/src/driftdrought/baselines.py +123 -0
- drift_drought-0.1.2/src/driftdrought/confidence.py +97 -0
- drift_drought-0.1.2/src/driftdrought/core.py +443 -0
- drift_drought-0.1.2/src/driftdrought/data/amazon_orinoco_pulses.npz +0 -0
- drift_drought-0.1.2/src/driftdrought/indices.py +129 -0
- drift_drought-0.1.2/src/driftdrought/metrics.py +155 -0
- drift_drought-0.1.2/src/driftdrought/significance.py +101 -0
- drift_drought-0.1.2/src/driftdrought/synthetic.py +188 -0
- drift_drought-0.1.2/tests/test_core.py +78 -0
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
name: publish to PyPI
|
|
2
|
+
on:
|
|
3
|
+
release:
|
|
4
|
+
types: [published]
|
|
5
|
+
workflow_dispatch:
|
|
6
|
+
jobs:
|
|
7
|
+
build:
|
|
8
|
+
runs-on: ubuntu-latest
|
|
9
|
+
steps:
|
|
10
|
+
- uses: actions/checkout@v5
|
|
11
|
+
- uses: actions/setup-python@v6
|
|
12
|
+
with:
|
|
13
|
+
python-version: "3.12"
|
|
14
|
+
- run: pip install build twine
|
|
15
|
+
- run: python -m build
|
|
16
|
+
- run: twine check dist/*
|
|
17
|
+
- uses: actions/upload-artifact@v4
|
|
18
|
+
with:
|
|
19
|
+
name: dist
|
|
20
|
+
path: dist/
|
|
21
|
+
publish:
|
|
22
|
+
needs: build
|
|
23
|
+
runs-on: ubuntu-latest
|
|
24
|
+
environment:
|
|
25
|
+
name: pypi
|
|
26
|
+
url: https://pypi.org/project/drift-drought/
|
|
27
|
+
permissions:
|
|
28
|
+
id-token: write
|
|
29
|
+
steps:
|
|
30
|
+
- uses: actions/download-artifact@v4
|
|
31
|
+
with:
|
|
32
|
+
name: dist
|
|
33
|
+
path: dist/
|
|
34
|
+
- uses: pypa/gh-action-pypi-publish@release/v1
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
name: tests
|
|
2
|
+
on: [push, pull_request]
|
|
3
|
+
jobs:
|
|
4
|
+
test:
|
|
5
|
+
runs-on: ubuntu-latest
|
|
6
|
+
strategy:
|
|
7
|
+
matrix:
|
|
8
|
+
python-version: ["3.10", "3.11", "3.12"]
|
|
9
|
+
steps:
|
|
10
|
+
- uses: actions/checkout@v5
|
|
11
|
+
- uses: actions/setup-python@v6
|
|
12
|
+
with:
|
|
13
|
+
python-version: ${{ matrix.python-version }}
|
|
14
|
+
- run: pip install -e ".[test,plot]"
|
|
15
|
+
- run: pytest -q
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
{
|
|
2
|
+
"title": "DRIFT: Drought Regions Identified From the space-time component Tree",
|
|
3
|
+
"upload_type": "software",
|
|
4
|
+
"license": "MIT",
|
|
5
|
+
"creators": [
|
|
6
|
+
{
|
|
7
|
+
"name": "Sanchez H., Karel A.",
|
|
8
|
+
"orcid": "0000-0002-4961-9694"
|
|
9
|
+
}
|
|
10
|
+
],
|
|
11
|
+
"keywords": [
|
|
12
|
+
"drought",
|
|
13
|
+
"event detection",
|
|
14
|
+
"component tree",
|
|
15
|
+
"topological persistence",
|
|
16
|
+
"tracking"
|
|
17
|
+
],
|
|
18
|
+
"description": "Python package to detect, characterize and evaluate space-time drought events selected from the component tree of a deficit field (volume-weighted topological persistence, noise-adaptive threshold, lineage inheritance), with the synthetic benchmark, reference detectors, tracking metrics, event confidence and surrogate significance."
|
|
19
|
+
}
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
cff-version: 1.2.0
|
|
2
|
+
message: "If you use DRIFT, please cite the software and the article below."
|
|
3
|
+
title: "DRIFT: Drought Regions Identified From the space-time component Tree"
|
|
4
|
+
version: 0.1.2
|
|
5
|
+
date-released: 2026-11-21
|
|
6
|
+
license: MIT
|
|
7
|
+
doi: 10.5281/zenodo.24409548
|
|
8
|
+
identifiers:
|
|
9
|
+
- type: doi
|
|
10
|
+
value: 10.5281/zenodo.24409548
|
|
11
|
+
description: All versions (concept DOI)
|
|
12
|
+
- type: doi
|
|
13
|
+
value: 10.5281/zenodo.24409549
|
|
14
|
+
description: Version 0.1.1
|
|
15
|
+
repository-code: "https://github.com/karelsanchez/drift-drought"
|
|
16
|
+
authors:
|
|
17
|
+
- family-names: "Sanchez H."
|
|
18
|
+
given-names: "Karel A."
|
|
19
|
+
orcid: "https://orcid.org/0000-0002-4961-9694"
|
|
20
|
+
keywords: [drought, event detection, component tree, topological persistence, tracking]
|
|
21
|
+
preferred-citation:
|
|
22
|
+
type: article
|
|
23
|
+
title: "DRIFT for detecting and tracking spatiotemporal drought events with component trees"
|
|
24
|
+
authors:
|
|
25
|
+
- family-names: "Sanchez H."
|
|
26
|
+
given-names: "Karel A."
|
|
27
|
+
orcid: "https://orcid.org/0000-0002-4961-9694"
|
|
28
|
+
journal: "Water Resources Research (submitted)"
|
|
29
|
+
year: 2026
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Karel A. Sanchez H.
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,264 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: drift-drought
|
|
3
|
+
Version: 0.1.2
|
|
4
|
+
Summary: DRIFT: space-time drought events selected from the component tree of a deficit field
|
|
5
|
+
Project-URL: Documentation, https://drift-drought.readthedocs.io
|
|
6
|
+
Project-URL: Source, https://github.com/karelsanchez/drift-drought
|
|
7
|
+
Author-email: "Karel A. Sanchez H." <sanchezkarel@gmail.com>
|
|
8
|
+
License: MIT License
|
|
9
|
+
|
|
10
|
+
Copyright (c) 2026 Karel A. Sanchez H.
|
|
11
|
+
|
|
12
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
13
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
14
|
+
in the Software without restriction, including without limitation the rights
|
|
15
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
16
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
17
|
+
furnished to do so, subject to the following conditions:
|
|
18
|
+
|
|
19
|
+
The above copyright notice and this permission notice shall be included in all
|
|
20
|
+
copies or substantial portions of the Software.
|
|
21
|
+
|
|
22
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
23
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
24
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
25
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
26
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
27
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
28
|
+
SOFTWARE.
|
|
29
|
+
License-File: LICENSE
|
|
30
|
+
Keywords: component tree,drought,event detection,hydrology,topological persistence,tracking
|
|
31
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
32
|
+
Classifier: Programming Language :: Python :: 3
|
|
33
|
+
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
|
|
34
|
+
Classifier: Topic :: Scientific/Engineering :: Hydrology
|
|
35
|
+
Requires-Python: >=3.10
|
|
36
|
+
Requires-Dist: higra>=0.6
|
|
37
|
+
Requires-Dist: numba>=0.58
|
|
38
|
+
Requires-Dist: numpy>=1.24
|
|
39
|
+
Requires-Dist: pandas>=2.0
|
|
40
|
+
Requires-Dist: scikit-image>=0.21
|
|
41
|
+
Requires-Dist: scikit-learn>=1.3
|
|
42
|
+
Requires-Dist: scipy>=1.10
|
|
43
|
+
Requires-Dist: xarray>=2023.1
|
|
44
|
+
Provides-Extra: docs
|
|
45
|
+
Requires-Dist: matplotlib>=3.7; extra == 'docs'
|
|
46
|
+
Requires-Dist: sphinx-rtd-theme>=2; extra == 'docs'
|
|
47
|
+
Requires-Dist: sphinx>=7; extra == 'docs'
|
|
48
|
+
Provides-Extra: plot
|
|
49
|
+
Requires-Dist: matplotlib>=3.7; extra == 'plot'
|
|
50
|
+
Provides-Extra: test
|
|
51
|
+
Requires-Dist: pytest>=7; extra == 'test'
|
|
52
|
+
Description-Content-Type: text/markdown
|
|
53
|
+
|
|
54
|
+
# DRIFT — drought events from the space–time component tree
|
|
55
|
+
|
|
56
|
+
[](https://github.com/karelsanchez/drift-drought/actions/workflows/tests.yml)
|
|
57
|
+
[](https://drift-drought.readthedocs.io)
|
|
58
|
+
[](https://github.com/karelsanchez/drift-drought/blob/main/LICENSE)
|
|
59
|
+

|
|
60
|
+
[](https://doi.org/10.5281/zenodo.24409548)
|
|
61
|
+
|
|
62
|
+
**DRIFT** (*Drought Regions Identified From the space–time component Tree*) detects drought events in gridded
|
|
63
|
+
standardized indices (SPI, SPEI, soil-moisture percentiles) **without fixing a single threshold**. It builds the
|
|
64
|
+
max-tree of the deficit field over time, latitude and longitude and selects events inside that hierarchy with
|
|
65
|
+
volume-weighted topological persistence, a noise-adaptive persistence threshold and lineage inheritance. One tree
|
|
66
|
+
gives two nested levels: drought **episodes** and the **pulses** they contain.
|
|
67
|
+
|
|
68
|
+
The package also provides everything needed to **test** a drought-event detector: a synthetic benchmark with known
|
|
69
|
+
events (Gaussian scenarios and irregular shapes from real droughts), three reference detectors, tracking metrics
|
|
70
|
+
(HOTA, object F1, partition agreement), event confidence and a surrogate significance test.
|
|
71
|
+
|
|
72
|
+

|
|
73
|
+
|
|
74
|
+
## Contents
|
|
75
|
+
|
|
76
|
+
- [Why DRIFT](#why-drift)
|
|
77
|
+
- [Installation](#installation)
|
|
78
|
+
- [Quickstart](#quickstart)
|
|
79
|
+
- [How it works](#how-it-works)
|
|
80
|
+
- [Evaluation metrics](#evaluation-metrics)
|
|
81
|
+
- [Benchmark](#benchmark)
|
|
82
|
+
- [Tests and validation](#tests-and-validation)
|
|
83
|
+
- [Package structure](#package-structure)
|
|
84
|
+
- [Documentation](#documentation) · [Citation](#citation) · [License](#license)
|
|
85
|
+
|
|
86
|
+
## Why DRIFT
|
|
87
|
+
|
|
88
|
+
A drought catalogue built by labelling connected cells below one threshold (for example SPI ≤ −1) changes with that
|
|
89
|
+
threshold: a strict one breaks droughts into pieces, a lenient one chains separate droughts into multi-year objects.
|
|
90
|
+
DRIFT keeps **all thresholds at once** in a component tree and lets each event take its own effective threshold:
|
|
91
|
+
|
|
92
|
+

|
|
93
|
+
|
|
94
|
+
*(a) Each threshold gives a different set of events. (b) In the tree, each maximum is a branch with a persistence
|
|
95
|
+
P = peak − saddle; shallow branches created by noise are absorbed, droughts separated by deep saddles are kept.*
|
|
96
|
+
|
|
97
|
+
## Installation
|
|
98
|
+
|
|
99
|
+
```bash
|
|
100
|
+
pip install drift-drought
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
Python ≥ 3.10. Dependencies: NumPy, SciPy, pandas, [Higra](https://higra.readthedocs.io) (component trees), Numba,
|
|
104
|
+
scikit-image, scikit-learn and xarray. Extras: `[plot]` (matplotlib), `[test]` (pytest), `[docs]` (Sphinx).
|
|
105
|
+
|
|
106
|
+
## Quickstart
|
|
107
|
+
|
|
108
|
+
```python
|
|
109
|
+
import numpy as np
|
|
110
|
+
import driftdrought as dd
|
|
111
|
+
|
|
112
|
+
# a benchmark cube (60 months x 60 x 80 cells): one drought splits, two converge
|
|
113
|
+
index, truth, meta = dd.synthetic.generate("S3_splitmerge", noise=0.6, seed=3)
|
|
114
|
+
area = np.ones(index.shape[1:]) # unit cells; dd.cell_area_km2() on a lat-lon grid
|
|
115
|
+
|
|
116
|
+
labels, info = dd.detect(dd.smooth(index, 2.5), area, v_min=50, floor=0.5,
|
|
117
|
+
footprint="watershed", ext_floor=0.5)
|
|
118
|
+
|
|
119
|
+
print(dd.metrics.hota(truth, labels, area)) # HOTA 0.574, DetA 0.628, AssA 0.525
|
|
120
|
+
print(dd.metrics.object_match(truth, labels, area, iou_thr=0.25)["f1_iou25"]) # 0.86
|
|
121
|
+
print(dd.event_table(labels, index, area)) # start, end, duration, volume, peak month...
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
On real data:
|
|
125
|
+
|
|
126
|
+
```python
|
|
127
|
+
spi3 = xr.open_dataset("spi3.nc").spi3 # (time, lat, lon), NaN over sea
|
|
128
|
+
area = dd.cell_area_km2(spi3.lat.values, 0.25)[:, None] * np.ones(spi3.lon.size)
|
|
129
|
+
area[np.isnan(spi3.values[0])] = 0
|
|
130
|
+
x = dd.smooth(spi3.values, 2.5)
|
|
131
|
+
floor, scan = dd.select_floor(x, area, v_min=2e6) # event-count stability rule
|
|
132
|
+
episodes, info = dd.detect(x, area, v_min=2e6, floor=floor) # km2 x months
|
|
133
|
+
pulses, _ = dd.detect(x, area, v_min=2e6, floor=floor, selection="leaf")
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
The complete script is [`examples/quickstart.py`](https://github.com/karelsanchez/drift-drought/blob/main/examples/quickstart.py).
|
|
137
|
+
|
|
138
|
+
## How it works
|
|
139
|
+
|
|
140
|
+
| Step | What DRIFT does | Parameter |
|
|
141
|
+
|---|---|---|
|
|
142
|
+
| 1. Deficit field | `d = −index`, optionally smoothed with a 3-D Gaussian | `smooth(index, sigma)` |
|
|
143
|
+
| 2. Component tree | max-tree of `d` with 26-connectivity in time and space | — |
|
|
144
|
+
| 3. Significant nodes | volume ≥ `v_min` and deficit ≥ `floor` | `v_min`, `floor` |
|
|
145
|
+
| 4. Persistence | branch persistence P = peak − saddle; branches with P < π are absorbed | `persistence="auto:k"`: π = k · 1.4826 · MAD of the high-pass residual |
|
|
146
|
+
| 5. Volume weighting | P_V = P · (V / v_min)^γ, so large droughts survive shallow saddles | `pers_gamma` (γ = 1) |
|
|
147
|
+
| 6. Lineage inheritance | an event born inside an older event (share ≥ q of its first footprint) takes its identity | `inherit` (q = 0.75) |
|
|
148
|
+
| 7. Footprint | birth component, or watershed growth into cells with deficit ≥ `ext_floor` | `footprint`, `ext_floor` |
|
|
149
|
+
| 8. Floor | the floor where the number of events is most stable | `select_floor` |
|
|
150
|
+
|
|
151
|
+
**Episodes and pulses.** `selection="persistence_vl"` (default) returns episodes; `selection="leaf"` returns the
|
|
152
|
+
pulses nested in them:
|
|
153
|
+
|
|
154
|
+

|
|
155
|
+
|
|
156
|
+
**Event attributes.** `confidence.parameter_confidence` gives each event a confidence (mean best IoU with runs of
|
|
157
|
+
perturbed parameters; with another precipitation product it becomes a *product confidence*), and
|
|
158
|
+
`significance.surrogate_test` tests each event against phase-randomized surrogates of the field (family-wise and
|
|
159
|
+
Benjamini–Hochberg p-values).
|
|
160
|
+
|
|
161
|
+

|
|
162
|
+
|
|
163
|
+
## Evaluation metrics
|
|
164
|
+
|
|
165
|
+
| Metric | Function | Meaning |
|
|
166
|
+
|---|---|---|
|
|
167
|
+
| **IoU** | — | area-weighted space–time intersection over union of a true and a detected event |
|
|
168
|
+
| **Precision, recall, F1** | `metrics.object_match` | one-to-one matching of events (Hungarian) with IoU ≥ 0.5; `f1_iou25` uses IoU ≥ 0.25 |
|
|
169
|
+
| **Mean IoU, volume error** | `metrics.object_match` | quality of the matched footprints |
|
|
170
|
+
| **Events detected vs true** | `metrics.object_match` (`n_pred`, `n_gt`) | exposes fragmentation (too many) and chaining (too few) |
|
|
171
|
+
| **HOTA** | `metrics.hota` | Higher Order Tracking Accuracy (Luiten et al., 2021): √(DetA · AssA), averaged over IoU thresholds 0.05–0.95 |
|
|
172
|
+
| **DetA** | `metrics.hota` | detection accuracy: drought cells found in the right months |
|
|
173
|
+
| **AssA** | `metrics.hota` | association accuracy: each drought keeps one identity through time |
|
|
174
|
+
| **ARI, VI** | `metrics.partition_agreement` | adjusted Rand index and variation of information between two partitions |
|
|
175
|
+
|
|
176
|
+
Equations and interpretation: [metrics page of the documentation](https://drift-drought.readthedocs.io/en/latest/metrics.html).
|
|
177
|
+
|
|
178
|
+
## Benchmark
|
|
179
|
+
|
|
180
|
+
`synthetic.generate` reproduces the known-truth cubes of the DRIFT article; `synthetic.generate_irregular` places
|
|
181
|
+
**real drought shapes** — from your own catalogue (`build_library`) or from the bundled library of 99 droughts of the
|
|
182
|
+
Amazon and Orinoco basins (`example_library`) — so DRIFT can be tuned to the scale of the target region.
|
|
183
|
+
|
|
184
|
+

|
|
185
|
+
|
|
186
|
+
| Scenario | What it tests |
|
|
187
|
+
|---|---|
|
|
188
|
+
| `S1_isolated` | recovery of separated events |
|
|
189
|
+
| `S2_advection` | continuity of migrating events |
|
|
190
|
+
| `S3_splitmerge` | identity through a split and two converging droughts |
|
|
191
|
+
| `S4_fragmented` | weak events on strongly correlated noise |
|
|
192
|
+
| irregular | non-convex, multi-core events with the geometry of observed droughts |
|
|
193
|
+
|
|
194
|
+
Mini benchmark (`examples/make_figures.py`: four scenarios × two noise levels × ten seeds, configurations selected in
|
|
195
|
+
the article):
|
|
196
|
+
|
|
197
|
+

|
|
198
|
+
|
|
199
|
+
| Method | HOTA (noise 0.3) | HOTA (noise 0.6) | AssA (0.6) | F1, IoU ≥ 0.25 (0.6) | Events detected (0.6; true 4.6) |
|
|
200
|
+
|---|---|---|---|---|---|
|
|
201
|
+
| **DRIFT** | **0.575** | **0.461** | **0.496** | **0.78** | 6.8 |
|
|
202
|
+
| CCL-2D + overlap | 0.520 | 0.424 | 0.460 | 0.67 | 10.8 |
|
|
203
|
+
| CCL-3D | 0.506 | 0.409 | 0.430 | 0.69 | 4.0 |
|
|
204
|
+
| 3D-DBSCAN | 0.496 | 0.411 | 0.447 | 0.68 | 5.3 |
|
|
205
|
+
|
|
206
|
+
In the article (20 seeds, held-out selection of every method) DRIFT reached HOTA 0.579 and 0.459 against at most 0.530
|
|
207
|
+
and 0.428, was best in seven of eight scenario–noise combinations and, re-tuned on irregular events from observed
|
|
208
|
+
droughts, remained best on average. Weak events in strongly correlated noise (S4) are hard for every method, and at
|
|
209
|
+
the smoothing that maximizes HOTA the split in S3 is not reported as a split (DRIFT keeps one identity instead).
|
|
210
|
+
|
|
211
|
+
## Tests and validation
|
|
212
|
+
|
|
213
|
+
The test suite runs on GitHub Actions for Python 3.10, 3.11 and 3.12 on every push.
|
|
214
|
+
|
|
215
|
+
| Test | What it checks |
|
|
216
|
+
|---|---|
|
|
217
|
+
| `test_generator_is_deterministic` | same scenario, noise and seed → same cube and truth |
|
|
218
|
+
| `test_detect_recovers_isolated_events` | HOTA > 0.4 and F1 (IoU ≥ 0.25) > 0.6 on isolated events |
|
|
219
|
+
| `test_all_selection_rules_run` | the five selection rules run and return events |
|
|
220
|
+
| `test_nan_cells_are_never_events` | cells outside the domain are never labelled |
|
|
221
|
+
| `test_merge_branches_joins_a_split` | lineage inheritance gives one identity to a lobe born inside an event |
|
|
222
|
+
| `test_baselines_and_confidence` | reference detectors run; a catalogue has confidence 1 against itself |
|
|
223
|
+
| `test_select_floor_returns_candidate` | the floor rule returns a candidate floor and the full scan |
|
|
224
|
+
| `test_surrogate_test_small` | the significance test returns valid family-wise and FDR p-values |
|
|
225
|
+
| `test_example_library` | the bundled real-shape library loads and builds cubes |
|
|
226
|
+
|
|
227
|
+
```bash
|
|
228
|
+
pip install -e ".[test]"
|
|
229
|
+
pytest -v
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
**Equivalence with the article.** Before release, `detect` was checked against the research implementation used in
|
|
233
|
+
the article on the four benchmark scenarios: the label cubes were identical voxel by voxel.
|
|
234
|
+
|
|
235
|
+
## Package structure
|
|
236
|
+
|
|
237
|
+
| Module | Contents |
|
|
238
|
+
|---|---|
|
|
239
|
+
| `driftdrought.core` | `detect`, `smooth`, `select_floor`, `event_table`, `merge_branches`, `cell_area_km2` |
|
|
240
|
+
| `driftdrought.indices` | SPI, SPEI and soil-moisture index fitted per calendar month |
|
|
241
|
+
| `driftdrought.synthetic` | benchmark cubes (S1–S4), `build_library`, `example_library`, `generate_irregular` |
|
|
242
|
+
| `driftdrought.baselines` | CCL-2D with overlap tracking, CCL-3D, 3D-DBSCAN |
|
|
243
|
+
| `driftdrought.metrics` | HOTA (DetA, AssA), object matching, partition agreement |
|
|
244
|
+
| `driftdrought.confidence` | event confidence against perturbed parameters or another input product |
|
|
245
|
+
| `driftdrought.significance` | phase-randomized surrogate test, family-wise and FDR p-values |
|
|
246
|
+
|
|
247
|
+
## Documentation
|
|
248
|
+
|
|
249
|
+
**https://drift-drought.readthedocs.io** — installation, quickstart, method with equations, metrics, benchmark, tests,
|
|
250
|
+
gallery and the full API reference generated from the docstrings.
|
|
251
|
+
|
|
252
|
+
## Citation
|
|
253
|
+
|
|
254
|
+
If you use DRIFT, please cite the software and the article (see `CITATION.cff`, or "Cite this repository" on GitHub):
|
|
255
|
+
|
|
256
|
+
> Sanchez H., K. A. (2026). *DRIFT: Drought Regions Identified From the space–time component Tree* (software).
|
|
257
|
+
> Zenodo. https://doi.org/10.5281/zenodo.24409548 (all versions; version 0.1.1: https://doi.org/10.5281/zenodo.24409549)
|
|
258
|
+
|
|
259
|
+
> Sanchez H., K. A. (2026). DRIFT for detecting and tracking spatiotemporal drought events with component trees.
|
|
260
|
+
> *Water Resources Research* (submitted).
|
|
261
|
+
|
|
262
|
+
## License
|
|
263
|
+
|
|
264
|
+
MIT © 2026 Karel A. Sanchez H. (see [LICENSE](https://github.com/karelsanchez/drift-drought/blob/main/LICENSE)).
|
|
@@ -0,0 +1,211 @@
|
|
|
1
|
+
# DRIFT — drought events from the space–time component tree
|
|
2
|
+
|
|
3
|
+
[](https://github.com/karelsanchez/drift-drought/actions/workflows/tests.yml)
|
|
4
|
+
[](https://drift-drought.readthedocs.io)
|
|
5
|
+
[](https://github.com/karelsanchez/drift-drought/blob/main/LICENSE)
|
|
6
|
+

|
|
7
|
+
[](https://doi.org/10.5281/zenodo.24409548)
|
|
8
|
+
|
|
9
|
+
**DRIFT** (*Drought Regions Identified From the space–time component Tree*) detects drought events in gridded
|
|
10
|
+
standardized indices (SPI, SPEI, soil-moisture percentiles) **without fixing a single threshold**. It builds the
|
|
11
|
+
max-tree of the deficit field over time, latitude and longitude and selects events inside that hierarchy with
|
|
12
|
+
volume-weighted topological persistence, a noise-adaptive persistence threshold and lineage inheritance. One tree
|
|
13
|
+
gives two nested levels: drought **episodes** and the **pulses** they contain.
|
|
14
|
+
|
|
15
|
+
The package also provides everything needed to **test** a drought-event detector: a synthetic benchmark with known
|
|
16
|
+
events (Gaussian scenarios and irregular shapes from real droughts), three reference detectors, tracking metrics
|
|
17
|
+
(HOTA, object F1, partition agreement), event confidence and a surrogate significance test.
|
|
18
|
+
|
|
19
|
+

|
|
20
|
+
|
|
21
|
+
## Contents
|
|
22
|
+
|
|
23
|
+
- [Why DRIFT](#why-drift)
|
|
24
|
+
- [Installation](#installation)
|
|
25
|
+
- [Quickstart](#quickstart)
|
|
26
|
+
- [How it works](#how-it-works)
|
|
27
|
+
- [Evaluation metrics](#evaluation-metrics)
|
|
28
|
+
- [Benchmark](#benchmark)
|
|
29
|
+
- [Tests and validation](#tests-and-validation)
|
|
30
|
+
- [Package structure](#package-structure)
|
|
31
|
+
- [Documentation](#documentation) · [Citation](#citation) · [License](#license)
|
|
32
|
+
|
|
33
|
+
## Why DRIFT
|
|
34
|
+
|
|
35
|
+
A drought catalogue built by labelling connected cells below one threshold (for example SPI ≤ −1) changes with that
|
|
36
|
+
threshold: a strict one breaks droughts into pieces, a lenient one chains separate droughts into multi-year objects.
|
|
37
|
+
DRIFT keeps **all thresholds at once** in a component tree and lets each event take its own effective threshold:
|
|
38
|
+
|
|
39
|
+

|
|
40
|
+
|
|
41
|
+
*(a) Each threshold gives a different set of events. (b) In the tree, each maximum is a branch with a persistence
|
|
42
|
+
P = peak − saddle; shallow branches created by noise are absorbed, droughts separated by deep saddles are kept.*
|
|
43
|
+
|
|
44
|
+
## Installation
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
pip install drift-drought
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
Python ≥ 3.10. Dependencies: NumPy, SciPy, pandas, [Higra](https://higra.readthedocs.io) (component trees), Numba,
|
|
51
|
+
scikit-image, scikit-learn and xarray. Extras: `[plot]` (matplotlib), `[test]` (pytest), `[docs]` (Sphinx).
|
|
52
|
+
|
|
53
|
+
## Quickstart
|
|
54
|
+
|
|
55
|
+
```python
|
|
56
|
+
import numpy as np
|
|
57
|
+
import driftdrought as dd
|
|
58
|
+
|
|
59
|
+
# a benchmark cube (60 months x 60 x 80 cells): one drought splits, two converge
|
|
60
|
+
index, truth, meta = dd.synthetic.generate("S3_splitmerge", noise=0.6, seed=3)
|
|
61
|
+
area = np.ones(index.shape[1:]) # unit cells; dd.cell_area_km2() on a lat-lon grid
|
|
62
|
+
|
|
63
|
+
labels, info = dd.detect(dd.smooth(index, 2.5), area, v_min=50, floor=0.5,
|
|
64
|
+
footprint="watershed", ext_floor=0.5)
|
|
65
|
+
|
|
66
|
+
print(dd.metrics.hota(truth, labels, area)) # HOTA 0.574, DetA 0.628, AssA 0.525
|
|
67
|
+
print(dd.metrics.object_match(truth, labels, area, iou_thr=0.25)["f1_iou25"]) # 0.86
|
|
68
|
+
print(dd.event_table(labels, index, area)) # start, end, duration, volume, peak month...
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
On real data:
|
|
72
|
+
|
|
73
|
+
```python
|
|
74
|
+
spi3 = xr.open_dataset("spi3.nc").spi3 # (time, lat, lon), NaN over sea
|
|
75
|
+
area = dd.cell_area_km2(spi3.lat.values, 0.25)[:, None] * np.ones(spi3.lon.size)
|
|
76
|
+
area[np.isnan(spi3.values[0])] = 0
|
|
77
|
+
x = dd.smooth(spi3.values, 2.5)
|
|
78
|
+
floor, scan = dd.select_floor(x, area, v_min=2e6) # event-count stability rule
|
|
79
|
+
episodes, info = dd.detect(x, area, v_min=2e6, floor=floor) # km2 x months
|
|
80
|
+
pulses, _ = dd.detect(x, area, v_min=2e6, floor=floor, selection="leaf")
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
The complete script is [`examples/quickstart.py`](https://github.com/karelsanchez/drift-drought/blob/main/examples/quickstart.py).
|
|
84
|
+
|
|
85
|
+
## How it works
|
|
86
|
+
|
|
87
|
+
| Step | What DRIFT does | Parameter |
|
|
88
|
+
|---|---|---|
|
|
89
|
+
| 1. Deficit field | `d = −index`, optionally smoothed with a 3-D Gaussian | `smooth(index, sigma)` |
|
|
90
|
+
| 2. Component tree | max-tree of `d` with 26-connectivity in time and space | — |
|
|
91
|
+
| 3. Significant nodes | volume ≥ `v_min` and deficit ≥ `floor` | `v_min`, `floor` |
|
|
92
|
+
| 4. Persistence | branch persistence P = peak − saddle; branches with P < π are absorbed | `persistence="auto:k"`: π = k · 1.4826 · MAD of the high-pass residual |
|
|
93
|
+
| 5. Volume weighting | P_V = P · (V / v_min)^γ, so large droughts survive shallow saddles | `pers_gamma` (γ = 1) |
|
|
94
|
+
| 6. Lineage inheritance | an event born inside an older event (share ≥ q of its first footprint) takes its identity | `inherit` (q = 0.75) |
|
|
95
|
+
| 7. Footprint | birth component, or watershed growth into cells with deficit ≥ `ext_floor` | `footprint`, `ext_floor` |
|
|
96
|
+
| 8. Floor | the floor where the number of events is most stable | `select_floor` |
|
|
97
|
+
|
|
98
|
+
**Episodes and pulses.** `selection="persistence_vl"` (default) returns episodes; `selection="leaf"` returns the
|
|
99
|
+
pulses nested in them:
|
|
100
|
+
|
|
101
|
+

|
|
102
|
+
|
|
103
|
+
**Event attributes.** `confidence.parameter_confidence` gives each event a confidence (mean best IoU with runs of
|
|
104
|
+
perturbed parameters; with another precipitation product it becomes a *product confidence*), and
|
|
105
|
+
`significance.surrogate_test` tests each event against phase-randomized surrogates of the field (family-wise and
|
|
106
|
+
Benjamini–Hochberg p-values).
|
|
107
|
+
|
|
108
|
+

|
|
109
|
+
|
|
110
|
+
## Evaluation metrics
|
|
111
|
+
|
|
112
|
+
| Metric | Function | Meaning |
|
|
113
|
+
|---|---|---|
|
|
114
|
+
| **IoU** | — | area-weighted space–time intersection over union of a true and a detected event |
|
|
115
|
+
| **Precision, recall, F1** | `metrics.object_match` | one-to-one matching of events (Hungarian) with IoU ≥ 0.5; `f1_iou25` uses IoU ≥ 0.25 |
|
|
116
|
+
| **Mean IoU, volume error** | `metrics.object_match` | quality of the matched footprints |
|
|
117
|
+
| **Events detected vs true** | `metrics.object_match` (`n_pred`, `n_gt`) | exposes fragmentation (too many) and chaining (too few) |
|
|
118
|
+
| **HOTA** | `metrics.hota` | Higher Order Tracking Accuracy (Luiten et al., 2021): √(DetA · AssA), averaged over IoU thresholds 0.05–0.95 |
|
|
119
|
+
| **DetA** | `metrics.hota` | detection accuracy: drought cells found in the right months |
|
|
120
|
+
| **AssA** | `metrics.hota` | association accuracy: each drought keeps one identity through time |
|
|
121
|
+
| **ARI, VI** | `metrics.partition_agreement` | adjusted Rand index and variation of information between two partitions |
|
|
122
|
+
|
|
123
|
+
Equations and interpretation: [metrics page of the documentation](https://drift-drought.readthedocs.io/en/latest/metrics.html).
|
|
124
|
+
|
|
125
|
+
## Benchmark
|
|
126
|
+
|
|
127
|
+
`synthetic.generate` reproduces the known-truth cubes of the DRIFT article; `synthetic.generate_irregular` places
|
|
128
|
+
**real drought shapes** — from your own catalogue (`build_library`) or from the bundled library of 99 droughts of the
|
|
129
|
+
Amazon and Orinoco basins (`example_library`) — so DRIFT can be tuned to the scale of the target region.
|
|
130
|
+
|
|
131
|
+

|
|
132
|
+
|
|
133
|
+
| Scenario | What it tests |
|
|
134
|
+
|---|---|
|
|
135
|
+
| `S1_isolated` | recovery of separated events |
|
|
136
|
+
| `S2_advection` | continuity of migrating events |
|
|
137
|
+
| `S3_splitmerge` | identity through a split and two converging droughts |
|
|
138
|
+
| `S4_fragmented` | weak events on strongly correlated noise |
|
|
139
|
+
| irregular | non-convex, multi-core events with the geometry of observed droughts |
|
|
140
|
+
|
|
141
|
+
Mini benchmark (`examples/make_figures.py`: four scenarios × two noise levels × ten seeds, configurations selected in
|
|
142
|
+
the article):
|
|
143
|
+
|
|
144
|
+

|
|
145
|
+
|
|
146
|
+
| Method | HOTA (noise 0.3) | HOTA (noise 0.6) | AssA (0.6) | F1, IoU ≥ 0.25 (0.6) | Events detected (0.6; true 4.6) |
|
|
147
|
+
|---|---|---|---|---|---|
|
|
148
|
+
| **DRIFT** | **0.575** | **0.461** | **0.496** | **0.78** | 6.8 |
|
|
149
|
+
| CCL-2D + overlap | 0.520 | 0.424 | 0.460 | 0.67 | 10.8 |
|
|
150
|
+
| CCL-3D | 0.506 | 0.409 | 0.430 | 0.69 | 4.0 |
|
|
151
|
+
| 3D-DBSCAN | 0.496 | 0.411 | 0.447 | 0.68 | 5.3 |
|
|
152
|
+
|
|
153
|
+
In the article (20 seeds, held-out selection of every method) DRIFT reached HOTA 0.579 and 0.459 against at most 0.530
|
|
154
|
+
and 0.428, was best in seven of eight scenario–noise combinations and, re-tuned on irregular events from observed
|
|
155
|
+
droughts, remained best on average. Weak events in strongly correlated noise (S4) are hard for every method, and at
|
|
156
|
+
the smoothing that maximizes HOTA the split in S3 is not reported as a split (DRIFT keeps one identity instead).
|
|
157
|
+
|
|
158
|
+
## Tests and validation
|
|
159
|
+
|
|
160
|
+
The test suite runs on GitHub Actions for Python 3.10, 3.11 and 3.12 on every push.
|
|
161
|
+
|
|
162
|
+
| Test | What it checks |
|
|
163
|
+
|---|---|
|
|
164
|
+
| `test_generator_is_deterministic` | same scenario, noise and seed → same cube and truth |
|
|
165
|
+
| `test_detect_recovers_isolated_events` | HOTA > 0.4 and F1 (IoU ≥ 0.25) > 0.6 on isolated events |
|
|
166
|
+
| `test_all_selection_rules_run` | the five selection rules run and return events |
|
|
167
|
+
| `test_nan_cells_are_never_events` | cells outside the domain are never labelled |
|
|
168
|
+
| `test_merge_branches_joins_a_split` | lineage inheritance gives one identity to a lobe born inside an event |
|
|
169
|
+
| `test_baselines_and_confidence` | reference detectors run; a catalogue has confidence 1 against itself |
|
|
170
|
+
| `test_select_floor_returns_candidate` | the floor rule returns a candidate floor and the full scan |
|
|
171
|
+
| `test_surrogate_test_small` | the significance test returns valid family-wise and FDR p-values |
|
|
172
|
+
| `test_example_library` | the bundled real-shape library loads and builds cubes |
|
|
173
|
+
|
|
174
|
+
```bash
|
|
175
|
+
pip install -e ".[test]"
|
|
176
|
+
pytest -v
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
**Equivalence with the article.** Before release, `detect` was checked against the research implementation used in
|
|
180
|
+
the article on the four benchmark scenarios: the label cubes were identical voxel by voxel.
|
|
181
|
+
|
|
182
|
+
## Package structure
|
|
183
|
+
|
|
184
|
+
| Module | Contents |
|
|
185
|
+
|---|---|
|
|
186
|
+
| `driftdrought.core` | `detect`, `smooth`, `select_floor`, `event_table`, `merge_branches`, `cell_area_km2` |
|
|
187
|
+
| `driftdrought.indices` | SPI, SPEI and soil-moisture index fitted per calendar month |
|
|
188
|
+
| `driftdrought.synthetic` | benchmark cubes (S1–S4), `build_library`, `example_library`, `generate_irregular` |
|
|
189
|
+
| `driftdrought.baselines` | CCL-2D with overlap tracking, CCL-3D, 3D-DBSCAN |
|
|
190
|
+
| `driftdrought.metrics` | HOTA (DetA, AssA), object matching, partition agreement |
|
|
191
|
+
| `driftdrought.confidence` | event confidence against perturbed parameters or another input product |
|
|
192
|
+
| `driftdrought.significance` | phase-randomized surrogate test, family-wise and FDR p-values |
|
|
193
|
+
|
|
194
|
+
## Documentation
|
|
195
|
+
|
|
196
|
+
**https://drift-drought.readthedocs.io** — installation, quickstart, method with equations, metrics, benchmark, tests,
|
|
197
|
+
gallery and the full API reference generated from the docstrings.
|
|
198
|
+
|
|
199
|
+
## Citation
|
|
200
|
+
|
|
201
|
+
If you use DRIFT, please cite the software and the article (see `CITATION.cff`, or "Cite this repository" on GitHub):
|
|
202
|
+
|
|
203
|
+
> Sanchez H., K. A. (2026). *DRIFT: Drought Regions Identified From the space–time component Tree* (software).
|
|
204
|
+
> Zenodo. https://doi.org/10.5281/zenodo.24409548 (all versions; version 0.1.1: https://doi.org/10.5281/zenodo.24409549)
|
|
205
|
+
|
|
206
|
+
> Sanchez H., K. A. (2026). DRIFT for detecting and tracking spatiotemporal drought events with component trees.
|
|
207
|
+
> *Water Resources Research* (submitted).
|
|
208
|
+
|
|
209
|
+
## License
|
|
210
|
+
|
|
211
|
+
MIT © 2026 Karel A. Sanchez H. (see [LICENSE](https://github.com/karelsanchez/drift-drought/blob/main/LICENSE)).
|
|
Binary file
|
|
Binary file
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
method,noise,HOTA,DetA,AssA,F1_iou25,events,true_events
|
|
2
|
+
3D-DBSCAN,0.3,0.496,0.474,0.533,0.797,3.175,4.575
|
|
3
|
+
3D-DBSCAN,0.6,0.411,0.39,0.447,0.682,5.325,4.575
|
|
4
|
+
CCL-2D + overlap,0.3,0.52,0.505,0.547,0.801,3.675,4.575
|
|
5
|
+
CCL-2D + overlap,0.6,0.424,0.405,0.46,0.666,10.775,4.575
|
|
6
|
+
CCL-3D,0.3,0.506,0.493,0.53,0.797,3.075,4.575
|
|
7
|
+
CCL-3D,0.6,0.409,0.398,0.43,0.688,3.95,4.575
|
|
8
|
+
DRIFT,0.3,0.575,0.56,0.599,0.921,4.15,4.575
|
|
9
|
+
DRIFT,0.6,0.461,0.44,0.496,0.784,6.775,4.575
|
|
Binary file
|