improver.nbhood.square_kernel module

This module contains methods for square neighbourhood processing.

class improver.nbhood.square_kernel.SquareNeighbourhood(weighted_mode=True, sum_or_fraction='fraction', re_mask=True)[source]

Bases: object

Methods for use in application of a square neighbourhood.

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

Initialise class.

Parameters

  • weighted_mode (bool) – This is included to allow a standard interface for both the square and circular neighbourhood plugins.

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

_pad_and_calculate_neighbourhood(cube, mask, grid_cells_x, grid_cells_y)[source]

Apply neighbourhood processing consisting of the following steps:

  1. Pad a halo around the input cube to allow vectorised neighbourhooding at edgepoints.

  2. Cumulate the array along the x and y axes.

  3. Apply neighbourhood processing to the cumulated array.

Parameters

  • cube (iris.cube.Cube) – Cube with masked or NaN values set to 0.0

  • mask (iris.cube.Cube) – Cube with masked or NaN values set to 0.0

  • grid_cells_x (float) – The number of grid cells along the x axis used to create a square neighbourhood.

  • grid_cells_y (float) – The number of grid cells along the y axis used to create a square neighbourhood.

Returns

Cube containing the smoothed field after the square neighbourhood method has been applied with halo added.

Return type

iris.cube.Cube

_remove_padding_and_mask(neighbourhood_averaged_cube, original_cube, mask, grid_cells_x, grid_cells_y)[source]

Remove the halo from the padded array and apply the mask, if required. If fraction option set, clip the data so values lie within the range of the original cube.

Parameters

  • neighbourhood_averaged_cube (iris.cube.Cube) – Cube containing the smoothed field after the square neighbourhood method has been applied.

  • original_cube (iris.cube.Cube or None) – The original cube slice.

  • mask (iris.cube.Cube) – The mask cube created by set_up_cubes_to_be_neighbourhooded.

  • grid_cells_x (float) – The number of grid cells along the x axis used to create a square neighbourhood.

  • grid_cells_y (float) – The number of grid cells along the y axis used to create a square neighbourhood.

Returns

Cube containing the smoothed field after the square neighbourhood method has been applied and halo removed.

Return type

iris.cube.Cube

static calculate_neighbourhood(summed_cube, ymax_xmax_disp, ymin_xmax_disp, ymin_xmin_disp, ymax_xmin_disp, n_rows, n_columns)[source]

Fast vectorised approach to calculating neighbourhood totals.

Displacements are calculated as follows for the following input array, where the accumulation has occurred from top to bottom and left to right:

| 1 | 2 | 2 | 2 |
| 1 | 3 | 4 | 4 |
| 2 | 4 | 5 | 6 |
| 2 | 4 | 6 | 7 |

For a 3x3 neighbourhood centred around the point with a value of 5:

| 1 (C) | 2 | 2                 | 2 (D) |
| 1     | 3 | 4                 | 4     |
| 2     | 4 | 5 (Central point) | 6     |
| 2 (A) | 4 | 6                 | 7 (B) |

To calculate the value for the neighbourhood sum at the “Central point” with a value of 5, calculate:

Neighbourhood sum = B - A - D + C

At the central point, this will yield:

Neighbourhood sum = 7 - 2 - 2 +1 => 4
Parameters

  • summed_cube (iris.cube.Cube) – cube on which to calculate the neighbourhood total.

  • ymax_xmax_disp (int) – Displacement from the point at the centre of the neighbourhood. Equivalent to point B in the docstring example.

  • ymax_xmin_disp (int) – Displacement from the point at the centre of the neighbourhood. Equivalent to point A in the docstring example.

  • ymin_xmax_disp (int) – Displacement from the point at the centre of the neighbourhood. Equivalent to point D in the docstring example.

  • ymin_xmin_disp (int) – Displacement from the point at the centre of the neighbourhood. Equivalent to point C in the docstring example.

  • n_rows (int) – Number of rows

  • n_columns (int) – Number of columns

