Clutter Identification and Hydrometeor Classification (HMC)#

filter_gabella

Clutter identification filter developed by [Gabella et al., 2002].

filter_gabella_a

First part of the Gabella filter looking for large reflectivity gradients.

filter_gabella_b

Second part of the Gabella filter comparing area to circumference of contiguous echo regions.

filter_cloudtype

Identification of non-meteorological echoes based on cloud type.

filter_window_distance

2d filter looking for large reflectivity gradients.

histo_cut

Histogram based clutter identification.

classify_echo_fuzzy

Fuzzy echo classification and clutter identification based on polarimetric moments.

msf_index_indep

Retrieve membership function values based on independent observable

trapezoid

Calculates membership of obs using trapezoidal membership functions

fuzzyfi

Iterate over all hmc-classes and retrieve memberships

probability

Calculate probability of hmc-class for every data bin.

classify

Calculate probability of hmc-class for every data bin.

ClassifyMethods

wradlib xarray SubAccessor methods for Classify.

wradlib.classify.filter_gabella(obj, *, wsize=5, **kwargs)[source]#
wradlib.classify.filter_gabella(obj: DataArray, **kwargs)

Clutter identification filter developed by [Gabella et al., 2002].

This is a two-part identification algorithm using echo continuity and minimum echo area to distinguish between meteorological (rain) and non- meteorological echos (ground clutter etc.)

Parameters
  • obj (numpy.ndarray)

  • wsize (int, optional) – Size of the window surrounding the central pixel, defaults to 5.

Keyword Arguments
  • thrsnorain (float) –

  • tr1 (float) –

  • n_p (int) –

  • tr2 (float) –

  • rm_nans (bool) – True replaces nans with Inf False takes nans into acount

  • radial (bool) – True to use radial information only in filter_gabella_a.

  • cartesian (bool) – True if cartesian data are used, polar assumed if False.

Returns

output (numpy.ndarray) – boolean array with pixels identified as clutter set to True.

Examples

See Clutter detection using the Gabella approach.

wradlib.classify.filter_gabella_a(obj, wsize, tr1, *, cartesian=False, radial=False)[source]#
wradlib.classify.filter_gabella_a(obj: DataArray, **kwargs)

First part of the Gabella filter looking for large reflectivity gradients.

This function checks for each pixel in img how many pixels surrounding it in a window of wsize are by tr1 smaller than the central pixel.

Parameters
  • obj (numpy.ndarray) – radar image to which the filter is to be applied

  • wsize (int) – Size of the window surrounding the central pixel

  • tr1 (float) – Threshold value

  • cartesian (bool) – Specify if the input grid is Cartesian or polar

  • radial (bool) – Specify if only radial information should be used

Returns

output (numpy.ndarray) – an array with the same shape as img, containing the filter’s results.

Examples

See Clutter detection using the Gabella approach.

wradlib.classify.filter_gabella_b(obj, *, thrs=0.0)[source]#
wradlib.classify.filter_gabella_b(obj: DataArray, **kwargs)

Second part of the Gabella filter comparing area to circumference of contiguous echo regions.

Parameters
  • obj (numpy.ndarray)

  • thrs (float) – Threshold below which the field values will be considered as no rain

Returns

output (numpy.ndarray) – contains in each pixel the ratio between area and circumference of the meteorological echo it is assigned to or 0 for non precipitation pixels.

Examples

See Clutter detection using the Gabella approach.

wradlib.classify.filter_cloudtype(img, cloud, *, thrs=0, snow=False, low=False, cirrus=False, smoothing=None, grid='polar', scale=None)[source]#

Identification of non-meteorological echoes based on cloud type.

