improver.utilities.spatial module

Provides support utilities.

class BaseDistanceCalculator(cube)

Bases: ABC

Base class for distance calculators for cubes with different coordinate systems/axis types

__init__(cube)

Parameters:

cube (Cube) – Cube for which the distances will be calculated.

_abc_impl = <_abc._abc_data object>

abstractmethod _get_x_distances()

Abstract method for calculating distances along the x axis of the input cube. The resulting cube shall have two dimensions as the result may be a function of position along the y axis.

Return type:

Cube

abstractmethod _get_y_distances()

Abstract method for calculating distances along the y axis of the input cube. The resulting cube shall have two dimensions.

Return type:

Cube

static build_distances_cube(distances, dims, axis)

Constructs an output cube with units of metres. :type distances: ndarray :param distances: Data array containing calculated distances with which to populate the output cube. :type dims: List[Coord] :param dims: Coordinate axes for the output cube. Must match the shape of distances. :type axis: str :param axis: The axis along which distances have been calculated.

Return type:

Cube

get_difference_axes()

Derives and returns the x and y coords for a cube of differences along one axis

Return type:

Tuple[DimCoord, DimCoord]

get_distances()

Calculates and returns the distances between grid points calculated along the cube’s x and y axis.

Return type:

Tuple[Cube, Cube]

Returns:

• 2D Cube of x-axis distances.

• 2D Cube of y-axis distances.

static get_midpoints(axis)

Returns the midpoints along the supplied axis. If the axis is circular, the difference between the last and first point is included with the assumption that this is in units of degrees.

Return type:

ndarray

class DifferenceBetweenAdjacentGridSquares

Bases: BasePlugin

Calculate the difference between adjacent grid squares within a cube. The difference is calculated along the x and y axes individually.

_abc_impl = <_abc._abc_data object>

static _axis_wraps_around_meridian(axis, cube)

Returns true if the cube is ‘circular’ with the given axis wrapping around, i.e. if there is a smooth transition between 180 degrees and -180 degrees on the axis.

Parameters:

• axis (Coord) – Axis to check for circularity.

• cube (Cube) – The cube to which the axis belongs.

Return type:

bool

Returns:

True if the axis wraps around the meridian; false otherwise.

static _update_metadata(diff_cube, coord_name, cube_name)

Rename cube, add attribute and cell method to describe difference.

Parameters:

• diff_cube (Cube)

• coord_name (str)

• cube_name (str)

Return type:

None

calculate_difference(cube, coord_name)

Calculate the difference along the axis specified by the coordinate.

Parameters:

• cube (Cube) – Cube from which the differences will be calculated.

• coord_name (str) – Name of coordinate along which the difference is calculated.

Return type:

ndarray

Returns:

Array after the differences have been calculated along the specified axis.

create_difference_cube(cube, coord_name, diff_along_axis)

Put the difference array into a cube with the appropriate metadata.

Parameters:

• cube (Cube) – Cube from which the differences have been calculated.

• coord_name (str) – The name of the coordinate over which the difference have been calculated.

• diff_along_axis (ndarray) – Array containing the differences.

Return type:

Cube

Returns:

Cube containing the differences calculated along the specified axis.

process(cube)

Calculate the difference along the x and y axes and return the result in separate cubes. The difference along each axis is calculated using numpy.diff.

Parameters:

cube (Cube) – Cube from which the differences will be calculated.

Return type:

Tuple[Cube, Cube]

Returns:

• Cube after the differences have been calculated along the x axis.

• Cube after the differences have been calculated along the y axis.

class DistanceBetweenGridSquares

Bases: BasePlugin

Calculates the distances between adjacent grid squares within a cube. The distances are calculated along the x and y axes individually. Returned distances are in metres. The class can handle cubes with either Geographic (lat-long) or Equal Area projections. For lat-lon cubes, the distances are calculated assuming a spherical earth. This causes a < 0.15% error compared with the full haversine formula.

