identify_and_stack_circular_extrema#

rojak.atmosphere.regions.identify_and_stack_circular_extrema(target_data, extrema_kind, extrema_threshold_value=None, footprint_radius=24, sel_region_indexer=None, lat_dim_name='latitude', lon_dim_name='longitude', time_dim_name='time', **filter_kwargs)[source]#

Identify circular extrema in a 3D field and return a per-extremum mask stack.

Detects spatial extrema (minima or maxima) in target_data using a circular structuring element, labels the connected regions surrounding each extremum, and expands the result so that every detected extremum occupies its own index along a new "n_extrema" dimension. The output therefore encodes both which grid cells belong to each extremum and when each extremum occurred.

Processing follows a split-apply-combine pattern to accommodate the variable number of extrema per timestep:

  1. Split - group timesteps by their extrema count so that xarray.apply_ufunc() always receives arrays of a known, fixed output size.

  2. Apply - call _stack_extrema() on each group via _apply_and_combine_on_n_extrema_groups().

  3. Combine - xarray concatenates the groups; results are sorted by time and re-indexed with a flat n_extrema integer coordinate.

Parameters:

  • target_data (xr.DataArray) – Three-dimensional input field. Must have exactly the dimensions {lat_dim_name, lon_dim_name, time_dim_name}.

  • extrema_kind (ExtremaKind) – Whether to detect minima or maxima. Passed directly to the internal __identify_extrema_locations helper.

  • extrema_threshold_value (float, optional) – Minimum absolute value a grid point must exceed to qualify as an extremum. None disables thresholding. Defaults to None.

  • footprint_radius (int) – Radius in grid cells of the circular structuring element used for the morphological extrema filter. Defaults to 24.

  • sel_region_indexer (dict, optional) – If provided, passed to xarray.DataArray.sel() to spatially subset target_data before processing. Defaults to None.

  • lat_dim_name (str) – Name of the latitude dimension. Defaults to "latitude".

  • lon_dim_name (str) – Name of the longitude dimension. Defaults to "longitude".

  • time_dim_name (str) – Name of the time dimension. Defaults to "time".

  • **filter_kwargs (Any) – Additional keyword arguments forwarded to __identify_extrema_locations (e.g. smoothing parameters).

Returns:

Array with dimensions (n_extrema, lat_dim_name, lon_dim_name) and coordinates:

  • n_extrema - flat integer index [0, N) where N is the total number of extrema across all timesteps.

  • time - source timestamp of each extremum, attached to the n_extrema dimension.

Pixel values follow the 0 / 1 / 2 encoding described in _stack_extrema(). If no extrema are identified, n_extrema has size 0.

Return type:

xr.DataArray

Raises:

  • ValueError – If target_data is not 3D.

  • ValueError – If the dimensions of target_data do not match the specified lat_dim_name, lon_dim_name, and time_dim_name.

Warns:

UserWarning – If no extrema are identified in target_data.