Parameters
  • img (numpy.ndarray) – radar image to which the filter is to be applied

  • cloud (numpy.ndarray) – image with collocated cloud value from MSG SAFNWC PGE02 product

  • thrs (float) – Threshold above which to identify clutter

  • snow (bool) – Switch to use PGE02 class “land/sea snow” for clutter identification

  • low (bool) – Switch to use PGE02 class very low stratus, very low cumulus and low cumulus for clutter identification

  • cirrus (bool) – Switch to use PGE02 class “very thin cirrus” and “fractional clouds” for clutter identification

  • smoothing (float) – Size [m] of the smoothing window used to take into account various localisation errors (e.g. advection, parallax)

  • grid (str) – “polar” or “cartesian”

  • scale (float or tuple) – float or tuple of 2 floats range [m] scale for polar grid x[m] and y[m] scale for cartesian grid

Returns

output (numpy.ndarray) – a boolean array containing TRUE where clutter has been identified.

wradlib.classify.filter_window_distance(img, rscale, *, fsize=1500, tr1=7)[source]#
wradlib.classify.filter_window_distance(obj: DataArray, **kwargs)
wradlib.classify.filter_window_distance(obj: Dataset, **kwargs)

2d filter looking for large reflectivity gradients.

This function counts for each bin in img the percentage of surrounding bins in a window of half size fsize which are not tr1 smaller than the central bin. The window is defined using geometrical distance.

Parameters
  • img (numpy.ndarray) – 2d polar data to which the filter is to be applied

  • rscale (float) – range [m] scale of the polar grid

  • fsize (int) – Half-size [m] of the square window surrounding the central pixel

  • tr1 (float) – Threshold value

Returns

output (numpy.ndarray) – an array with the same shape as img, containing the filter’s results.

wradlib.classify.histo_cut(obj, *, upper_frequency=0.01, lower_frequency=0.01)[source]#
wradlib.classify.histo_cut(obj: DataArray, **kwargs)

Histogram based clutter identification.

This identification algorithm uses the histogram of temporal accumulated rainfall. It iteratively detects classes whose frequency falls below a specified percentage (1% by default) of the frequency of the class with the biggest frequency and remove the values from the dataset until the changes from iteration to iteration falls below a threshold. This algorithm is able to detect static clutter as well as shadings.

The tresholds for the upper frequency (clutter) and the lower frequency (shading) can be parameterized by the respective kwargs, upper_frequency/lower_frequency.

It is suggested to choose a representative time periode for the input precipitation accumulation. The recommended time period should cover one year.

Parameters
  • obj (numpy.ndarray) – spatial array containing rain accumulation

  • upper_frequency (float, optional) – Upper frequency percentage for clutter detection, defaults to 0.01.

  • lower_frequency (float, optional) – Lower frequency percentage for shading detection, defaults to 0.01.

Returns

output (numpy.ndarray) – uint8 array with pixels identified as clutter set to 1 and shadings set to 2. Remaining pixels set to 0. Users strictly relying on a boolean mask might have to explicitely cast to boolean (adding .astype(np.bool) on the return).

Examples

See Heuristic clutter detection based on distribution properties ("histo cut").

wradlib.classify.classify_echo_fuzzy(dat, *, weights=None, trpz=None)[source]#
wradlib.classify.classify_echo_fuzzy(obj: Dataset, dat, **kwargs)

Fuzzy echo classification and clutter identification based on polarimetric moments.

The implementation is based on [Vulpiani et al., 2012]. At the moment, it only distinguishes between meteorological and non-meteorological echos.

Changed in version 1.4.0: The implementation was extended using depolarization ratio (dr) and clutter phase alignment (cpa).

Changed in version 2.0.0: Returns probability of meteorological echos instead of clutter mask

For Clutter Phase Alignment (CPA) see [Hubbert et al., 2009a] and [Hubbert et al., 2009b]

For each decision variable and radar bin, the algorithm uses trapezoidal functions in order to define the membership to the non-meteorological echo class. Based on pre-defined weights, a linear combination of the different degrees of membership is computed. The echo is assumed to be non-meteorological in case the linear combination exceeds a threshold.