_abc_impl = <_abc._abc_data object>

static _cube_xy_dimensions_are_distances(cube)

Returns true if the given cube has coordinates mapping to the x and y axes with units measuring distance (as opposed to angular separation) and false otherwise. :type cube: Cube :param cube: The iris cube to evaluate.

Return type:

bool

Returns:

Boolean representing whether the cube has x and y axes defined in a distance unit.

static _get_cube_spatial_type(cube)

Finds the coordinate system used by a cube.

Parameters:

cube (Cube) – Cube to find the coordinate system of.

Return type:

CoordSystem

Returns:

The coordinate system of the cube as an Iris Coordinate System.

_select_distance_calculator(cube)

Chooses which distance calculator class to apply based on the cube’s spatial coordinates.

Parameters:

cube (Cube) – Cube for which the distances will be calculated.

Raises:

• ValueError – Cube does not have enough information from which to calculate distances

• or uses an unsupported coordinate system. –

process(cube)

Calculate the distances between grid points along the x and y axes and return the result in separate cubes.

Parameters:

cube (Cube) – Cube for which the distances will be calculated.

Return type:

Tuple[Cube, Cube]

Returns:

• Cube of x-axis distances.

• Cube of y-axis distances.

class GradientBetweenAdjacentGridSquares(regrid=False)

Bases: PostProcessingPlugin

Calculate the gradients between adjacent grid squares within a cube. The gradient is calculated along the x and y axis individually.

__init__(regrid=False)

Initialise plugin.

Parameters:

regrid (bool) – If True, the gradient cube is regridded to match the spatial dimensions of the input cube. If False, the two output gradient cubes will have different spatial coords such that the coord matching the gradient axis will represent the midpoint of the input cube and will have one fewer points. If the x-axis is marked as circular, the gradient between the last and first points is also included.

_abc_impl = <_abc._abc_data object>

static _create_output_cube(gradient, name)

Create the output gradient cube, inheriting all metadata from source, but discarding the “form_of_difference” attribute.

Parameters:

• gradient (Cube) – Gradient values used in the data array of the resulting cube.

• name (str) – Name to apply to the output cube.

Return type:

Cube

Returns:

A cube of the gradients in the coordinate direction specified.

process(cube)

Calculate the gradient along the x and y axes and return the result in separate cubes. The difference along each axis is calculated using numpy.diff. This is then divided by the distance between grid points along the same axis to get the gradient.

Parameters:

cube (Cube) – Cube from which the differences will be calculated.

Return type:

CubeList[Cube, Cube]

Returns:

• Cube after the gradients have been calculated along the x-axis.

• Cube after the gradients have been calculated along the y-axis.

class LatLonCubeDistanceCalculator(cube)

Bases: BaseDistanceCalculator

Distance calculator for cubes using a Geographic Coordinate system. Assumes that latitude and longitude are given in degrees, and that the origin is at the intersection of the equator and the prime meridian. Distances are calculated assuming a spherical earth, resulting in a < 0.15% error when compared with the full haversine formula.

_abc_impl = <_abc._abc_data object>

_get_cube_latlon_points()

Extracts the y-axis and x-axis grid points used by a cube with a geographic coordinate system.

Return type:

Tuple[ndarray, ndarray]

Returns:

• latitude points used by the cube’s grid (in degrees).

• longitude points used by the cube’s grid (in degrees).

Raises:

• ValueError – Input cube does not use geographic coordinates, and/or

• uses units other than degrees. –

_get_x_distances()

Calculates the x-axis distances between adjacent grid points of a cube which uses Geographic coordinates.

Return type:

Cube

Returns:

A 2D cube containing the x-axis distances between adjacent grid points of the input cube in metres. As the earth is an oblate spheroid, the x-axis distances vary as a function of the y-axis. If the x-axis is marked as being circular, the distance between the last and first points is included in the output. x-axis coord positions are shifted to the mid-point of each pair.

