improver.utilities.spatial module¶

Provides support utilities.

class improver.utilities.spatial.DifferenceBetweenAdjacentGridSquares(gradient=False)[source]¶

Bases: improver.BasePlugin

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

__init__(gradient=False)[source]¶: Initialise class.

_abc_cache = <_weakrefset.WeakSet object>¶

_abc_negative_cache = <_weakrefset.WeakSet object>¶

_abc_negative_cache_version = 213¶

_abc_registry = <_weakrefset.WeakSet object>¶

calculate_difference(cube, coord_axis)[source]¶

Calculate the difference along the axis specified by the coordinate.

Parameters

cube (iris.cube.Cube) – Cube from which the differences will be calculated.
coord_axis (str) – Short-hand reference for the x or y coordinate, as allowed by iris.util.guess_coord_axis.

Returns

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

Return type

iris.cube.Cube

create_difference_cube(cube, coord_name, diff_along_axis)[source]¶

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

Parameters

cube (iris.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 (numpy.ndarray) – Array containing the differences.

Returns

Cube containing the differences calculated along the specified axis.

Return type

iris.cube.Cube

static gradient_from_diff(diff_cube, ref_cube, coord_axis)[source]¶

Calculate the gradient along the x or y axis from differences between adjacent grid squares.

Parameters

diff_cube (iris.cube.Cube) – Cube containing differences along the x or y axis
ref_cube (iris.cube.Cube) – Cube with correct output dimensions
coord_axis (str) – Short-hand reference for the x or y coordinate, as allowed by iris.util.guess_coord_axis.

Returns

A cube of the gradients in the coordinate direction specified.

Return type

iris.cube.Cube

process(cube)[source]¶

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 (iris.cube.Cube) – Cube from which the differences will be calculated.

Returns

tuple containing:

diff_along_y_cube (iris.cube.Cube):: Cube after the differences have been calculated along the y axis.
diff_along_x_cube (iris.cube.Cube):: Cube after the differences have been calculated along the x axis.

Return type

(tuple)

class improver.utilities.spatial.OccurrenceWithinVicinity(distance)[source]¶

Bases: object

Calculate whether a phenomenon occurs within the specified distance.

__init__(distance)[source]¶

Initialise the class.

Parameters: distance (float) – Distance in metres used to define the vicinity within which to search for an occurrence.

maximum_within_vicinity(cube)[source]¶

Find grid points where a phenomenon occurs within a defined distance. 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.

Parameters: cube (iris.cube.Cube) – Thresholded cube.
Returns: Cube where the occurrences have been spatially spread, so that they’re equally likely to have occurred anywhere within the vicinity defined using the specified distance.
Return type: iris.cube.Cube

process(cube)[source]¶

Ensure that the cube passed to the maximum_within_vicinity method is 2d and subsequently merged back together.

Parameters

cube (iris.cube.Cube) – Thresholded cube.

Returns

Iris.cube.Cube: Cube containing the occurrences within a vicinity for each xy 2d slice, which have been merged back together.

improver.utilities.spatial.calculate_grid_spacing(cube, units, axis='x')[source]¶

Returns the grid spacing of a given spatial axis

Parameters

cube (iris.cube.Cube) – Cube of data on equal area grid
units (str or cf_units.Unit) – Unit in which the grid spacing is required
axis (str) – Axis (‘x’ or ‘y’) to use in determining grid spacing

Returns

Grid spacing in required unit

Return type

float

Raises

ValueError – If points are not equally spaced

improver.utilities.spatial.check_if_grid_is_equal_area(cube, require_equal_xy_spacing=True)[source]¶

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 (iris.cube.Cube) – Cube with coordinates that will be checked.
require_equal_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

improver.utilities.spatial.convert_distance_into_number_of_grid_cells(cube, distance, axis='x', max_distance_in_grid_cells=None, int_grid_cells=True)[source]¶

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 (iris.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.
axis (str) – Axis (‘x’ or ‘y’) to use in determining grid spacing
max_distance_in_grid_cells (int or None) – Maximum distance in grid cells. Defaults to None, which bypasses the check.
int_grid_cells (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.

Returns

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

Return type

int or float

Raises

ValueError – If a negative distance is provided
ValueError – If the projection is not equal-area
ValueError – If the distance in grid cells is larger than the maximum dimension of the rectangular domain (measured across the diagonal). Needed for neighbourhood processing.
ValueError – If the distance in grid cells is zero.
Value Error – If max_distance_in_grid_cells is set and the distance in grid cells exceeds this value. Needed for neighbourhood processing.

improver.utilities.spatial.convert_number_of_grid_cells_into_distance(cube, grid_points)[source]¶

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

Parameters

cube (iris.cube.Cube) – Cube for which the distance is to be calculated.
grid_points (int) – Number of grid points to convert.

Returns

The radius in metres.

Return type

float

improver.utilities.spatial.lat_lon_determine(cube)[source]¶

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

Parameters: cube (iris.cube.Cube) – A diagnostic cube to examine for coordinate system.
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.
Return type: cartopy.crs.CRS or None

improver.utilities.spatial.transform_grid_to_lat_lon(cube)[source]¶

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

Parameters: cube (iris.cube.Cube) – Cube with points to transform

Returns

(tuple): tuple containing:

lats (numpy.ndarray):: Array of cube.data.shape of Latitude values
lons (numpy.ndarray):: Array of cube.data.shape of Longitude values