Source code for improver.cli.recursive_filter

#!/usr/bin/env python
# (C) Crown Copyright, Met Office. All rights reserved.
#
# This file is part of 'IMPROVER' and is released under the BSD 3-Clause license.
# See LICENSE in the root of the repository for full licensing details.
"""Module to apply a recursive filter to neighbourhooded data."""

from improver import cli




@cli.clizefy
@cli.with_output
def process(
    cube: cli.inputcube,
    smoothing_coefficients: cli.inputcubelist,
    *,
    iterations: int = 1,
    variable_mask: bool = False,
    mask_zeros: bool = False,
):
    """Module to apply a recursive filter to neighbourhooded data.

    Run a recursive filter to convert a square neighbourhood into a
    Gaussian-like kernel or smooth over short distances. The filter uses a
    smoothing_coefficient (between 0 and 1) to control what proportion of the
    probability is passed onto the next grid-square in the x and y directions.

    Each iteration of the recursive filter applies the smoothing coefficients
    forwards and backwards in both the x and y directions. Applying 1-10
    iterations of the filter is typical. Each iteration further smooths the
    data, meaning the user must make a judgement regarding the number of
    iterations to apply that preserves real detail whilst removing artefacts
    in their data.

    The IMPROVER plugin actually limits the maximum smoothing coefficient to
    a value of 0.5. Above this the smoothing is considered to be too great.
    The smoothing_coefficient can be set on a grid square by grid-square basis
    for the x and y directions separately (using two arrays of
    smoothing_coefficients of the same dimensionality as the domain).

    Args:
        cube (iris.cube.Cube):
            Cube to be processed.
        smoothing_coefficients (iris.cube.CubeList):
            CubeList describing the smoothing_coefficients to be used in the x
            and y directions.
        iterations (int):
            Number of times to apply the filter.
        variable_mask (bool):
            Determines whether each spatial slice of the input cube can have a
            different mask. If False and cube is masked, a check will be made that
            the same mask is present on each spatial slice. If True, each spatial
            slice of cube may contain a different spatial mask.
        mask_zeros (bool):
            If set true all of the values of 0 in the cube will be masked,
            stopping the recursive filter from spreading values into these areas.
            They will then be unmasked later on. If the input cube was masked
            this mask will be reapplied to the output at the end.

    Returns:
        iris.cube.Cube:
            The processed Cube.
    """
    from improver.nbhood.recursive_filter import RecursiveFilter

    plugin = RecursiveFilter(iterations=iterations)
    return plugin(
        cube,
        smoothing_coefficients=smoothing_coefficients,
        variable_mask=variable_mask,
        mask_zeros=mask_zeros,
    )