improver.convection module

Module containing convection diagnosis utilities.

class improver.convection.DiagnoseConvectivePrecipitation(lower_threshold, higher_threshold, neighbourhood_method, radii, fuzzy_factor=None, comparison_operator='>', lead_times=None, weighted_mode=True, use_adjacent_grid_square_differences=True)[source]

Bases: improver.BasePlugin

Diagnose convective precipitation by using differences between adjacent grid squares to help distinguish convective and stratiform precipitation. Convective precipitation features would be anticipated to have sharp features compared with broader (less sharp) features for stratiform precipitation.

__init__(lower_threshold, higher_threshold, neighbourhood_method, radii, fuzzy_factor=None, comparison_operator='>', lead_times=None, weighted_mode=True, use_adjacent_grid_square_differences=True)[source]
Parameters

  • lower_threshold (float) – The threshold point for ‘significant’ datapoints to define the lower threshold e.g. 0 mm/hr.

  • higher_threshold (float) – The threshold point for ‘significant’ datapoints to define the higher threshold e.g. 5 mm/hr.

  • neighbourhood_method (str) – Name of the neighbourhood method to use. Options: ‘circular’, ‘square’.

  • radii (float or list if defining lead times) – The radii in metres of the neighbourhood to apply. Rounded up to convert into integer number of grid points east and north, based on the characteristic spacing at the zero indices of the cube projection-x and y coords.

  • fuzzy_factor (float or None) – Percentage above or below threshold for fuzzy membership value. If None, no fuzzy_factor is applied.

  • comparison_operator (str) – Indicates the comparison_operator to use with the threshold. e.g. ‘ge’ or ‘>=’ to evaluate data >= threshold or ‘<’ to evaluate data < threshold. When using fuzzy_factor, there is no difference between < and <= or > and >=. Valid choices: > >= < <= gt ge lt le.

  • lead_times (list) – List of lead times or forecast periods, at which the radii within radii are defined. The lead times are expected in hours.

  • weighted_mode (bool) – If True, use a circle for neighbourhood kernel with weighting decreasing with radius. If False, use a circle with constant weighting.

  • use_adjacent_grid_square_differences (bool) – If True, use the differences between adjacent grid squares to diagnose convective precipitation. If False, use the raw field without calculating differences to diagnose convective precipitation.

_abc_cache = <_weakrefset.WeakSet object>
_abc_negative_cache = <_weakrefset.WeakSet object>
_abc_negative_cache_version = 213
_abc_registry = <_weakrefset.WeakSet object>
_calculate_convective_ratio(cubelist, threshold_list)[source]

Calculate the convective ratio by:

  1. Apply neighbourhood processing to cubes that have been thresholded using an upper and lower threshold.

  2. Calculate the convective ratio by: higher_threshold_cube / lower_threshold_cube. For example, the higher_threshold might be 5 mm/hr, whilst the lower_threshold might be 0.1 mm/hr.

The convective ratio can have the following values:

  • A non-zero fractional value, indicating that both the higher and lower thresholds were exceeded.

  • A zero value, if the lower threshold was exceeded, whilst the higher threshold was not exceeded.

  • A NaN value (np.nan), if neither the higher or lower thresholds were exceeded, such that the convective ratio was 0/0.

Parameters

  • cube (iris.cube.CubeList) – Cubelist containing cubes from which the convective ratio will be calculated. The cube should have been thresholded, so that values within cube.data are between 0.0 and 1.0.

  • threshold_list (list) – The list of thresholds.

Returns

Cube containing the convective ratio.

Return type

iris.cube.Cube

Raises

ValueError – If a value of infinity or a value greater than 1.0 are found within the convective ratio.

static absolute_differences_between_adjacent_grid_squares(cube)[source]

Compute the absolute differences between grid squares and put the resulting cubes into a cubelist.

Parameters

cube (iris.cube.Cube) – The cube from which adjacent grid square differences will be calculated.

Returns

Cubelist containing cubes with the absolute difference between adjacent grid squares along x and y, respectively.

Return type

iris.cube.CubeList

iterate_over_threshold(cubelist, threshold)[source]

Iterate over the application of thresholding to multiple cubes.

Parameters

  • cubelist (iris.cube.CubeList) – Cubelist containing cubes to be thresholded.

  • threshold (float) – The threshold that will be applied.

Returns

Cubelist after thresholding each cube.

Return type

iris.cube.CubeList

process(cube)[source]

Calculate the convective ratio either for the underlying field e.g. precipitation rate, or using the differences between adjacent grid squares.

If the difference between adjacent grid squares is used, firstly the absolute differences are calculated, and then the difference cubes are thresholded using a high and low threshold. The thresholded difference cubes are then summed in order to put these cubes back onto the grid of the original cube. The convective ratio is then calculated by applying neighbourhood processing to the resulting cubes by dividing the high threshold cube by the low threshold cube.

Parameters

cube (iris.cube.Cube) – The cube from which the convective ratio will be calculated.

Returns

Cube containing the convective ratio defined as the ratio between a cube with a high threshold applied and a cube with a low threshold applied.

Return type

iris.cube.Cube

static sum_differences_between_adjacent_grid_squares(cube, thresholded_cubes)[source]

Put the differences back onto the original grid by summing together the array with offsets. This covers the fact that the difference cubes will result in output on a staggered grid compared with the input cube.

Parameters

  • cube (iris.cube.Cube) – The cube with the original grid.

  • thresholded_cubes (iris.cube.CubeList) – Cubelist containing differences between adjacent grid squares along x and differences between adjacent grid squares along y, which have been thresholded.

Returns

Cube on the original grid with the values from the thresholded adjacent grid square difference cubes inserted. The resulting values have been restricted to be between 0 and 1.

Return type

iris.cube.Cube