improver.nbhood.recursive_filter module

Module to apply a recursive filter to neighbourhooded data.

class improver.nbhood.recursive_filter.RecursiveFilter(alpha_x=None, alpha_y=None, iterations=None, edge_width=1, re_mask=False)[source]

Bases: improver.BasePlugin

Apply a recursive filter to the input cube.

__init__(alpha_x=None, alpha_y=None, iterations=None, edge_width=1, re_mask=False)[source]

Initialise the class.

The alpha values determine how much “value” of a cell undergoing filtering is comprised of the current value at that cell and how much comes from the adjacent cell preceding it in the direction in which filtering is being applied.

Parameters

  • alpha_x (float or None) – Filter parameter: A constant used to weight the recursive filter along the x-axis. Defined such that 0 < alpha_x < 1.0

  • alpha_y (float or None) – Filter parameter: A constant used to weight the recursive filter along the y-axis. Defined such that 0 < alpha_y < 1.0

  • iterations (int or None) – The number of iterations of the recursive filter.

  • edge_width (int) – Half the width of the padding halo applied before recursive filtering.

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

Raises

  • ValueError – If alpha_x is not set such that 0 < alpha_x <= 0.5

  • ValueError – If alpha_y is not set such that 0 < alpha_y <= 0.5

  • ValueError – If number of iterations is not None and is set such that iterations is less than 1.

Warns

UserWarning – If iterations is higher than 2.

_abc_cache = <_weakrefset.WeakSet object>
_abc_negative_cache = <_weakrefset.WeakSet object>
_abc_negative_cache_version = 213
_abc_registry = <_weakrefset.WeakSet object>
static _recurse_backward(grid, alphas, axis)[source]

Method to run the recursive filter in the backwards direction.

In the backwards direction:
Recursive filtering is calculated as:

Bi = ((1-alpha) * Ai) + (alpha * Bi+1)

Progressing from gridpoint i+1 to i:.

Bi = new value at gridpoint i, Ai = Old value at gridpoint i Bi+1 = New value at gridpoint i+1

Parameters

  • grid (numpy.ndarray) – 2D array containing the input data to which the recursive filter will be applied.

  • alphas (numpy.ndarray) – Matching 2D array of alpha values that will be used when applying the recursive filter along the specified axis.

  • axis (int) – Index of the spatial axis (0 or 1) over which to recurse.

Returns

2D array containing the smoothed field after the recursive filter method has been applied to the input array in the backwards direction along the specified axis.

Return type

numpy.ndarray

static _recurse_forward(grid, alphas, axis)[source]

Method to run the recursive filter in the forward direction.

In the forward direction:
Recursive filtering is calculated as:

Bi = ((1-alpha) * Ai) + (alpha * Bi-1)

Progressing from gridpoint i-1 to i:

Bi = new value at gridpoint i, Ai = Old value at gridpoint i Bi-1 = New value at gridpoint i-1

Parameters

  • grid (numpy.ndarray) – 2D array containing the input data to which the recursive filter will be applied.

  • alphas (numpy.ndarray) – Matching 2D array of alpha values that will be used when applying the recursive filter along the specified axis.

  • axis (int) – Index of the spatial axis (0 or 1) over which to recurse.

Returns

2D array containing the smoothed field after the recursive filter method has been applied to the input array in the forward direction along the specified axis.

Return type

numpy.ndarray

static _run_recursion(cube, alphas_x, alphas_y, iterations)[source]

Method to run the recursive filter.

Parameters

  • cube (iris.cube.Cube) – 2D cube containing the input data to which the recursive filter will be applied.

  • alphas_x (iris.cube.Cube) – 2D cube containing array of alpha values that will be used when applying the recursive filter along the x-axis.

  • alphas_y (iris.cube.Cube) – 2D cube containing array of alpha values that will be used when applying the recursive filter along the y-axis.

  • iterations (int) – The number of iterations of the recursive filter

Returns

Cube containing the smoothed field after the recursive filter method has been applied to the input cube.

Return type

iris.cube.Cube

_set_alphas(cube, alpha, alphas_cube)[source]

Set up the alpha parameter.

Parameters

  • cube (iris.cube.Cube) – 2D cube containing the input data to which the recursive filter will be applied.

  • alpha (float) – The constant used to weight the recursive filter in that direction: Defined such that 0.0 < alpha < 1.0

  • alphas_cube (iris.cube.Cube or None) – Cube containing array of alpha values that will be used when applying the recursive filter in a specific direction.

Raises

  • ValueError – If both alphas_cube and alpha are provided.

  • ValueError – If alpha and alphas_cube are both set to None

  • ValueError – If dimension of alphas array is less than dimension of data array

  • ValueError – If dimension of alphas array is greater than dimension of data array

Returns

Cube containing a padded array of alpha values for the specified direction.

Return type

iris.cube.Cube

process(cube, alphas_x=None, alphas_y=None, mask_cube=None)[source]

Set up the alpha parameters and run the recursive filter.

The steps undertaken are:

  1. Split the input cube into slices determined by the co-ordinates in the x and y directions.

  2. Construct an array of filter parameters (alphas_x and alphas_y) for each cube slice that are used to weight the recursive filter in the x- and y-directions.

  3. Pad each cube slice with a square-neighbourhood halo and apply the recursive filter for the required number of iterations.

  4. Remove the halo from the cube slice and append the recursed cube slice to a ‘recursed cube’.

  5. Merge all the cube slices in the ‘recursed cube’ into a ‘new cube’.

  6. Modify the ‘new cube’ so that its scalar dimension co-ordinates are consistent with those in the original input cube.

  7. Return the ‘new cube’ which now contains the recursively filtered values for the original input cube.

Parameters

  • cube (iris.cube.Cube) – Cube containing the input data to which the recursive filter will be applied.

  • alphas_x (iris.cube.Cube or None) – Cube containing array of alpha values that will be used when applying the recursive filter along the x-axis.

  • alphas_y (iris.cube.Cube or None) – Cube containing array of alpha values that will be used when applying the recursive filter along the y-axis.

  • mask_cube (iris.cube.Cube or None) – Cube containing an external mask to apply to the cube before applying the recursive filter.

Returns

Cube containing the smoothed field after the recursive filter method has been applied.

Return type

iris.cube.Cube

Raises

ValueError – If any alpha cube value is over 0.5