improver.cli.vicinity module#
Script to apply vicinity neighbourhoods to data.
- process(cube, land_mask=None, *, vicinity=None, operator='max', new_name=None)[source]#
Module to apply vicinity processing to data.
Calculate the operator value within a vicinity radius about each point in each x-y slice of the input cube, with default being the maximum.
If working with thresholded data, using this CLI to calculate a neighbourhood maximum ensemble probability, the vicinity process must be applied prior to averaging across the ensemble, i.e. collapsing the realization coordinate. A typical chain might look like:
threshold –> vicinity –> realization collapse
Note that the threshold CLI can be used to perform this series of steps in a single call without intermediate output.
Users should ensure they do not inadvertently apply vicinity processing twice, once within the threshold CLI and then again using this CLI.
As a further note, when applying the mean operator to thresholded data, the vicinity CLI will produce output equivalent to the nhbood CLI (disregarding the boundary), but less efficiently (particularly when applied to masked or datasets containing NaNs). For such cases, it is recommended that one use the nbhood CLI instead.
- Parameters:
cube (iris.cube.Cube) – A cube containing data to which a vicinity is to be applied.
land_mask (iris.cube.Cube) – Binary land-sea mask data. True for land-points, False for sea. Restricts in-vicinity processing to only include points of a like mask value.
vicinity (list of float / int) – List of distances in metres used to define the vicinities within which to search for an occurrence. Each vicinity provided will lead to a different gridded field.
operator (str) – Operation to apply over vicinity. Options are one of: [“max”, “mean”, “min”, “std”] with “max” being the default.
new_name (str) – Name to assign to the resultant cube after calculating the vicinity values for the specified operator. Where no value is provided, the cube will retain the same name as the input cube.
- Returns:
Cube with the vicinity processed data.
- Return type: