API reference
Detection
DRIFT: Drought Regions Identified From the space–time component Tree.
A connected-component catalogue at one threshold is one horizontal cut through the max-tree of the deficit
field d = -index. DRIFT builds the whole max-tree on the (time, y, x) grid, keeps the nodes that are large
and deep enough (volume >= v_min and level >= floor), condenses chains of such nodes into clusters and
selects events inside the hierarchy with volume-weighted topological persistence and lineage inheritance.
- driftdrought.core.detect(index, cell_area, v_min, floor=0.5, *, selection='persistence_vl', persistence='auto:3', pers_gamma=1.0, inherit=0.75, footprint='birth', ext_floor=None, connectivity=26, max_frac=None, return_info=True)[source]
Detect drought events in a space–time index field with DRIFT.
- Parameters:
index (numpy.ndarray) – Standardized drought index (drought negative, e.g. SPI or SPEI), shape
(time, y, x), NaN outside the domain. Smooth it first withsmooth()(the paper usessigma = 2.5).cell_area (numpy.ndarray) – Cell areas
(y, x)(km², or 1 for unit cells); 0 outside the domain.v_min (float) – Minimum space–time volume of a significant node, in area × time units (e.g. km² month).
floor (float, default 0.5) – Weakest deficit that may belong to an event (
index <= -floor).select_floor()chooses it by the event-count stability rule.selection ({"persistence_vl", "persistence_v", "persistence", "leaf", "eom"}, default "persistence_vl") – Event-selection rule.
"persistence_vl"is the final DRIFT (volume-weighted persistence + lineage inheritance);"persistence_v"omits inheritance;"persistence"uses unweighted persistence (DRIFT-P);"leaf"takes the leaves of the condensed tree;"eom"uses excess-of-mass stability as in HDBSCAN.persistence (float or str, default "auto:3") – Persistence threshold
piin index units, or"auto:k"(seenoise_persistence()).pers_gamma (float, default 1.0) – Exponent
gammaof the volume weightingP_V = P (V / v_min)^gamma; 0 gives unweighted persistence.inherit (float, default 0.75) – Inherited share
qfor lineage inheritance (only with"persistence_vl").footprint ({"birth", "watershed"}, default "birth") –
"birth": the selected component itself;"watershed": events grown by a marker-controlled watershed into all cells with deficit>= ext_floor(hysteresis footprint).ext_floor (float, optional) – Extension floor of the watershed footprint (default:
floor).connectivity ({26, 6}, default 26) – Space–time neighbourhood.
max_frac (float, optional) – Only for
selection="eom": clusters larger than this share of the domain volume cannot be selected.return_info (bool, default True) – Also return the per-event table.
- Returns:
labels (numpy.ndarray of int32) – Event labels
(time, y, x), 0 = no event.info (pandas.DataFrame) – One row per event:
event,birth_threshold,peak_index,volume,persistence,n_cores(number of significant sub-clusters, i.e. nested pulses).
Examples
>>> from driftdrought import synthetic, detect, smooth >>> idx, truth, meta = synthetic.generate("S1_isolated", noise=0.3, seed=0) >>> labels, info = detect(smooth(idx, 2.5), cell_area=1.0 + 0 * idx[0], v_min=50)
- driftdrought.core.smooth(index, sigma)[source]
Three-dimensional Gaussian smoothing that keeps invalid (NaN) cells invalid.
- Parameters:
index (numpy.ndarray) – Standardized index, shape
(time, y, x); NaN outside the domain.sigma (float or sequence of float) – Gaussian width in time steps and cells (
0returns the input).
- Returns:
Smoothed field with NaN at the same cells as
index.- Return type:
numpy.ndarray
- driftdrought.core.cell_area_km2(lat, res)[source]
Area of regular latitude–longitude cells.
- Parameters:
lat (array_like) – Cell-centre latitudes in degrees.
res (float) – Grid spacing in degrees.
- Returns:
Cell areas in km² (same shape as
lat).- Return type:
numpy.ndarray
- driftdrought.core.noise_persistence(deficit, spec)[source]
Noise-adaptive persistence threshold
auto:k.pi = k * 1.4826 * MAD(d - G_2(d)):ktimes a robust estimate of the standard deviation of the high-frequency residual of the deficit field (Equation 2 of the DRIFT paper).- Parameters:
deficit (numpy.ndarray) – Deficit field
-index; invalid cells are<= -9.spec (str) –
"auto:k", e.g."auto:3".
- Returns:
Persistence threshold in index units.
- Return type:
float
- driftdrought.core.merge_branches(labels, inherit=0.75)[source]
Lineage inheritance: give one identity to the branches of a splitting drought.
Event
jtakes the identity of an older eventiwhen at least a shareinheritof the footprint ofjin its first month was occupied byiin the previous month (Equation 4 of the paper). Droughts that only touch, or converge, inherit no cells and keep separate identities. The rule is transitive (union–find).- Parameters:
labels (numpy.ndarray of int) – Event labels
(time, y, x), 0 = no event.inherit (float, default 0.75) – Minimum inherited share
qof the onset footprint.
- Returns:
Labels after merging.
- Return type:
numpy.ndarray of int
- driftdrought.core.event_table(labels, index, cell_area, times=None)[source]
Summary of a label field: one row per event.
- Parameters:
labels (numpy.ndarray of int) – Event labels
(time, y, x).index (numpy.ndarray) – Index field used for the severity statistics.
cell_area (numpy.ndarray or float) – Cell areas
(y, x).times (sequence, optional) – Time stamps of the first axis (default: integer steps).
- Returns:
event, start, end, duration, volume, max_area, peak_time, mean_index.- Return type:
pandas.DataFrame
- driftdrought.core.select_floor(index, cell_area, v_min, floors=array([0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 1., 1.1, 1.2, 1.3, 1.4]), min_events=5, max_duration_frac=0.3333333333333333, **detect_kwargs)[source]
Choose the deficit floor by event-count stability (Equation 5 of the paper).
For each candidate floor the number of events
Nis computed; the instability of floorjis the mean relative change ofNto its neighbours. Floors that give fewer thanmin_eventsevents, or an event longer thanmax_duration_fracof the record, are excluded. No impact data are used.- Parameters:
index – As in
detect()(indexalready smoothed).cell_area – As in
detect()(indexalready smoothed).v_min – As in
detect()(indexalready smoothed).floors (sequence of float) – Candidate floors in increasing order.
min_events (int, default 5)
max_duration_frac (float, default 1/3)
**detect_kwargs – Passed to
detect().
- Returns:
best (float) – Selected floor.
scan (pandas.DataFrame) –
floor, n_events, max_duration, instability, eligiblefor every candidate.
Drought indices
Standardized drought indices on monthly (time, lat, lon) arrays, fitted per calendar month.
SPI: two-parameter gamma distribution (Thom maximum-likelihood approximation) with a zero-precipitation mass.
SPEI: three-parameter log-logistic distribution fitted by unbiased probability-weighted moments (Vicente-Serrano et al., 2010).
SMI: empirical (Weibull plotting position) percentile mapped to a standard normal.
All fits use the baseline period only; values are clipped to [-3.09, 3.09].
- driftdrought.indices.spi(precip, scale, baseline)[source]
Standardized Precipitation Index (McKee et al., 1993), fitted per calendar month.
- Parameters:
precip (xarray.DataArray) – Monthly precipitation with dimensions
(time, lat, lon).scale (int) – Accumulation period in months (e.g. 3 for SPI-3).
baseline ((int, int)) – First and last year of the calibration period, e.g.
(1981, 2020).
- Returns:
SPI clipped to [-3.09, 3.09]; NaN where the input is NaN.
- Return type:
xarray.DataArray
- driftdrought.indices.spei(precip, pet, scale, baseline)[source]
Standardized Precipitation Evapotranspiration Index (Vicente-Serrano et al., 2010).
Three-parameter log-logistic distribution fitted by probability-weighted moments; left-skewed samples are fitted on the reflected water balance. Parameters as in
spi(), withpetthe potential evapotranspiration.
Synthetic benchmark
Synthetic drought cubes with known events (the DRIFT benchmark).
Gaussian scenarios (generate()), shape (60, 60, 80) = (months, rows, columns):
S1_isolated— stationary, well-separated events;S2_advection— events that migrate 0.3–1.2 cells per month;S3_splitmerge— one event splits into two diverging lobes (one true split), two others converge and touch;S4_fragmented— weaker events on strongly correlated (red) noise.
Irregular scenarios (generate_irregular()) place real drought shapes from a library built with
build_library() from any label field and index (for example, a DRIFT catalogue of your own region), so the
method can be tuned and tested on events with the geometry of the target region.
Truth: a cell belongs to event k if its clean deficit is >= support and is the largest contribution.
- driftdrought.synthetic.generate(scenario, noise, seed, support=0.5)[source]
Gaussian benchmark cube.
- Parameters:
scenario (str) – One of
SCENARIOS.noise (float) – Noise standard deviation (the paper uses 0.3 and 0.6).
seed (int) – Random seed (the paper uses 0–19).
support (float, default 0.5) – Clean-deficit level that defines the true event extent.
- Returns:
index (numpy.ndarray of float32) – Synthetic standardized index
(60, 60, 80)(drought negative).truth (numpy.ndarray of int32) – True event labels.
meta (dict) –
n_eventsandtrue_splits.
- driftdrought.synthetic.build_library(labels, index, min_cells=200, sigma=1.0)[source]
Event-shape library from a label field and its index.
Each entry is the space–time deficit (
-indexsmoothed withsigma, clipped at 0) inside one event, cropped to its bounding box.- Parameters:
labels (numpy.ndarray of int) – Event labels
(time, y, x)(e.g. a DRIFT catalogue).index (numpy.ndarray) – Index field of the same shape.
min_cells (int, default 200) – Smallest event (in voxels) kept in the library.
- Return type:
list of numpy.ndarray
- driftdrought.synthetic.generate_irregular(library, noise, seed, support=0.5, red_noise=False, n_events=(3, 6), box=((10, 28), (15, 36), (20, 48)))[source]
Benchmark cube with irregular, multi-core events drawn from
library.Each event is a library shape rescaled to a random box, mirrored with probability 0.5, normalized to a peak amplitude of 1.2–2.5 and placed at random.
- Parameters:
library (list of numpy.ndarray) – Output of
build_library().noise (float) – Noise standard deviation.
seed (int) – Random seed.
red_noise (bool, default False) – Strongly correlated noise (as scenario S4) instead of weakly correlated noise.
n_events ((int, int)) – Minimum and maximum number of events.
box (three (min, max) pairs) – Ranges of the rescaled event size in months, rows and columns.
- Returns:
As in
generate().- Return type:
index, truth, meta
Reference detectors
Reference detectors used in the DRIFT benchmark.
ccl2d_overlap()— monthly 8-connected patches linked across months by overlap (Andreadis et al., 2005).ccl3d()— 26-connected space–time components with a minimum volume (Lloyd-Hughes, 2012; Diaz et al., 2020).dbscan3d()— density-based clustering of drought voxels (Ester et al., 1996; Cammalleri & Toreti, 2023).
All take a standardized index (time, y, x) (drought negative, NaN outside the domain) and a threshold, and return
an integer label cube (0 = no event).
- driftdrought.baselines.ccl2d_overlap(index, thr, cell_area, min_frac=0.016, overlap_frac=0.016)[source]
Two-dimensional connected components linked through time by overlap.
- Parameters:
index (numpy.ndarray) – Index
(time, y, x).thr (float) – Drought threshold (cells with
index <= thrare dry).cell_area (numpy.ndarray) – Cell areas
(y, x).min_frac (float) – Minimum patch area as a share of the domain area.
overlap_frac (float) – Minimum overlap between patches of consecutive months, as a share of the domain area.
- driftdrought.baselines.ccl3d(index, thr, cell_area, min_volume_frac=0.0)[source]
26-connected space–time components with a minimum volume.
- Parameters:
min_volume_frac (float) – Minimum event volume as a share of (domain area × one time step).
- driftdrought.baselines.dbscan3d(index, thr, s_xy=3, s_t=3, fr_mp=0.25, c_min=50)[source]
Density-based clustering (DBSCAN) of drought voxels in a scaled space–time window.
- Parameters:
s_xy (int) – Half-widths of the search window in cells and time steps.
s_t (int) – Half-widths of the search window in cells and time steps.
fr_mp (float) – Minimum share of the window that must be dry for a core point.
c_min (int) – Minimum cluster size in voxels.
Metrics
Evaluation metrics for space–time event catalogues.
Against a known truth (synthetic benchmark):
object matching on 3-D volumes (area-weighted IoU, Hungarian assignment): precision, recall, F1, mean IoU of matches, relative volume error;
HOTA (Luiten et al., 2021) with DetA and AssA, averaged over localization thresholds 0.05–0.95; a detection is the slice of an event in one time step;
partition agreement: adjusted Rand index and variation of information.
Between catalogues without truth (real data) the partition and matching metrics are used symmetrically.
- driftdrought.metrics.object_match(gt, pr, w, iou_thr=0.5)[source]
Match true and detected events by space–time IoU (Hungarian assignment).
- Parameters:
gt (numpy.ndarray of int) – True and detected label cubes
(time, y, x).pr (numpy.ndarray of int) – True and detected label cubes
(time, y, x).w (numpy.ndarray or float) – Cell weights (areas) broadcastable to the cube.
iou_thr (float, default 0.5) – IoU needed for a match to count as a true positive.
- Returns:
precision, recall, f1(atiou_thr),f1_iou25,mean_iou,vol_err,n_gt,n_pred.- Return type:
dict
- driftdrought.metrics.hota(gt, pr, w, alphas=array([0.05, 0.1, 0.15, 0.2, 0.25, 0.3, 0.35, 0.4, 0.45, 0.5, 0.55, 0.6, 0.65, 0.7, 0.75, 0.8, 0.85, 0.9, 0.95]))[source]
Higher Order Tracking Accuracy (Luiten et al., 2021) for label cubes.
Each time step is a frame and each event slice a detection; the similarity is the IoU. HOTA, DetA and AssA are averaged over the localization thresholds
alphas.- Returns:
HOTA, DetA, AssA, HOTA_05.- Return type:
dict
Event confidence
Event confidence: how robust each event is to parameters or to the input product.
The confidence of event e is the mean, over K alternative catalogues L_k, of the best space–time IoU between
e and any event of L_k (Equation 9 of the DRIFT paper). With catalogues from perturbed parameters it measures
parameter robustness; with a catalogue from another precipitation product it is the product confidence.
- driftdrought.confidence.best_iou(ref, other)[source]
Best IoU of every event of
refwith any event ofother.- Parameters:
ref (numpy.ndarray of int) – Label cubes of equal shape.
other (numpy.ndarray of int) – Label cubes of equal shape.
- Returns:
Array indexed by the event id of
ref(entry 0 unused).- Return type:
numpy.ndarray
- driftdrought.confidence.event_confidence(ref, members)[source]
Mean best IoU of each event of
refover the cataloguesmembers.- Returns:
{event_id: confidence}with values in [0, 1].- Return type:
dict
- driftdrought.confidence.parameter_confidence(index, cell_area, v_min, floor, floors_delta=(-0.1, 0.1), sigma=None, smooth_deltas=(-0.5, 0.5), **detect_kwargs)[source]
Confidence of the events of a reference run against runs with perturbed floor (and smoothing).
- Parameters:
index (numpy.ndarray) – Raw (unsmoothed) index when
sigmais given, otherwise the already smoothed index.sigma (float, optional) – Smoothing width of the reference run; when given, runs with
sigma + smooth_deltasare added.
- Returns:
labels (numpy.ndarray) – Reference labels.
confidence (dict) –
{event_id: confidence}.
- driftdrought.confidence.consensus(ref, members, q=0.5)[source]
Consensus footprint: cells of
reflabelled as drought in at least a shareqofmembers.- Returns:
labels (numpy.ndarray) – Consensus labels (events emptied by the rule are dropped).
confidence (dict) – Event confidence of the remaining events.
frequency (numpy.ndarray) – Share of members that label each cell.
Significance
Event-level significance against phase-randomized surrogate fields.
H0(e): event e is a fluctuation of a stationary field with the same space–time power spectrum and marginal
distribution as the analysed field. Surrogates are 3-D Fourier phase randomizations (Theiler et al., 1992) with the
marginal restored by rank remapping. Each surrogate is processed with exactly the same DRIFT configuration.
Event score (volume-weighted deficit contrast): S_e = (max D_e - floor) (V_e / v_min)^gamma.
p_fw: family-wise p-value from the maximum score of every surrogate;p_pool: per-event p-value from all surrogate events, to be combined with Benjamini–Hochberg (bh()).
The test is conservative because the surrogates keep part of the power of the observed events.
- driftdrought.significance.phase_surrogate(x, rng)[source]
Phase-randomized surrogate of
x(NaN cells stay NaN; marginal distribution kept).
- driftdrought.significance.event_scores(labels, deficit, cell_area, floor, v_min, gamma=1.0)[source]
Score
S_eof every event. Returns{event: (score, peak_deficit, volume)}.
- driftdrought.significance.pvalues(obs, null_scores)[source]
Family-wise and pooled p-values of observed scores against lists of surrogate event scores.
- driftdrought.significance.surrogate_test(index, cell_area, v_min, floor=0.5, n_surrogates=29, seed=0, gamma=1.0, **detect_kwargs)[source]
Detect events and test each against
n_surrogatesphase-randomized surrogates.- Parameters:
index (numpy.ndarray) – Smoothed index used for detection.
n_surrogates (int, default 29) – Number of surrogates (29 gives a smallest family-wise p of 0.033).
- Returns:
labels (numpy.ndarray)
table (pandas.DataFrame) –
event, score, p_fw, p_pool, q_pool.