improver.nbhood.use_nbhood module
Utilities for using neighbourhood processing.
- class ApplyNeighbourhoodProcessingWithAMask(coord_for_masking, neighbourhood_method, radii, lead_times=None, collapse_weights=None, weighted_mode=False, sum_only=False)[source]
Bases:
PostProcessingPluginClass 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.
However, if weights are provided then you can weight between adjacent bands when you collapse the new “topographic_zone” coordinate. This takes into account the result from the neighbourhood processing to adjust the weights for points in a “topographic_zone” that don’t have a valid result.
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 these weights:
GenerateTopographicZoneWeightsA B .......................... band 2 ..................x....... x band 1 ..........................
We may need to 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, which happens automatically within the numpy functions called within the iris collapse method.
After collapsing the “topographic_zone” coordinate 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.
See also
GenerateOrographyBandAncilsfor a plugin for generating topographic band masks.- __init__(coord_for_masking, neighbourhood_method, radii, lead_times=None, collapse_weights=None, weighted_mode=False, sum_only=False)[source]
Initialise the class.
- Parameters:
coord_for_masking (
str) – String matching the name of the coordinate that will be used for masking.neighbourhood_method (
str) – Name of the neighbourhood method to use. Options: ‘circular’, ‘square’.radii (
Union[float,List[float]]) – 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.collapse_weights (
Optional[Cube]) – A cube from an ancillary file containing the weights for each point in the ‘coord_for_masking’ at each grid point. If given, the coord_for_masking coordinate will be collapsed using these weights resulting in an output cube with the same dimensions as the input cube. Otherwise the output cube will have the coord_for_masking from the supplied mask_cube as an additional dimension. The data in this cube may be an instance of numpy.ma.masked_array, for example if sea points have been set to np.nan and masked in order for them to be discounted when calculating the result. In this case the result returned from the process method of this plugin will have the same points masked.lead_times (
Optional[List[float]]) – 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_only (
bool) – If true, return neighbourhood sum instead of mean.
- _abc_impl = <_abc_data object>
- collapse_mask_coord(cube)[source]
Collapse the chosen coordinate 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.
- process(cube, mask_cube)[source]
Apply neighbourhood processing with a mask to the input cube, collapsing the coord_for_masking if collapse_weights have been provided.
- Parameters:
cube (
Cube) – Cube containing the array to which the square neighbourhood will be applied.mask_cube (
Cube) – Cube containing the array to be used as a mask. The data in this array is not an instance of numpy.ma.MaskedArray. Any sea points that should be ignored are set to zeros in every layer of the mask_cube.
- Return type:
- 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.