At the moment, the following decision variables are considered:

  • Texture of differential reflectivity (zdr) (mandatory)

  • Texture of correlation coefficient (rho) (mandatory)

  • Texture of differential propagation phase (phidp) (mandatory)

  • Doppler velocity (dop) (mandatory)

  • Static clutter map (map) (mandatory)

  • Correlation coefficient (rho2) (additional)

  • Depolarization Ratio (dr), computed from correlation coefficient & differential reflectivity (additional)

  • clutter phase alignment (cpa) (additional)

Parameters
  • dat (dict) – dictionary of arrays. Contains the data of the decision variables. The shapes of the arrays should be (…, number of beams, number of gates) and the shapes need to be identical or be broadcastable.

  • weights (dict) – dictionary of floats. Defines the weights of the decision variables. Default is: zdr: 0.4, rho: 0.4, phi: 0.1, dop: 0.1, map: 0.5, rho2: 0.4, dr: 0.4, cpa: 0.4.

  • trpz (dict) – dictionary of lists of floats. Contains the arguments of the trapezoidal membership functions for each decision variable. Default is: zdr: [0.7, 1.0, 9999, 9999], rho: [0.1, 0.15, 9999, 9999], phi: [15, 20, 10000, 10000], dop: [-0.2, -0.1, 0.1, 0.2], map: [1, 1, 9999, 9999], rho2: [-9999, -9999, 0.95, 0.98], dr: [-20, -12, 9999, 9999], cpa: [0.6, 0.9, 9999, 9999].

Returns

  • prob (numpy.ndarray) – Array indicates probability of meteorological echos based on the fuzzy classification.

  • mask (numpy.ndarray) – Boolean array indicating where all the polarimetric moments had missing values which could be used as an additional information criterion.

Note

The boolean clutter mask (versions prior 2.0) can be calculated with the following code: np.where(prob < thresh, True, False).

wradlib.classify.msf_index_indep(msf, idp, obs)[source]#
wradlib.classify.msf_index_indep(msf: Dataset, obs)

Retrieve membership function values based on independent observable

Parameters
  • msf (numpy.ndarray) – Array of size (hmc-classes, observables, indep-ranges, 4) containing the values of the trapezoidal msf values for every hmc-class and observable within the independent observable range.

  • idp (numpy.ndarray) – Array of length of the independent observable containing the ranges of the independent observable.

  • obs (numpy.ndarray) – Array of arbitrary shape containing the data of the independent observable (e.g. (rays, bins) or (scan, rays, bins)).

Returns

out (numpy.ndarray) – Array of shape (hmc-classes, observables, obs.shape, 4) containing the membership function values for every radar-bin for every hmc-class and observable.

wradlib.classify.trapezoid(msf, obs)[source]#

Calculates membership of obs using trapezoidal membership functions

Parameters
  • msf (numpy.ndarray) – Array which is of size (obs.shape, 4), containing the trapezoidal membership function values for every obs point for one particular hydrometeor class.

  • obs (numpy.ndarray) – Array of arbitrary size and dimensions containing the data from which the membership shall be calculated.

Returns

out (numpy.ndarray) – Array which is of (obs.shape) containing calculated membership probabilities.

wradlib.classify.fuzzyfi(msf, obs)[source]#
wradlib.classify.fuzzyfi(msf: DataArray, hmc_ds, msf_obs_mapping)

Iterate over all hmc-classes and retrieve memberships

Parameters
  • msf (numpy.ndarray) – Array which is of size (hmc-class, obs.shape, 4), containing the trapezoidal membership function values for every obs point for every hydrometeor class.

  • obs (numpy.ndarray) – Array of arbitrary size and dimensions containing the data from which the memberships shall be calculated.

Returns

out (numpy.ndarray) – Array which is of (hmc-class, obs.shape) containing calculated membership probabilities.

wradlib.classify.probability(data, weights)[source]#
wradlib.classify.probability(data: DataArray, weights)

Calculate probability of hmc-class for every data bin.

Parameters
  • data (numpy.ndarray) – Array which is of size (hmc-class, obs, data.shape), containing the membership probability values.

  • weights (numpy.ndarray) – Array of length (observables) containing the weights for each observable.