Returns

Array containing the calculated neighbourhood total.

Return type

numpy.ndarray

static cumulate_array(cube, iscomplex=False)[source]

Method to calculate the cumulative sum of an m x n array, by first cumulating along the y direction so that the largest values are in the nth row, and then cumulating along the x direction, so that the largest values are in the mth column. Each grid point will contain the cumulative sum from the origin to that grid point.

Parameters

  • cube (iris.cube.Cube) – Cube to which the cumulative summing along the y and x direction will be applied. The cube should contain only x and y dimensions, so will generally be a slice of a cube ordered so that y is first in the cube (i.e. axis=0).

  • iscomplex (bool) – Flag indicating whether cube.data contains complex values.

Returns

Cube to which the cumulative summing along the y and x direction has been applied.

Return type

iris.cube.Cube

mean_over_neighbourhood(summed_cube, summed_mask, cells_x, cells_y, iscomplex=False)[source]

Method to calculate the average value in a square neighbourhood using the 4-point algorithm to find the total sum over the neighbourhood.

The output from the cumulate_array method can be used to calculate the sum over a neighbourhood of size (2*cells_x+1)*(2*cells_y+1). This sum is then divided by the area of the neighbourhood to calculate the mean value in the neighbourhood.

For all points, a fast vectorised approach is taken:

  1. The displacements between the four points used to calculate the neighbourhood total sum and the central grid point are calculated.

  2. Within the function calculate_neighbourhood… Four copies of the cumulate array output are flattened and rolled by these displacements to align the four terms used in the neighbourhood total sum calculation.

  3. The neighbourhood total at all points can then be calculated simultaneously in a single vector sum.

Neighbourhood mean = Neighbourhood sum / Neighbourhood area

Neighbourhood area = (2 * nb_width +1)^2 if there are no missing points, nb_width is the neighbourhood width, which is equal to 1 for a 3x3 neighbourhood.

Parameters

  • summed_cube (iris.cube.Cube) – Summed Cube to which neighbourhood processing is being applied. Must be passed through cumulate_array method first. The cube should contain only x and y dimensions, so will generally be a slice of a cube.

  • summed_mask (iris.cube.Cube) – Summed Mask used to calculate neighbourhood size. Must be passed through cumulate_array method first. The cube should contain only x and y dimensions, so will generally be a slice of a cube.

  • cells_x (int) – The radius of the neighbourhood in grid points, in the x direction (excluding the central grid point).

  • cells_y (int) – The radius of the neighbourhood in grid points, in the y direction (excluding the central grid point).

  • iscomplex (bool) – Flag indicating whether cube.data contains complex values.

Returns

Cube to which square neighbourhood has been applied.

Return type

iris.cube.Cube

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

Call the methods required to apply a square neighbourhood method to a cube.

The steps undertaken are:

  1. Set up cubes by determining, if the arrays are masked.

  2. Pad the input array with a halo and then calculate the neighbourhood of the haloed array.

  3. Remove the halo from the neighbourhooded array and deal with a mask, if required.

Parameters

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

  • radius (float) – Radius in metres for use in specifying the number of grid cells used to create a square neighbourhood.

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

Return type

iris.cube.Cube

static set_up_cubes_to_be_neighbourhooded(cube, mask_cube=None)[source]

Set up a cube ready for neighourhooding the data.

Parameters

  • cube (iris.cube.Cube) – Cube that will be checked for whether the data is masked or nan. The cube should contain only x and y dimensions, so will generally be a slice of a cube.

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

Returns

tuple containing:
cube (iris.cube.Cube):

Cube with masked or NaN values set to 0.0

mask (iris.cube.Cube):

Cube with masked or NaN values set to 0.0

nan_array (numpy.ndarray):

numpy array to be used to set the values within the data of the output cube to be NaN.

Return type

(tuple)