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 with smooth() (the paper uses sigma = 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 pi in index units, or "auto:k" (see noise_persistence()).

  • pers_gamma (float, default 1.0) – Exponent gamma of the volume weighting P_V = P (V / v_min)^gamma; 0 gives unweighted persistence.

  • inherit (float, default 0.75) – Inherited share q for 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 (0 returns 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)): k times 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 j takes the identity of an older event i when at least a share inherit of the footprint of j in its first month was occupied by i in 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 q of 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 N is computed; the instability of floor j is the mean relative change of N to its neighbours. Floors that give fewer than min_events events, or an event longer than max_duration_frac of the record, are excluded. No impact data are used.

Parameters:
  • index – As in detect() (index already smoothed).

  • cell_area – As in detect() (index already smoothed).

  • v_min – As in detect() (index already 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, eligible for every candidate.

driftdrought.core.patches(labels)[source]

Monthly 8-connected patches of every event (helper for lineage diagnostics).

Returns:

Patch labels (time, y, x), unique over the whole cube.

Return type:

numpy.ndarray of int

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(), with pet the potential evapotranspiration.

driftdrought.indices.smi(sm, scale, baseline)[source]

Soil-moisture index: empirical percentile of sm (mean over scale months) mapped to a standard normal.

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_events and true_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 (-index smoothed with sigma, 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 <= thr are 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 (at iou_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

driftdrought.metrics.partition_agreement(a, b, mask=None)[source]

Adjusted Rand index and variation of information (bits) between two label cubes.

Computed over the cells where either cube labels an event (or over mask).

driftdrought.metrics.cv(values)[source]

Coefficient of variation (e.g. of event counts across thresholds).

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 ref with any event of other.

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 ref over the catalogues members.

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 sigma is given, otherwise the already smoothed index.

  • sigma (float, optional) – Smoothing width of the reference run; when given, runs with sigma + smooth_deltas are 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 ref labelled as drought in at least a share q of members.

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_e of 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.bh(p)[source]

Benjamini–Hochberg adjusted p-values (q-values).

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_surrogates phase-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.