Returns

out (numpy.ndarray) – Array which is of (hmc-class, data.shape) containing weighted hmc-membership probabilities.

wradlib.classify.classify(data, *, threshold=0.0)[source]#
wradlib.classify.classify(data: DataArray, threshold=0.0)

Calculate probability of hmc-class for every data bin.

Parameters
  • data (numpy.ndarray) – Array which is of size (hmc-class, data.shape), containing the weighted hmc-membership probability values.

  • threshold (float, optional) – Threshold value where probability is considered no precip, defaults to 0.

Returns

  • idx (numpy.ndarray) – Array which is of (data.shape) containing the (sorted) index into the hydrometeor-class. No precip is added on the top.

  • vals (numpy.ndarray) – Array which is of (data.shape) containing the (sorted) probability scores. No precip is added on the top.

class wradlib.classify.ClassifyMethods(obj)[source]#

Bases: XarrayMethods

wradlib xarray SubAccessor methods for Classify.

filter_gabella(**kwargs)[source]#

Clutter identification filter developed by [Gabella et al., 2002].

This is a two-part identification algorithm using echo continuity and minimum echo area to distinguish between meteorological (rain) and non- meteorological echos (ground clutter etc.)

Parameters

obj (xarray.DataArray)

Keyword Arguments
  • wsize (int) – Size of the window surrounding the central pixel

  • thrsnorain (float) –

  • tr1 (float) –

  • n_p (int) –

  • tr2 (float) –

  • rm_nans (bool) – True replaces nans with Inf False takes nans into acount

  • radial (bool) – True to use radial information only in filter_gabella_a.

  • cartesian (bool) – True if cartesian data are used, polar assumed if False.

Returns

output (xarray.DataArray) – boolean array with pixels identified as clutter set to True.

Examples

See Clutter detection using the Gabella approach.

filter_gabella_a(**kwargs)[source]#

First part of the Gabella filter looking for large reflectivity gradients.

This function checks for each pixel in img how many pixels surrounding it in a window of wsize are by tr1 smaller than the central pixel.

Parameters

obj (xarray.DataArray) – radar image to which the filter is to be applied

Keyword Arguments
  • wsize (int) – Size of the window surrounding the central pixel

  • tr1 (float) – Threshold value

  • cartesian (bool) – Specify if the input grid is Cartesian or polar

  • radial (bool) – Specify if only radial information should be used

Returns

out (xarray.DataArray) – an array with the same shape as img, containing the filter’s results.

Examples

See Clutter detection using the Gabella approach.

filter_gabella_b(**kwargs)[source]#

Second part of the Gabella filter comparing area to circumference of contiguous echo regions.

Parameters

obj (xarray.DataArray)

Keyword Arguments

thrs (float) – Threshold below which the field values will be considered as no rain

Returns

out (xarray.DataArray) – contains in each pixel the ratio between area and circumference of the meteorological echo it is assigned to or 0 for non precipitation pixels.

Examples

See Clutter detection using the Gabella approach.

histo_cut(**kwargs)[source]#

Histogram based clutter identification.

This identification algorithm uses the histogram of temporal accumulated rainfall. It iteratively detects classes whose frequency falls below a specified percentage (1% by default) of the frequency of the class with the biggest frequency and remove the values from the dataset until the changes from iteration to iteration falls below a threshold. This algorithm is able to detect static clutter as well as shadings.

The tresholds for the upper frequency (clutter) and the lower frequency (shading) can be parameterized by the respective kwargs, upper_frequency/lower_frequency.

It is suggested to choose a representative time periode for the input precipitation accumulation. The recommended time period should cover one year.

Parameters

obj (xarray.DataArray) – spatial array containing rain accumulation

Keyword Arguments
  • upper_frequency (float) – Upper frequency percentage for clutter detection, defaults to 0.01.

  • lower_frequency (float) – Lower frequency percentage for shading detection, defaults to 0.01.

Returns

