drift-drought 0.1.2__py3-none-any.whl

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.
@@ -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
+ [![tests](https://github.com/karelsanchez/drift-drought/actions/workflows/tests.yml/badge.svg)](https://github.com/karelsanchez/drift-drought/actions/workflows/tests.yml)
57
+ [![docs](https://readthedocs.org/projects/drift-drought/badge/?version=latest)](https://drift-drought.readthedocs.io)
58
+ [![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/karelsanchez/drift-drought/blob/main/LICENSE)
59
+ ![python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue)
60
+ [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.24409548.svg)](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
+ ![Quickstart](https://raw.githubusercontent.com/karelsanchez/drift-drought/main/docs/_static/quickstart.png)
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
+ ![One threshold versus the tree](https://raw.githubusercontent.com/karelsanchez/drift-drought/main/docs/_static/concept_tree.png)
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
+ ![Episodes and pulses](https://raw.githubusercontent.com/karelsanchez/drift-drought/main/docs/_static/pulses_episodes.png)
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
+ ![Floor selection](https://raw.githubusercontent.com/karelsanchez/drift-drought/main/docs/_static/floor_scan.png)
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
+ ![Benchmark scenarios](https://raw.githubusercontent.com/karelsanchez/drift-drought/main/docs/_static/scenarios.png)
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
+ ![Mini benchmark](https://raw.githubusercontent.com/karelsanchez/drift-drought/main/docs/_static/mini_benchmark.png)
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,13 @@
1
+ driftdrought/__init__.py,sha256=1kYyrR9Zjdl8KuqJCViUNAlOUgXt2pUcji_rgLkH2_E,632
2
+ driftdrought/baselines.py,sha256=sEGJ4xGip04ahUKZwpBQAT5aOUraIfzpTMH9D-BsL08,4527
3
+ driftdrought/confidence.py,sha256=gMqLZUoBgJZpQKOXwTKfLuIHTKxnen1tRX3lQ4O5v54,3664
4
+ driftdrought/core.py,sha256=zUfSCRM8S5optTMtEi1BONJ-ypTC8BTZBWqLBr8OPJo,17604
5
+ driftdrought/indices.py,sha256=Tc9rPptYMJ5HuQYGgWeyx6lVeurKflzGQl9zehT-n4U,4916
6
+ driftdrought/metrics.py,sha256=ERdFtnC-WVw6XQgyRN3Q1wiD6dSOd68ssiJFl3fvoqY,6051
7
+ driftdrought/significance.py,sha256=Vqo-PWvKYBF_2iE0-l4CjY_HA_EeJUMfOoTdoHOH7Nk,4249
8
+ driftdrought/synthetic.py,sha256=Ppeh68rbrgGY4-sa7AoMaMVEez5thM3g6vSBrYORCaE,8002
9
+ driftdrought/data/amazon_orinoco_pulses.npz,sha256=s1KFutnSzaYgcgEK_eauaRpk-2vixP5eQ1cBSyBGyP4,411782
10
+ drift_drought-0.1.2.dist-info/METADATA,sha256=7hb4y6q8oBFfr75N7JhpiEW61DOHpcSinMpuqLOeKzc,14588
11
+ drift_drought-0.1.2.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
12
+ drift_drought-0.1.2.dist-info/licenses/LICENSE,sha256=n6VmFpiU9PYxqMBJBoUkei7gu07sePEjul5N6Zwj2rU,1076
13
+ drift_drought-0.1.2.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: hatchling 1.33.0
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -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,10 @@
1
+ """DRIFT — Drought Regions Identified From the space–time component Tree.
2
+
3
+ Detect, characterize and evaluate space–time drought events selected from the component tree of a deficit field.
4
+ """
5
+ from . import baselines, confidence, indices, metrics, significance, synthetic
6
+ from .core import cell_area_km2, detect, event_table, merge_branches, noise_persistence, select_floor, smooth
7
+
8
+ __version__ = "0.1.2"
9
+ __all__ = ["detect", "smooth", "select_floor", "event_table", "merge_branches", "noise_persistence", "cell_area_km2",
10
+ "baselines", "confidence", "indices", "metrics", "significance", "synthetic", "__version__"]
@@ -0,0 +1,123 @@
1
+ """Reference detectors used in the DRIFT benchmark.
2
+
3
+ * :func:`ccl2d_overlap` — monthly 8-connected patches linked across months by overlap (Andreadis et al., 2005).
4
+ * :func:`ccl3d` — 26-connected space–time components with a minimum volume (Lloyd-Hughes, 2012; Diaz et al., 2020).
5
+ * :func:`dbscan3d` — density-based clustering of drought voxels (Ester et al., 1996; Cammalleri & Toreti, 2023).
6
+
7
+ All take a standardized index ``(time, y, x)`` (drought negative, NaN outside the domain) and a threshold, and return
8
+ an integer label cube (0 = no event).
9
+ """
10
+ import numpy as np
11
+ import pandas as pd
12
+ from scipy import ndimage
13
+
14
+ from .core import _relabel
15
+
16
+ __all__ = ["ccl2d_overlap", "ccl3d", "dbscan3d"]
17
+
18
+
19
+ def ccl2d_overlap(index, thr, cell_area, min_frac=0.016, overlap_frac=0.016):
20
+ """Two-dimensional connected components linked through time by overlap.
21
+
22
+ Parameters
23
+ ----------
24
+ index : numpy.ndarray
25
+ Index ``(time, y, x)``.
26
+ thr : float
27
+ Drought threshold (cells with ``index <= thr`` are dry).
28
+ cell_area : numpy.ndarray
29
+ Cell areas ``(y, x)``.
30
+ min_frac : float
31
+ Minimum patch area as a share of the domain area.
32
+ overlap_frac : float
33
+ Minimum overlap between patches of consecutive months, as a share of the domain area.
34
+ """
35
+ dry = np.nan_to_num(index, nan=0.0) <= thr
36
+ land = np.isfinite(index[0])
37
+ area = np.broadcast_to(np.asarray(cell_area, float), index.shape[1:])
38
+ total = area[land].sum()
39
+ labels = np.zeros(index.shape, dtype=np.int64)
40
+ parent = {}
41
+
42
+ def find(a):
43
+ while parent[a] != a:
44
+ parent[a] = parent[parent[a]]
45
+ a = parent[a]
46
+ return a
47
+
48
+ nxt = 1
49
+ s8 = np.ones((3, 3), bool)
50
+ for t in range(index.shape[0]):
51
+ lab, n = ndimage.label(dry[t], structure=s8)
52
+ if n == 0:
53
+ continue
54
+ a = ndimage.sum(area, lab, index=np.arange(1, n + 1))
55
+ for k in np.where(a >= min_frac * total)[0] + 1:
56
+ labels[t][lab == k] = nxt
57
+ parent[nxt] = nxt
58
+ nxt += 1
59
+ if t == 0:
60
+ continue
61
+ prev, cur = labels[t - 1], labels[t]
62
+ both = (prev > 0) & (cur > 0)
63
+ if not both.any():
64
+ continue
65
+ ov = pd.DataFrame({"p": prev[both], "c": cur[both], "a": area[both]}).groupby(["p", "c"]).a.sum()
66
+ for (p, c), a in ov.items():
67
+ if a >= overlap_frac * total:
68
+ rp, rc = find(p), find(c)
69
+ if rp != rc:
70
+ parent[rc] = rp
71
+ if nxt > 1:
72
+ lut = np.zeros(nxt, dtype=np.int64)
73
+ for k in range(1, nxt):
74
+ lut[k] = find(k)
75
+ labels = lut[labels]
76
+ return _relabel(labels)
77
+
78
+
79
+ def ccl3d(index, thr, cell_area, min_volume_frac=0.0):
80
+ """26-connected space–time components with a minimum volume.
81
+
82
+ Parameters
83
+ ----------
84
+ min_volume_frac : float
85
+ Minimum event volume as a share of (domain area × one time step).
86
+ """
87
+ dry = np.nan_to_num(index, nan=0.0) <= thr
88
+ lab, n = ndimage.label(dry, structure=np.ones((3, 3, 3), bool))
89
+ if n == 0 or min_volume_frac <= 0:
90
+ return lab.astype(np.int32)
91
+ land = np.isfinite(index[0])
92
+ area = np.broadcast_to(np.asarray(cell_area, float), index.shape[1:])
93
+ vol = ndimage.sum(np.broadcast_to(area, index.shape), lab, index=np.arange(1, n + 1))
94
+ keep = np.zeros(n + 1, bool)
95
+ keep[1:] = vol >= min_volume_frac * area[land].sum()
96
+ return _relabel(np.where(keep[lab], lab, 0))
97
+
98
+
99
+ def dbscan3d(index, thr, s_xy=3, s_t=3, fr_mp=0.25, c_min=50):
100
+ """Density-based clustering (DBSCAN) of drought voxels in a scaled space–time window.
101
+
102
+ Parameters
103
+ ----------
104
+ s_xy, s_t : int
105
+ Half-widths of the search window in cells and time steps.
106
+ fr_mp : float
107
+ Minimum share of the window that must be dry for a core point.
108
+ c_min : int
109
+ Minimum cluster size in voxels.
110
+ """
111
+ from sklearn.cluster import DBSCAN
112
+ dry = np.nan_to_num(index, nan=0.0) <= thr
113
+ pts = np.argwhere(dry)
114
+ if len(pts) == 0:
115
+ return np.zeros(index.shape, np.int32)
116
+ scaled = pts / np.array([s_t, s_xy, s_xy], float)
117
+ win = (2 * s_t + 1) * (2 * s_xy + 1) ** 2
118
+ db = DBSCAN(eps=1.0, min_samples=max(1, int(round(fr_mp * win))), metric="chebyshev", algorithm="ball_tree").fit(scaled)
119
+ lab = np.zeros(index.shape, np.int64)
120
+ lab[tuple(pts.T)] = db.labels_ + 1
121
+ sizes = np.bincount(lab.ravel())
122
+ lab[np.isin(lab, np.where(sizes < c_min)[0])] = 0
123
+ return _relabel(lab)
@@ -0,0 +1,97 @@
1
+ """Event confidence: how robust each event is to parameters or to the input product.
2
+
3
+ The confidence of event ``e`` is the mean, over ``K`` alternative catalogues ``L_k``, of the best space–time IoU between
4
+ ``e`` and any event of ``L_k`` (Equation 9 of the DRIFT paper). With catalogues from perturbed parameters it measures
5
+ parameter robustness; with a catalogue from another precipitation product it is the *product confidence*.
6
+ """
7
+ import numpy as np
8
+
9
+ from .core import detect
10
+
11
+ __all__ = ["best_iou", "event_confidence", "parameter_confidence", "consensus"]
12
+
13
+
14
+ def best_iou(ref, other):
15
+ """Best IoU of every event of ``ref`` with any event of ``other``.
16
+
17
+ Parameters
18
+ ----------
19
+ ref, other : numpy.ndarray of int
20
+ Label cubes of equal shape.
21
+
22
+ Returns
23
+ -------
24
+ numpy.ndarray
25
+ Array indexed by the event id of ``ref`` (entry 0 unused).
26
+ """
27
+ r, m = ref.ravel().astype(np.int64), other.ravel().astype(np.int64)
28
+ n_r, n_m = int(r.max()) + 1, int(m.max()) + 1
29
+ both = (r > 0) & (m > 0)
30
+ inter = np.bincount(r[both] * n_m + m[both], minlength=n_r * n_m).reshape(n_r, n_m)
31
+ union = np.bincount(r, minlength=n_r)[:, None] + np.bincount(m, minlength=n_m)[None, :] - inter
32
+ with np.errstate(invalid="ignore", divide="ignore"):
33
+ iou = np.where(union > 0, inter / union, 0.0)
34
+ iou[:, 0] = 0.0
35
+ return iou.max(axis=1)
36
+
37
+
38
+ def event_confidence(ref, members):
39
+ """Mean best IoU of each event of ``ref`` over the catalogues ``members``.
40
+
41
+ Returns
42
+ -------
43
+ dict
44
+ ``{event_id: confidence}`` with values in [0, 1].
45
+ """
46
+ conf = np.mean([best_iou(ref, m) for m in members], axis=0)
47
+ return {int(e): float(conf[e]) for e in np.unique(ref[ref > 0])}
48
+
49
+
50
+ def parameter_confidence(index, cell_area, v_min, floor, floors_delta=(-0.1, 0.1), sigma=None, smooth_deltas=(-0.5, 0.5),
51
+ **detect_kwargs):
52
+ """Confidence of the events of a reference run against runs with perturbed floor (and smoothing).
53
+
54
+ Parameters
55
+ ----------
56
+ index : numpy.ndarray
57
+ Raw (unsmoothed) index when ``sigma`` is given, otherwise the already smoothed index.
58
+ sigma : float, optional
59
+ Smoothing width of the reference run; when given, runs with ``sigma + smooth_deltas`` are added.
60
+
61
+ Returns
62
+ -------
63
+ labels : numpy.ndarray
64
+ Reference labels.
65
+ confidence : dict
66
+ ``{event_id: confidence}``.
67
+ """
68
+ from .core import smooth
69
+ base = smooth(index, sigma) if sigma else index
70
+ ref = detect(base, cell_area, v_min, floor, return_info=False, **detect_kwargs)
71
+ members = []
72
+ sigmas = [sigma] + ([sigma + d for d in smooth_deltas] if sigma else [])
73
+ for s in sigmas:
74
+ x = smooth(index, s) if s else index
75
+ for df in (0.0,) + tuple(floors_delta):
76
+ if s == sigma and df == 0.0:
77
+ continue
78
+ members.append(detect(x, cell_area, v_min, floor + df, return_info=False, **detect_kwargs))
79
+ return ref, event_confidence(ref, members)
80
+
81
+
82
+ def consensus(ref, members, q=0.5):
83
+ """Consensus footprint: cells of ``ref`` labelled as drought in at least a share ``q`` of ``members``.
84
+
85
+ Returns
86
+ -------
87
+ labels : numpy.ndarray
88
+ Consensus labels (events emptied by the rule are dropped).
89
+ confidence : dict
90
+ Event confidence of the remaining events.
91
+ frequency : numpy.ndarray
92
+ Share of members that label each cell.
93
+ """
94
+ freq = np.mean([m > 0 for m in members], axis=0)
95
+ lab = np.where(freq >= q, ref, 0).astype(np.int32)
96
+ conf = event_confidence(ref, members)
97
+ return lab, {e: c for e, c in conf.items() if (lab == e).any()}, freq