_get_y_distances()

Calculates the y-axis distances between adjacent grid points of a cube which uses Geographic coordinates.

Return type:

Cube

Returns:

A 2D cube containing the y-axis distances between adjacent grid points of the input cube in metres. y-axis coord positions are shifted to the mid-point of each pair.

class OccurrenceWithinVicinity(radii=None, grid_point_radii=None, land_mask_cube=None, new_name=None, operator='max')

Bases: PostProcessingPlugin

Calculate whether a phenomenon occurs within the specified radii about a point. These radii can be given in metres, or as numbers of grid points. Each radius provided will result in a distinct output, with these demarked using a radius_of_vicinity coordinate on the resulting cube. If a single radius is provided, this will be a scalar coordinate.

Radii in metres may be used with data on a equal areas projection only. Grid_point_radii will work with any projection, with caveats.

Using grid_point_radius

A grid_point_radius will work with any projection but the effective kernel shape in real space may be irregular. An exagerated example is shown in the figure below. A vicinity radius of 1 grid point leads to a 3x3 grid point area, defined here on a very coarse lat-lon (PlateCaree) grid. This has been reprojected to an equal areas grid to demonstrate the resulting trapezoidal shape of the vicinity in “real space”.

Users must be aware of this when choosing whether to use this plugin with a non-equal areas projection. It could introduce biases into the resulting data, e.g. related to latitude in the above example.

Vicinity processing of regridded coarse grid data

When applying vicinity processing to data sourced from a coarse grid some care is needed. The particular case of concern is coarse grid data that has been regridded to a finer mesh without any kind of downscaling. This means that the data on the finer mesh remains blocky, revealing the grid scale of the underlying data. In such cases, though a vicinity radius of order the fine mesh scale could be applied, there is no additional information on this scale; vicinity processing is effectively a convolution to a coarser grid, and it cannot be used to convolve to what is effectively a finer grid.

As such, when vicinity processing this kind of regridded but coarse data, the minimum vicinity radius that should be used is one which returns a vicinity region on the scale of the underlying coarse grid.

(vicinity radius)_min = underlying grid cell width / 2

SUPPORTED_VICINITY_CELL_METHODS = {'max': 'maximum', 'mean': 'mean', 'min': 'minimum', 'std': 'standard_deviation'}

SUPPORTED_VICINITY_OPERATORS = {'max': <function maximum_within_vicinity>, 'mean': <function mean_within_vicinity>, 'min': <function minimum_within_vicinity>, 'std': <function std_within_vicinity>}

__init__(radii=None, grid_point_radii=None, land_mask_cube=None, new_name=None, operator='max')

Parameters:

• radii (Optional[List[Union[float, int]]]) – A list of radii in metres used to define the vicinities within which to search for occurrences.

• grid_point_radii (Optional[List[Union[float, int]]]) – Alternatively, a list of numbers of grid points that define the vicinity radii over which to search for occurrences. Only one of radii or grid_point_radii should be set.

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

• new_name (str) – New name to give to the resultant cube

• Operator – Operator to evaluate over the vicinities. Defaults to max.

Raises:

• ValueError – If both radii and grid point radii are set.

• ValueError – If neither radii or grid point radii are set.

• ValueError – If a provided vicinity radius is negative.

• ValueError – Land mask not named land_binary_mask.

• ValueError – If operator not in SUPPORTED_VICINITY_OPERATORS.

_abc_impl = <_abc._abc_data object>

process(cube, new_name=None)

Produces the vicinity processed data. The input data is sliced to yield y-x slices to which the <operator>_within_vicinity method is applied. The different vicinity radii (if multiple) are looped over and a coordinate recording the radius used is added to each resulting cube. A single cube is returned with the leading coordinates of the input cube preserved. If a single vicinity radius is provided, a new scalar radius_of_vicinity coordinate will be found on the returned cube. If multiple radii are provided, this coordinate will be a dimension coordinate following any probabilistic / realization coordinates.

