identify_circular_extrema#

rojak.atmosphere.regions.identify_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', **filter_kwargs)[source]#

Identify circular extrema regions in a 3D spatial DataArray.

Detects local minima or maxima using a circular footprint filter and returns both the point locations of the extrema and the broader regions associated with them, filtered by a threshold condition.

See also

ExtremaKind: Enumeration of extrema types.
apply_extrema_filter(): The underlying extrema filter function.
circular_footprint(): Generates the circular footprint used for filtering.

Parameters:

target_data (xarray.DataArray) – A 3D DataArray to identify extrema in. Must contain the specified latitude and longitude dimensions.
extrema_kind (ExtremaKind) – The type of extrema to identify, either ExtremaKind.MAXIMA or ExtremaKind.MINIMA.
extrema_threshold_value (float, optional) – The threshold value used to filter extrema regions. Combined with is_threshold_less_than to determine which extrema are retained. Defaults to None.
footprint_radius (int) – Radius in grid points of the circular footprint used for the extrema filter. Defaults to 24.
sel_region_indexer (dict, optional) – Optional dictionary of indexers passed to xarray.DataArray.sel() to subset target_data to a specific region before processing. Defaults to None.
lat_dim_name (str) – Name of the latitude dimension in target_data. Defaults to "latitude".
lon_dim_name (str) – Name of the longitude dimension in target_data. Defaults to "longitude".
**filter_kwargs – Additional keyword arguments passed to the underlying scipy filter via apply_extrema_filter().

Returns:

A Dataset with the same coordinates as target_data containing:

local_extrema (xarray.DataArray): A boolean DataArray indicating the locations of local extrema, where True marks an extremum.
extrema_regions (xarray.DataArray): A boolean DataArray indicating grid points belonging to qualifying extrema regions after threshold filtering.

Return type:

xarray.Dataset

Raises:

ValueError – If target_data is not 3D.
ValueError – If target_data does not contain the specified latitude and longitude dimensions.

Example

result = identify_circular_extrema(
    target_data=my_data_array,
    extrema_kind=ExtremaKind.MINIMA,
    extrema_threshold_value=500.0,
    footprint_radius=24,
)
local_extrema = result["local_extrema"]
extrema_regions = result["extrema_regions"]