improver.nbhood.use_nbhood module

Utilities for using neighbourhood processing.

class improver.nbhood.use_nbhood.ApplyNeighbourhoodProcessingWithAMask(coord_for_masking, radii, lead_times=None, weighted_mode=True, sum_or_fraction='fraction', re_mask=False)[source]

Bases: improver.BasePlugin

Class for applying neighbourhood processing when passing in a mask cube that is iterated over.

Example

This plugin is designed to work with a set of masks which help you select points which are similar and only use these in your neighbourhood. The most obvious example of this is to divide the points in your cube into bands of similar orographic height.

..............................
Band 2        ---
............./...\.../\.......
Band 1      /     ---  \
.........../............\.....
Band 0    /              --
........--.................\..

In this case the mask cube that comes in has a “topographic_zone” coordinate and each slice along this dimension has a 2D mask, masking out any points which are outside the topographic band that is described by the “topographic_zone” coordinate.

The result from this plugin is a cube which has applied neighbourhooding to the plugin n times for the n bands in the mask cube. Each topography mask has been applied to the input cube in turn, resulting in a cube with a “topographic_zone” coordinate which is returned from this plugin.

There is an option to remask the output from the plugin, but if the result is left unmasked then the you can weight between adjacent bands when you collapse the new “topographic_zone” coordinate. See CollapseMaskedNeighbourhoodCoordinate for a plugin to collapse the new dimension on the output cube. See also GenerateOrographyBandAncils for a plugin for generating topographic band masks.

__init__(coord_for_masking, radii, lead_times=None, weighted_mode=True, sum_or_fraction='fraction', re_mask=False)[source]

Initialise the class.

Parameters

  • coord_for_masking (str) – String matching the name of the coordinate that will be used for masking.

  • 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.

  • 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.

  • sum_or_fraction (str) – Identifier for whether sum or fraction should be returned from neighbourhooding. The sum represents the sum of the neighbourhood. The fraction represents the sum of the neighbourhood divided by the neighbourhood area. “fraction” is the default. Valid options are “sum” or “fraction”.

  • re_mask (bool) – If re_mask is True, the original un-neighbourhood processed mask is applied to mask out the neighbourhood processed cube. If re_mask is False, the original un-neighbourhood processed mask is not applied. Therefore, the neighbourhood processing may result in values being present in areas that were originally masked.

_abc_cache = <_weakrefset.WeakSet object>
_abc_negative_cache = <_weakrefset.WeakSet object>
_abc_negative_cache_version = 213
_abc_registry = <_weakrefset.WeakSet object>
process(cube, mask_cube)[source]

  1. Iterate over the chosen coordinate within the mask_cube and apply the mask at each iteration to the cube that is to be neighbourhood processed.

  2. Concatenate the cubes from each iteration together to create a single cube.

Parameters

  • cube (iris.cube.Cube) – Cube containing the array to which the square neighbourhood will be applied.

  • mask_cube (iris.cube.Cube) – Cube containing the array to be used as a mask.

Returns

Cube containing the smoothed field after the square neighbourhood method has been applied when applying masking for each point along the coord_for_masking coordinate. The resulting cube is concatenated so that the dimension coordinates match the input cube.

Return type

iris.cube.Cube

class improver.nbhood.use_nbhood.CollapseMaskedNeighbourhoodCoordinate(coord_masked, weights)[source]

Bases: improver.BasePlugin

Plugin for collapsing the coordinate the mask was applied to after masked neighbourhood processing.

Takes into account the result from the neighbourhood processing to adjust the weights between the bands in the coordinate for the points where the were no points within a neighbourhood for and a non-zero weighting.

Example

This plugin is designed to work with ApplyNeighbourhoodProcessingWithAMask which adds a dimension to the resulting cube based on the masks that are applied. This most obvious example of these masks are topographic bands which separate the points in the field to be neighbourhooded into bands with points of similar orographic height.

..............................
Band 3
..............................
Band 2        ---
............./...\.../\.......
Band 1      /     ---  \
.........../............\.....
Band 0    /              --
........--.................\..

The cube that is input into this plugin has had neighbourhooding applied n times for the n bands. We now want to collapse this new “topographic_zone” coordinate by weighting between adjacent bands.

For example below we have two points A and B. Say point A was halfway between the midpoint and top of the lower band. We would want to generate a final result by weighting 0.75 times to neighbourhooded value from the bottom band and 0.25 times the neighbourhooded value in the upper band. For point B we would take equal weightings between the bands. There is a plugin to generate weights here: GenerateTopographicZoneWeights

            A             B
        ..........................
band 2

        ..................x.......
            x
band 1
        ..........................

We may need adjust the weights if there is missing data in the adjacent band. If we look at the diagram with labelled bands, points that are near the top of band 2 could be weighted with band 3, except there are no nearby points in band 3. In this case the neighbourhood code puts NaNs in band 3 and we want to take 100% of band 2. This can be easily done by renormalization of the weights.

Once we have valid weights for adjacent bands for each point we can collapse the “topographic_zone” coordinate using a weighted mean.

When this plugin is used alongside ApplyNeighbourhoodProcessingWithAMask we end up with a cube with the same dimensions as the original cube, but the neighbourhood processing has been applied using masks so that only similar points are used in the neighbourhood.

__init__(coord_masked, weights)[source]

Initialise the class.

Parameters

  • coord_masked (str) – String matching the name of the coordinate that has been used for masking.

  • weights (iris.cube.Cube) – A cube from an ancillary file containing the weights for each point in the coord_masked at each grid point. Only two points in coord_masked can have a non-zero weight for each grid-point, i.e. we are only weighting between two adjacent bands in the neighbourhood output for each gridpoint. Should have the coordinates coord_masked, x and y. The weights cube can be masked, and this mask will be retained, and will be present in the output.

_abc_cache = <_weakrefset.WeakSet object>
_abc_negative_cache = <_weakrefset.WeakSet object>
_abc_negative_cache_version = 213
_abc_registry = <_weakrefset.WeakSet object>
process(cube)[source]

Collapse the chosen coordinates with the available weights. The result of the neighbourhood processing is taken into account to renormalize any weights corresponding to a NaN in the result from neighbourhooding. In this case the weights are re-normalized so that we do not lose probability.

Parameters

cube (iris.cube.Cube) – Cube containing the array to which the square neighbourhood with a mask has been applied.

Returns

Cube containing the weighted mean from neighbourhood after collapsing the chosen coordinate.

Return type

iris.cube.Cube

remove_collapsed_coord_refs(result_cube)[source]

Remove references to the collapsed coordinate after processing.

Removes the collapsed coordinate and the cell method relating to it on the provided cube, in place.

Parameters

result_cube (iris.cube.Cube) – The collapsed cube whose metadata we want to change.

renormalize_weights(nbhood_cube)[source]

Renormalize the weights taking into account where there are NaNs in the result from neighbourhood.

The weights corresponding to NaNs in the result from neighbourhooding with a mask are set to zero and then the weights are renormalized along the axis corresponding to the coordinate we want to collapse.

Parameters

nbhood_cube (iris.cube.Cube) – The cube that has been through masked neighbourhood processing and has the dimension we wish to collapse. Must have the same dimensions of the cube.