Note that when applying the mean operator to thresholded data, this plugin will produce output equivalent to the NeighbourhoodProcessing plugin (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 NeighbourhoodProcessing plugin instead.

Parameters:

• cube (Cube) – Thresholded cube.

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

Return type:

Cube

Returns:

Cube containing the occurrences within a vicinity for each radius, calculated for each yx slice, which have been merged to yield a single cube.

Raises:

ValueError – Cube and land mask have differing spatial coordinates.

class ProjectionCubeDistanceCalculator(cube)

Bases: BaseDistanceCalculator

Distance calculator for cubes using a projected coordinate system. Assumes that x and y coordinates can be expressed in metres. Distances are calculated assuming an equal-area projection.

__init__(cube)

Parameters:

cube (Cube) – Cube for which the distances will be calculated.

Raises:

NotImplementedError – If the x-axis is marked as being circular.

_abc_impl = <_abc._abc_data object>

_get_x_distances()

Calculates the x-axis distances between adjacent grid points of a cube which uses Equal Area coordinates.

Return type:

Cube

Returns:

A 2D cube containing the x-axis distances between the grid points of the input cube in metres. x-axis coord positions are shifted to the mid-point of each pair.

_get_y_distances()

Calculates the y-axis distances between adjacent grid points of a cube which uses Equal Area coordinates.

Return type:

Cube

Returns:

A 2D cube containing the y-axis distances between the grid points of the input cube in metres. y-axis coord positions are shifted to the mid-point of each pair.

add_vicinity_coordinate(cube, radius, native_grid_point_radius=False, radius_is_max=False)

Add a coordinate to the cube that records the vicinity radius that has been applied to the data.

Parameters:

• cube (Cube) – Vicinity processed cube.

• radius (Union[float, int]) – The radius as a physical distance (m) or number of grid points, the value of which is recorded in the coordinate.

• native_grid_point_radius (bool) – True if radius is “number of grid points”, else False

• radius_is_max (bool) – True if the specified radius represents a maximum value from the source data. A comment is associated with the coord in this case.

Return type:

None

calculate_grid_spacing(cube, units, axis='x', rtol=1e-05)

Returns the grid spacing of a given spatial axis. This will be positive for axes that stride negatively.

Parameters:

• cube (Cube) – Cube of data on equal area grid

• units (Union[Unit, str]) – Unit in which the grid spacing is required

• axis (str) – Axis (‘x’ or ‘y’) to use in determining grid spacing

• rtol (float) – relative tolerance

Return type:

float

Returns:

Grid spacing in required unit

Raises:

ValueError – If points are not equally spaced

check_if_grid_is_equal_area(cube, require_equal_xy_spacing=True)

Identify whether the grid is an equal area grid, by checking whether points are equally spaced along each of the x- and y-axes. By default this function also checks whether the grid spacing is the same in both spatial dimensions.

Parameters:

• cube (Cube) – Cube with coordinates that will be checked.

• require_equal_xy_spacing (bool) – Flag to require the grid is equally spaced in the two spatial dimensions (not strictly required for equal-area criterion).

Raises:

• ValueError – If coordinate points are not equally spaced along either axis (from calculate_grid_spacing)

• ValueError – If point spacing is not equal for the two spatial axes

Return type:

None

create_vicinity_coord(radius, native_grid_point_radius=False)

Create a coordinate that records the vicinity radius passed in. This radius may be a distance in physical units, or if native_grid_point_radius is True, it will be a number of grid cells. If the latter an attribute comment is added to note that the radius is in grid cells.

Parameters:

• radius (Union[float, int]) – The radius as a physical distance or number of grid points, the value of which is recorded in the coordinate.

• native_grid_point_radius (bool) – If set to True the radius is provided a a number of grid points and the metadata created will reflect that.

Return type:

AuxCoord

distance_to_number_of_grid_cells(cube, distance, axis='x', return_int=True)

Return the number of grid cells in the x and y direction based on the input distance in metres. Requires an equal-area grid on which the spacing is equal in the x- and y- directions.

Parameters:

• cube (Cube) – Cube containing the x and y coordinates, which will be used for calculating the number of grid cells in the x and y direction, which equates to the requested distance in the x and y direction.

• distance (float) – Distance in metres. Must be positive.

• return_int (bool) – If true only integer number of grid_cells are returned, rounded down. If false the number of grid_cells returned will be a float.

• axis (str) – Axis (‘x’ or ‘y’) to use in determining grid spacing

Return type:

Union[float, int]

Returns:

Number of grid cells along the specified (x or y) axis equal to the requested distance in metres.

Raises:

ValueError – If a non-positive distance is provided.

get_grid_y_x_values(cube)

Extract the y and x coordinate values of each points in the cube.

The result is defined over the spatial grid, of shape (ny, nx) where ny is the length of the y-axis coordinate and nx the length of the x-axis coordinate.

Parameters:

cube (Cube) – Cube with points to extract

Return type:

Tuple[ndarray, ndarray]

Returns:

• Array of shape (ny, nx) containing y coordinate values

• Array of shape (ny, nx) containing x coordinate values

lat_lon_determine(cube)

Test whether a diagnostic cube is on a latitude/longitude grid or uses an alternative projection.

Parameters:

cube (Cube) – A diagnostic cube to examine for coordinate system.

Return type:

Optional[CRS]

Returns:

Coordinate system of the diagnostic cube in a cartopy format unless it is already a latitude/longitude grid, in which case None is returned.

maximum_within_vicinity(grid, grid_point_radius, landmask=None)

Find grid points where a phenomenon occurs within a defined radius. The occurrences within this vicinity are maximised, such that all grid points within the vicinity are recorded as having an occurrence. For non-binary fields, if the vicinity of two occurrences overlap, the maximum value within the vicinity is chosen. If a land-mask has been supplied, process land and sea points separately.

Parameters:

• grid (Union[MaskedArray, ndarray]) – An array of values to which the process is applied.

• grid_point_radius (int) – The radius in grid points about each point within which to determine the maximum value.

• landmask (Optional[ndarray]) – A binary grid of the same size as grid that differentiates between land and sea points to allow the different surface types to be processed independently.

Return type:

Union[MaskedArray, ndarray]

Returns:

Array where maximum is evaluated over spatial area; values are spatially spread, so that they’re equally likely to have occurred anywhere within the vicinity defined using the specified radius.

mean_within_vicinity(grid, grid_point_radius, landmask=None)

Find mean values over grid points within a defined radius. If a land-mask has been supplied, process land and sea points separately.

Parameters:

• grid (Union[MaskedArray, ndarray]) – An array of values to which the process is applied.

• grid_point_radius (int) – The radius in grid points about each point within which to determine the mean value.

• landmask (Optional[ndarray]) – A binary grid of the same size as grid that differentiates between land and sea points to allow the different surface types to be processed independently.

Return type:

Union[MaskedArray, ndarray]

Returns:

Array where mean is evaluated over spatial area; values are centred on each grid looking within the vicinity defined by the specified radius.

minimum_within_vicinity(grid, grid_point_radius, landmask=None)

Find grid points where a phenomenon occurs within a defined radius. The occurrences within this vicinity are minimised. For binary fields, grid points within the vicinity of a non-occurrence are all recorded as being a non-occurence. For non-binary fields, if the vicinity of two occurrences overlap, the minimum value within the vicinity is chosen. If a land-mask has been supplied, process land and sea points separately.

Parameters:

• grid (Union[MaskedArray, ndarray]) – An array of values to which the process is applied.

• grid_point_radius (int) – The radius in grid points about each point within which to determine the minimum value.

• landmask (Optional[ndarray]) – A binary grid of the same size as grid that differentiates between land and sea points to allow the different surface types to be processed independently.

Return type:

Union[MaskedArray, ndarray]

Returns:

Array where minimum is evaluated over spatial area; values are spatially spread, so that they’re equally likely to have occurred anywhere within the vicinity defined using the specified radius.

number_of_grid_cells_to_distance(cube, grid_points)

Calculate distance in metres equal to the given number of gridpoints based on the coordinates on an input cube.

Parameters:

• cube (Cube) – Cube for which the distance is to be calculated.

• grid_points (int) – Number of grid points to convert.

Return type:

float

Returns:

The radius in metres.

operator_within_vicinity(apply_filter, fill_value, grid, grid_point_radius, landmask=None)

Evaluate the specified filter over grid points within a defined radius. Where the operator applied is either an area maxima or minima, all grid points within the vicinity of the maxima/minima are recorded as having the same occurrence. If a land-mask has been supplied, process land and sea points separately.

Parameters:

• apply_filter (callable) – The filter to apply within the vicinity of each point.

• fill_value (Union[float, int]) – The fill-value to use when masking out points within the grid.

• grid (Union[MaskedArray, ndarray]) – An array of values to which the process is applied.

• grid_point_radius (int) – The radius in grid points about each point within which to determine the maximum value.

• landmask (Optional[ndarray]) – A binary grid of the same size as grid that differentiates between land and sea points to allow the different surface types to be processed independently.

Return type:

Union[MaskedArray, ndarray]

Returns:

Array where the occurrences have been spatially spread as per the filter method applied. For maxima/minima, they’re equally likely to have occurred anywhere within the vicinity defined using the specified radius.

rename_vicinity_cube(cube, new_name=None)

Rename a cube in place to indicate the cube has been vicinity processed.

Parameters:

cube (Cube) – Cube to be renamed.

set_vicinity_cell_method(cube, operation)

Add cell method to the cube to describe the vicinity operation applied.

Parameters:

• cube (Cube) – Cube to which to add the cell method.

• operation (str) – The operation type that has been applied to the spatial dimensions of the cube through the in-vicinity calculations.

Return type:

None

std_within_vicinity(grid, grid_point_radius, landmask=None)

Find the standard deviation values over grid points within a defined radius. If a land-mask has been supplied, process land and sea points separately.

Parameters:

• grid (Union[MaskedArray, ndarray]) – An array of values to which the process is applied.

• grid_point_radius (int) – The radius in grid points about each point within which to determine the standard deviation.

• landmask (Optional[ndarray]) – A binary grid of the same size as grid that differentiates between land and sea points to allow the different surface types to be processed independently.

Return type:

Union[MaskedArray, ndarray]

Returns:

Array where standard deviation is evaluated over spatial area; values are centred on each grid looking within the vicinity defined by the specified radius.

transform_grid_to_lat_lon(cube)

Calculate the latitudes and longitudes of each points in the cube.

The result is defined over the spatial grid, of shape (ny, nx) where ny is the length of the y-axis coordinate and nx the length of the x-axis coordinate.

Parameters:

cube (Cube) – Cube with points to transform

Return type:

Tuple[ndarray, ndarray]

Returns

• Array of shape (ny, nx) containing grid latitude values

• Array of shape (ny, nx) containing grid longitude values

update_name_and_vicinity_coord(cube, new_name, vicinity_radius)

Updates a cube with a new probabilistic-style name and replaces or adds a radius_of_vicinity coord with the specified radius.

Parameters:

• cube (Cube) – Cube to be updated in-place

• new_name (str) – The new name to be applied to the Cube, the threshold coord and any related cell methods.

• vicinity_radius (float) – The point value for the radius_of_vicinity coord. The units are assumed to be the same as the x and y spatial coords of the Cube