tobac.feature_detection.feature_detection_multithreshold#

tobac.feature_detection.feature_detection_multithreshold(field_in, dxy=None, threshold=None, min_num=0, target='maximum', position_threshold='center', sigma_threshold=0.5, n_erosion_threshold=0, n_min_threshold=0, min_distance=0, feature_number_start=1, PBC_flag='none', vertical_coord=None, vertical_axis=None, detect_subset=None, wavelength_filtering=None, dz=None, strict_thresholding=False, statistic=None, statistics_unsmoothed=False, return_labels=False, use_standard_names=None, converted_from_iris=False, **kwargs)#

Perform feature detection based on contiguous regions.

The regions are above/below a threshold.

Parameters:

  • field_in (iris.cube.Cube or xarray.DataArray) – 2D or 3D field to perform the tracking on (needs to have coordinate ‘time’ along one of its dimensions),

  • dxy (float) – Grid spacing of the input data (in meter).

  • thresholds (list of floats, optional) – Threshold values used to select target regions to track. The feature detection is inclusive of the threshold value(s), i.e. values greater/less than or equal are included in the target region. Default is None.

  • target ({'maximum', 'minimum'}, optional) – Flag to determine if tracking is targetting minima or maxima in the data. Default is ‘maximum’.

  • position_threshold ({'center', 'extreme', 'weighted_diff',) – ‘weighted_abs’}, optional Flag choosing method used for the position of the tracked feature. Default is ‘center’.

  • sigma_threshold (float, optional) – Standard deviation for intial filtering step. Default is 0.5.

  • n_erosion_threshold (int, optional) – Number of pixels by which to erode the identified features. Default is 0.

  • n_min_threshold (int, dict of float to int, or list of int, optional) – Minimum number of identified contiguous pixels for a feature to be detected. Default is 0. If given as a list, the number of elements must match number of thresholds. If given as a dict, the keys need to match the thresholds and the values are the minimum number of identified contiguous pixels for a feature using that specific threshold.

  • min_distance (float, optional) – Minimum distance between detected features (in meters). Default is 0.

  • feature_number_start (int, optional) – Feature id to start with. Default is 1.

  • PBC_flag (str('none', 'hdim_1', 'hdim_2', 'both')) – Sets whether to use periodic boundaries, and if so in which directions. ‘none’ means that we do not have periodic boundaries ‘hdim_1’ means that we are periodic along hdim1 ‘hdim_2’ means that we are periodic along hdim2 ‘both’ means that we are periodic along both horizontal dimensions

  • vertical_coord (str) – Name of the vertical coordinate. If None, tries to auto-detect. It looks for the coordinate or the dimension name corresponding to the string.

  • vertical_axis (int or None.) – The vertical axis number of the data. If None, uses vertical_coord to determine axis. This must be >=0.

  • detect_subset (dict-like or None) – Whether to run feature detection on only a subset of the data. If this is not None, it will subset the grid that we run feature detection on to the range specified for each axis specified. The format of this dict is: {axis-number: (start, end)}, where axis-number is the number of the axis to subset, start is inclusive, and end is exclusive. For example, if your data are oriented as (time, z, y, x) and you want to only detect on values between z levels 10 and 29, you would set: {1: (10, 30)}.

  • wavelength_filtering (tuple, optional) – Minimum and maximum wavelength for horizontal spectral filtering in meter. Default is None.

  • dz (float) – Constant vertical grid spacing (m), optional. If not specified and the input is 3D, this function requires that altitude is available in the features input. If you specify a value here, this function assumes that it is the constant z spacing between points, even if `z_coordinate_name` is specified.

  • strict_thresholding (Bool, optional) – If True, a feature can only be detected if all previous thresholds have been met. Default is False.

  • use_standard_names (bool) – If true, when interpolating a coordinate, it looks for a standard_name and uses that to name the output coordinate, to mimic iris functionality. If false, uses the actual name of the coordinate to output.

  • statistic (dict, optional) – Default is None. Optional parameter to calculate bulk statistics within feature detection. Dictionary with callable function(s) to apply over the region of each detected feature and the name of the statistics to appear in the feature output dataframe. The functions should be the values and the names of the metric the keys (e.g. {‘mean’: np.mean})

  • statistics_unsmoothed (bool, optional) – Default is False. If True, calculate the statistics on the raw data instead of the smoothed input data.

  • return_labels (bool, optional) – Default is False. If True, return the label fields.

  • preserve_iris_datetime_types (bool, optional, default: True) – If True, for iris input, preserve the original datetime type (typically cftime.DatetimeGregorian) where possible. For xarray input, this parameter has no effect.

  • kwargs (dict) – Additional keyword arguments.

  • threshold (list[float])

  • min_num (int)

  • converted_from_iris (bool)

Returns:

  • features (pandas.DataFrame) – Detected features. The structure of this dataframe is explained here

  • labels (xarray DataArray, optional) – Label fields for the respective thresholds. Only returned if return_labels is True.

Return type:

pandas.DataFrame | tuple[xarray.DataArray, pandas.DataFrame]