improver.nbhood.circular_kernel module¶

This module contains methods for circular neighbourhood processing.

class improver.nbhood.circular_kernel.CircularNeighbourhood(weighted_mode=True, sum_or_fraction='fraction', re_mask=False)[source]¶

Bases: object

Methods for use in the calculation and application of a circular neighbourhood. A maximum kernel radius of 500 grid cells is imposed in order to avoid computational ineffiency and possible memory errors.

__init__(weighted_mode=True, sum_or_fraction='fraction', re_mask=False)[source]¶

Initialise class.

Parameters

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

apply_circular_kernel(cube, ranges)[source]¶

Method to apply a circular kernel to the data within the input cube in order to smooth the resulting field.

Parameters

cube (iris.cube.Cube) – Cube containing to array to apply CircularNeighbourhood processing to.
ranges (tuple) – Number of grid cells in the x and y direction used to create the kernel.

Returns

Cube containing the smoothed field after the kernel has been applied.

Return type

iris.cube.Cube

run(cube, radius, mask_cube=None)[source]¶

Call the methods required to calculate and apply a circular neighbourhood.

Parameters

cube (iris.cube.Cube) – Cube containing to array to apply CircularNeighbourhood processing to.
radius (float) – Radius in metres for use in specifying the number of grid cells used to create a circular neighbourhood.
mask_cube (iris.cube.Cube or None) – Cube containing the array to be used as a mask.

Returns

Cube containing the smoothed field after the kernel has been applied.

Return type

iris.cube.Cube

class improver.nbhood.circular_kernel.GeneratePercentilesFromACircularNeighbourhood(percentiles=(0, 5, 10, 20, 25, 30, 40, 50, 60, 70, 75, 80, 90, 95, 100))[source]¶

Bases: object

Methods for use in calculating percentiles from a 2D circular neighbourhood. A maximum kernel radius of 500 grid cells is imposed in order to avoid computational ineffiency and possible memory errors.

__init__(percentiles=(0, 5, 10, 20, 25, 30, 40, 50, 60, 70, 75, 80, 90, 95, 100))[source]¶

Initialise class.

Parameters: percentiles (list or float) – Percentile values at which to calculate; if not provided uses DEFAULT_PERCENTILES.

make_percentile_cube(cube)[source]¶

Returns a cube with the same metadata as the sample cube but with an added percentile dimension.

Parameters: cube (iris.cube.Cube) – Cube to copy meta data from.
Returns: Cube like input but with added percentiles coordinate. Each slice along this coordinate is identical.
Return type: iris.cube.Cube

pad_and_unpad_cube(slice_2d, kernel)[source]¶

Method to pad and unpad a two dimensional cube. The input array is padded and percentiles are calculated using a neighbourhood around each point. The resulting percentile data are unpadded and put into a cube.

Parameters

slice_2d (iris.cube.Cube) – 2d cube to be padded with a halo.
kernel (numpy.ndarray) – Kernel used to specify the neighbourhood to consider when calculating the percentiles within a neighbourhood.

Examples

Take the input slice_2d cube with the data, where 1 is an occurrence and 0 is an non-occurrence:
```
[[1., 1., 1.,],
 [1., 0., 1.],
 [1., 1., 1.]]
```
Define a kernel. This kernel is effectively placed over each point within the input data. Note that the input data is padded prior to placing the kernel over each point, so that the kernel does not exceed the bounds of the padded data:
```
[[ 0.,  0.,  1.,  0.,  0.],
 [ 0.,  1.,  1.,  1.,  0.],
 [ 1.,  1.,  1.,  1.,  1.],
 [ 0.,  1.,  1.,  1.,  0.],
 [ 0.,  0.,  1.,  0.,  0.]]
```

Pad the input data. The extent of the padding is given by the shape of the kernel. The number of values included within the calculation of the mean is determined by the size of the kernel:

[[ 0.75,  0.75,  1.  ,  0.5 ,  1.  ,  0.75,  0.75],
 [ 0.75,  0.75,  1.  ,  0.5 ,  1.  ,  0.75,  0.75],
 [ 1.  ,  1.  ,  1.  ,  1.  ,  1.  ,  1.  ,  1.  ],
 [ 0.5 ,  0.5 ,  1.  ,  0.  ,  1.  ,  0.5 ,  0.5 ],
 [ 1.  ,  1.  ,  1.  ,  1.  ,  1.  ,  1.  ,  1.  ],
 [ 0.75,  0.75,  1.  ,  0.5 ,  1.  ,  0.75,  0.75],
 [ 0.75,  0.75,  1.  ,  0.5 ,  1.  ,  0.75,  0.75]]

Calculate the values at the percentiles: [10]. For the point in the upper right corner within the original input data e.g.

[[->1.<-, 1., 1.,],
 [  1.,   0., 1.],
 [  1.,   1., 1.]]

When the kernel is placed over this point within the padded data, then the following points are included:

[[   0.75,    0.75,  ->1.<-,  0.5 ,  1.  ,  0.75,  0.75],
 [   0.75,  ->0.75,    1.  ,  0.5<-, 1.  ,  0.75,  0.75],
 [ ->1.  ,    1.  ,    1.  ,  1.  ,  1.<-,  1.  ,  1.  ],
 [   0.5 ,  ->0.5 ,    1.  ,  0.<-,  1.  ,  0.5 ,  0.5 ],
 [   1.  ,    1.  ,  ->1.<-,  1.  ,  1.  ,  1.  ,  1.  ],
 [   0.75,    0.75,    1.  ,  0.5 ,  1.  ,  0.75,  0.75],
 [   0.75,    0.75,    1.  ,  0.5 ,  1.  ,  0.75,  0.75]]

This gives:

[0, 0.5, 0.5, 0.75, 1., 1., 1., 1., 1., 1., 1., 1., 1.]

As there are 13 points within the kernel, this gives the following relationship between percentiles and values.

Values

Percentile

0

0.5

8.33

0.5

16.67

0.75

25.0

33.33

41.67

50.0

58.33

66.67

75.0

83.33

91.66

Therefore, for the 10th percentile at the value returned for the point in the upper right corner of the original input data is 0.5. When this process is applied to every point within the original input data, the result is:

[[[ 0.75,  0.75,  0.5 ,  0.5 ,  0.5 ,  0.75,  0.75],
  [ 0.75,  0.55,  0.55,  0.5 ,  0.55,  0.55,  0.55],
  [ 0.55,  0.55,  0.5 ,  0.5 ,  0.5 ,  0.5 ,  0.5 ],
  [ 0.5 ,  0.5 ,  0.5 ,  0.5 ,  0.5 ,  0.5 ,  0.5 ],
  [ 0.5 ,  0.5 ,  0.5 ,  0.5 ,  0.5 ,  0.55,  0.55],
  [ 0.55,  0.55,  0.55,  0.5 ,  0.55,  0.55,  0.75],
  [ 0.75,  0.75,  0.5 ,  0.5 ,  0.5 ,  0.75,  0.75]]],

The padding is then removed to give:

[[[ 0.5,  0.5,  0.5],
  [ 0.5,  0.5,  0.5],
  [ 0.5,  0.5,  0.5]]]

run(cube, radius, mask_cube=None)[source]¶

Method to apply a circular kernel to the data within the input cube in order to derive percentiles over the kernel.

Parameters

cube (iris.cube.Cube) – Cube containing array to apply processing to.
radius (float) – Radius in metres for use in specifying the number of grid cells used to create a circular neighbourhood.
mask_cube (iris.cube.Cube or None) – Cube containing the array to be used as a mask.

Returns

Cube containing the percentile fields. Has percentile as an added dimension.

Return type

iris.cube.Cube

improver.nbhood.circular_kernel.circular_kernel(fullranges, ranges, weighted_mode)[source]¶

Method to create a circular kernel.

Parameters

fullranges (numpy.ndarray) – Number of grid cells in all dimensions used to create the kernel. This should have the value 0 for any dimension other than x and y.
ranges (tuple) – Number of grid cells in the x and y direction used to create the kernel.
weighted_mode (bool) – If True, use a circle for neighbourhood kernel with weighting decreasing with radius. If False, use a circle with constant weighting.

Returns

Array containing the circular smoothing kernel. This will have the same number of dimensions as fullranges.

Return type

numpy.ndarray