Detection#

Segments the 2D reflectivity field into labelled convective cells using binary thresholding, morphological closing, and connected component analysis.

Segment convective cells from gridded radar reflectivity.

Detects convective cell boundaries from a 2D reflectivity field (at a fixed altitude) and returns a labeled image where each cell is assigned a unique integer ID.

Two families of methods build the convective mask that a shared watershed + size-filtering backend then labels into cells:

  • threshold (default) — reflectivity above a fixed dBZ threshold. Needs only the 2D CAPPI, so it works on any run out of the box.

  • pyart convective/stratiform classifiers — conv_strat_raut, conv_strat_yuter, feature_detection, steiner_conv_strat — the convective class(es) of a per-pixel classification, computed over the full 3D grid via pyart.xradar.Xgrid.

Only the mask differs between methods; downstream labeling, size filtering, and size-ranked numbering are identical, so the output contract (integer, non-negative, 2D cell_labels) is unchanged and tracking is unaffected.

Cell size ordering: cells are numbered 1, 2, 3, … in decreasing order of size (area in grid points), so the largest cell is always ID 1. This ensures reproducible analysis and allows size-based filtering in downstream steps.

class adapt.modules.detection.module.CarriedLabels(labels, ages)#

Bases: object

The previous frame’s cell labels advected to this frame, with carry ages.

labels is an int raster (y, x), 0 = none; ages[i] is the carry age of label i + 1 (0 = detected independently in the previous frame).

Parameters:

  • labels (ndarray)

  • ages (tuple[int, ...])

ages: tuple[int, ...]#
labels: ndarray#
class adapt.modules.detection.module.RadarCellSegmenter(config)#

Bases: object

Convective-cell detection and labeling for 2D radar reflectivity.

Applies a series of image-processing steps to identify and label convective cells:

  1. Convective mask: mark convective grid points (threshold uses reflectivity > threshold; the pyart methods use the convective class of a convective/stratiform classification)

  2. Morphological closing: fill small holes within cells (tunable)

  3. Cell seeding + labeling: h-maxima seeds — plus, with seed_carry, seeds carried from the previous frame — grown by watershed

  4. Size filtering: remove cells smaller than min_gridpoints or larger than max_gridpoints (optional)

  5. Relabeling by size: largest cell gets label 1, second-largest 2, etc.

The output is a labeled image (xarray.DataArray) with integer cell IDs. Cell ID = 0 means no cell; cell ID > 0 means part of that cell.

Configuration#

Reads from a validated DetectionConfig:

  • methodstr

    threshold (default), conv_strat_raut, conv_strat_yuter, feature_detection or steiner_conv_strat. The pyart methods require the 3D grid dataset (grid_ds).

  • method_paramsdict

    Resolved parameters for the selected method. For threshold this is {"threshold": <dBZ>}; for the pyart methods it is the algorithm’s keyword arguments (splatted into the pyart call, recorded in the output).

  • closing_radiusint, default 2 (disk radius for mask closing; 0 = off)

    Morphological closing footprint. (1, 1) means no closing.

  • filter_by_sizebool, default True

    Whether to apply cell size filtering.

  • min_cellsize_gridpointint, default 5

    Minimum cell size in grid points. Smaller cells are removed.

  • max_cellsize_gridpointint or None, default None

    Maximum cell size in grid points. If None, no upper limit.

Notes

  • Input dataset must be 2D (already sliced at a fixed altitude by processor)

  • Not thread-safe; create separate instances for concurrent processing

  • Cell numbering is deterministic: largest cells always get lower IDs

decisions()#

The decision record of the most recent segment call (analysis only).

Return type:

SegmentationDecisions

segment(ds, grid_ds=None, carried=None)#

Segment 2D reflectivity and return dataset with cell labels.

The configured method determines how the convective mask is built; the mask is then labeled into size-ranked cells by a shared backend. The output dataset is a copy of the input with an added cell_labels variable of integer cell IDs.

Parameters:

  • ds (Dataset) – 2D dataset (dims y, x) with the reflectivity field, sliced at the analysis z-level. Supplies the reflectivity, coordinates, and attrs for the output.

  • grid_ds (Dataset | None) – Full 3D gridded dataset (ingest’s in-memory output). Required by the pyart convective/stratiform methods (they classify the 3D grid via pyart.xradar.Xgrid); unused by threshold.

  • carried (CarriedLabels | None) – The previous frame’s labels advected to this frame, with carry ages. A connected component of the mask that holds fewer independent seeds than prior cells has lost a core; only that deficit is filled with extra watershed markers, so a cell’s own mispositioned footprint never splits it. Requires seed_carry.

Returns:

Copy of ds with an int32 cell_labels variable (0 = background, 1..N = cells by decreasing size). Label attrs record method, threshold, z-level, and size-filter settings and, with seed_carry, carry_age per label.

Return type:

Dataset