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: object

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.

Keyword Arguments:
 
  • 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 (integer or None) – The number of iterations of the recursive filter.
  • edge_width (integer) – Half the width of the padding halo applied before recursive filtering.
  • re_mask (boolean) – 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 < 1
  • ValueError – If alpha_y is not set such that 0 < alpha_y < 1
  • ValueError – If number of iterations is not None and is set such that iterations is not >= 1
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 array) – 2D array containing the input data to which the recursive filter will be applied.
  • alphas (numpy array) – Matching 2D array of alpha values that will be used when applying the recursive filter along the specified axis.
  • axis (integer) – 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:

grid (numpy array)
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 array) – 2D array containing the input data to which the recursive filter will be applied.
  • alphas (numpy array) – Matching 2D array of alpha values that will be used when applying the recursive filter along the specified axis.
  • axis (integer) – 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:

grid (numpy array)
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 (integer) – 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:

cube (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:

alphas_cube (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.
Keyword Arguments:
 
  • 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:

new_cube (Iris.cube.Cube)