output (xarray.DataArray) – uint8 array with pixels identified as clutter set to 1 and shadings set to 2. Remaining pixels set to 0. Users strictly relying on a boolean mask might have to explicitely cast to boolean (adding .astype(np.bool) on the return).

Examples

See Heuristic clutter detection based on distribution properties ("histo cut").

classify_echo_fuzzy(dat, **kwargs)[source]#

Fuzzy echo classification and clutter identification based on polarimetric moments.

The implementation is based on [Vulpiani et al., 2012]. At the moment, it only distinguishes between meteorological and non-meteorological echos.

For Clutter Phase Alignment (CPA) see [Hubbert et al., 2009a] and [Hubbert et al., 2009b]

For each decision variable and radar bin, the algorithm uses trapezoidal functions in order to define the membership to the non-meteorological echo class. Based on pre-defined weights, a linear combination of the different degrees of membership is computed. The echo is assumed to be non-meteorological in case the linear combination exceeds a threshold.

At the moment, the following decision variables are considered:
  • Texture of differential reflectivity (zdr) (mandatory)

  • Texture of correlation coefficient (rho) (mandatory)

  • Texture of differential propagation phase (phidp) (mandatory)

  • Doppler velocity (dop) (mandatory)

  • Static clutter map (map) (mandatory)

  • Correlation coefficient (rho2) (additional)

  • Depolarization Ratio (dr), computed from correlation coefficient & differential reflectivity (additional)

  • clutter phase alignment (cpa) (additional)

Parameters
Keyword Arguments
  • weights (dict) – dictionary of floats. Defines the weights of the decision variables. Default is: zdr: 0.4, rho: 0.4, phi: 0.1, dop: 0.1, map: 0.5, rho2: 0.4, dr: 0.4, cpa: 0.4.

  • trpz (dict) – dictionary of lists of floats. Contains the arguments of the trapezoidal membership functions for each decision variable. Default is: zdr: [0.7, 1.0, 9999, 9999], rho: [0.1, 0.15, 9999, 9999], phi: [15, 20, 10000, 10000], dop: [-0.2, -0.1, 0.1, 0.2], map: [1, 1, 9999, 9999], rho2: [-9999, -9999, 0.95, 0.98], dr: [-20, -12, 9999, 9999], cpa: [0.6, 0.9, 9999, 9999].

Returns

  • prob (xarray.DataArray) – DataArray indicating probability of meteorological echos based on the fuzzy classification.

  • mask (xarray.DataArray) – DataArray indicating where all the polarimetric moments had missing values which could be used as an additional information criterion.

filter_window_distance(**kwargs)[source]#

2d filter looking for large reflectivity gradients.

This function counts for each bin in img the percentage of surrounding bins in a window of half size fsize which are not tr1 smaller than the central bin. The window is defined using geometrical distance.

Parameters

obj (xarray.DataArray | xarray.Dataset) – 2d polar data to which the filter is to be applied

Keyword Arguments
  • fsize (int) – Half-size [m] of the square window surrounding the central pixel

  • tr1 (float) – Threshold value

Returns

output (xarray.DataArray | xarray.Dataset) – an array with the same shape as img, containing the filter’s results.

msf_index_indep(obs)[source]#
fuzzyfi(hmc_ds, msf_obs_mapping)[source]#
probability(weights)[source]#

Calculate probability of hmc-class for every data bin.

Parameters
  • data (xarray.Dataset) – Dataset containing the membership probability values.

  • weights (numpy.ndarray) – Array of length (observables) containing the weights for each observable.

Returns

out (xarray.DataArray) – Array containing weighted hmc-membership probabilities.

classify(threshold=0.0)[source]#

Calculate probability of hmc-class for every data bin.

Parameters

data (numpy.ndarray) – Array which is of size (hmc-class, data.shape), containing the weighted hmc-membership probability values.

Keyword Arguments

threshold (float) – Threshold value where probability is considered no precip, defaults to 0

Returns

out (xarray.DataArray) – DataArray containing probability scores. No precip is added on the top.