pyart.retrieve.feature_detection#

pyart.retrieve.feature_detection(grid, dx=None, dy=None, level_m=None, always_core_thres=42, bkg_rad_km=11, use_cosine=True, max_diff=5, zero_diff_cos_val=55, scalar_diff=1.5, use_addition=True, calc_thres=0.75, weak_echo_thres=5.0, min_val_used=5.0, dB_averaging=True, remove_small_objects=True, min_km2_size=10, binary_close=False, val_for_max_rad=30, max_rad_km=5.0, core_val=3, nosfcecho=0, weakecho=3, bkgd_val=1, feat_val=2, field=None, estimate_flag=True, estimate_offset=5, overest_field=None, underest_field=None)[source]#

This function can be used to detect features in a field (e.g. reflectivity, rain rate, snow rate, etc.) described by Tomkins et al. (2023) and based on original convective-stratiform algorithms developed by Steiner et al. (1995), Yuter et al. (2005) and Yuter and Houze (1997) algorithm.

Author: Laura Tomkins (@lauratomkins)

Parameters:

  • grid (Grid) – Grid containing reflectivity field to partition.

  • dx, dy (float, optional) – The x- and y-dimension resolutions in meters, respectively. If None the resolution is determined from the first two axes values parsed from grid object.

  • level_m (float, optional) – Desired height in meters to run feature detection algorithm.

  • always_core_thres (float, optional) – Threshold for points that are always features. All values above the threshold are classified as features.

  • bkg_rad_km (float, optional) – Radius to compute background reflectivity in kilometers. Default is 11 km. Recommended to be at least 3 x grid spacing

  • use_cosine (bool, optional) – Boolean used to determine if a cosine scheme (see Yuter and Houze (1997)) should be used for identifying cores (True) or if a simpler scalar scheme (False) should be used.

  • max_diff (float, optional) – Maximum difference between background average and reflectivity in order to be classified as features. “a” value in Eqn. B1 in Yuter and Houze (1997)

  • zero_diff_cos_val (float, optional) – Value where difference between background average and reflectivity is zero in the cosine function “b” value in Eqn. B1 in Yuter and Houze (1997)

  • scalar_diff (float, optional) – If using a scalar difference scheme, this value is the multiplier or addition to the background average

  • use_addition (bool, optional) – Determines if a multiplier (False) or addition (True) in the scalar difference scheme should be used

  • calc_thres (float, optional) – Minimum percentage of points needed to be considered in background average calculation

  • weak_echo_thres (float, optional) – Threshold for determining weak echo. All values below this threshold will be considered weak echo

  • min_val_used (float, optional) – Minimum value used for classification. All values below this threshold will be considered no surface echo See Yuter and Houze (1997) and Yuter et al. (2005) for more detail. Units based on input field

  • dB_averaging (bool, optional) – True if using dBZ reflectivity values that need to be converted to linear Z before averaging. False for other non-dBZ values (i.e. snow rate)

  • remove_small_objects (bool, optional) – Determines if small objects should be removed from core array. Default is True.

  • min_km2_size (float, optional) – Minimum size of Cores to be considered. Cores less than this size will be removed. Default is 10 km^2.

  • binary_close (bool, optional) – Determines if a binary closing should be performed on the cores. Default is False.

  • val_for_max_rad (float, optional) – value used for maximum radius. Cores with values above this will have the maximum radius incorporated.

  • max_rad_km (float, optional) – Maximum radius around cores to classify as feature. Default is 5 km

  • core_val (int, optional) – Value for points classified as cores

  • nosfcecho (int, optional) – Value for points classified as no surface echo, based on min_val_used

  • weakecho (int, optional) – Value for points classified as weak echo, based on weak_echo_thres.

  • bkgd_val (int, optional) – Value for points classified as background echo.

  • feat_val (int, optional) – Value for points classified as features.

  • field (str, optional) – Field in grid to find objects in. None will use the default reflectivity field name from the Py-ART configuration file.

  • estimate_flag (bool, optional) – Determines if over/underestimation should be applied. If true, the algorithm will also be run on the same field wih the estimate_offset added and the same field with the estimate_offset subtracted. Default is True (recommended)

  • estimate_offset (float, optional) – Value used to offset the field values by for the over/underestimation application. Default value is 5 dBZ.

  • overest_field (str, optional) – Name of field in grid object used to calculate the overestimate if estimate_flag is True.

  • underest_field (str, optional) – Name of field in grid object used to calculate the underestimate if estimate_flag is True.

Returns:

feature_dict (dict) – Feature detection classification dictionary.

References

Steiner, M. R., R. A. Houze Jr., and S. E. Yuter, 1995: Climatological Characterization of Three-Dimensional Storm Structure from Operational Radar and Rain Gauge Data. J. Appl. Meteor., 34, 1978-2007.

Yuter, S. E., and R. A. Houze, Jr., 1997: Measurements of raindrop size distributions over the Pacific warm pool and implications for Z-R relations. J. Appl. Meteor., 36, 847-867. https://doi.org/10.1175/1520-0450(1997)036%3C0847:MORSDO%3E2.0.CO;2

Yuter, S. E., R. A. Houze, Jr., E. A. Smith, T. T. Wilheit, and E. Zipser, 2005: Physical characterization of tropical oceanic convection observed in KWAJEX. J. Appl. Meteor., 44, 385-415. https://doi.org/10.1175/JAM2206.1

Tomkins, L. M., S. E. Yuter, and M. A. Miller, 2024: Objective identification of faint and strong features in radar observations of winter storms. in prep.