improver.utilities.spatial module

Provides support utilities.

class improver.utilities.spatial.DifferenceBetweenAdjacentGridSquares(gradient=False)

Bases: object

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

__init__(gradient=False)

Initialise class.

calculate_difference(cube, coord_axis)

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 (String) – 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:

diff_cube (Iris.cube.Cube)

create_difference_cube(cube, coord_name, diff_along_axis)

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 (String) – The name of the coordinate over which the difference have been calculated.
• diff_along_axis (numpy array) – Array containing the differences.

Returns:

Cube containing the differences calculated along the specified axis.

Return type:

diff_cube (Iris.cube.Cube)

static gradient_from_diff(diff_cube, ref_cube, coord_axis)

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 (String) – 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:

gradient (Iris.cube.Cube)

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

Kwargs:

gradient (boolean):

Optionally return gradient rather than difference. This has dimensions of original grid, rather than losing 1 row & col, which is achieved by linear interpolation (note this will smooth over local maxima & minima).

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)

Bases: object

Calculate whether a phenomenon occurs within the specified distance.

__init__(distance)

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)

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:cube (Iris.cube.Cube)

process(cube)

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.

class improver.utilities.spatial.RegridLandSea(extrapolation_mode='nanmask', vicinity_radius=25000.0)

Bases: object

Replace data values at points where the nearest-regridding technique selects a source grid-point with an opposite land-sea-mask value to the target grid-point. The replacement data values are selected from a vicinity of points on the source-grid and the closest point of the correct mask is used. Where no match is found within the vicinity, the data value is not changed.

__init__(extrapolation_mode='nanmask', vicinity_radius=25000.0)

Initialise class

Keyword Arguments:  

• extrapolation_mode (string) –

  Mode to use for extrapolating data into regions beyond the limits of the source_data domain. Available modes are documented in iris.analysis

  Defaults to “nanmask”.

• vicinity_radius (float) – Distance in metres to search for a sea or land point.

correct_where_input_true(selector_val)

Replace points in the output_cube where output_land matches the selector_val and the input_land does not match, but has matching points in the vicinity, with the nearest matching point in the vicinity in the original nearest_cube.

Updates self.output_cube.data

Parameters:selector_val (int) – Value of mask to replace if needed. Intended to be 1 for filling land points near the coast and 0 for filling sea points near the coast.

process(cube, input_land, output_land)

Update cube.data so that output_land and sea points match an input_land or sea point respectively so long as one is present within the specified vicinity radius.

Parameters:

• cube (Iris.cube.Cube) – Cube of data to be updated (on same grid as output_land).
• input_land (Iris.cube.Cube) – Cube of land_binary_mask data on the grid from which “cube” has been reprojected (it is expected that the iris.analysis.Nearest method would have been used). This is used to determine where the input model data is representing land and sea points.
• output_land (Iris.cube.Cube) – Cube of land_binary_mask data on target grid.

improver.utilities.spatial.check_if_grid_is_equal_area(cube)

Identify whether the grid is an equal area grid. If not, raise an error. :param cube: Cube with coordinates that will be cMAhecked. :type cube: Iris.cube.Cube

Raises:

• ValueError – Invalid grid: projection_x/y coords required
• ValueError – Intervals between points along the x and y axis vary. Therefore the grid is not an equal area grid.
• ValueError – The size of the intervals along the x and y axis should be equal.

improver.utilities.spatial.convert_distance_into_number_of_grid_cells(cube, distance, max_distance_in_grid_cells=None, int_grid_cells=True)

Return the number of grid cells in the x and y direction based on the input distance in metres.

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.

Kwargs:

max_distance_in_grid_cells (int or None):

Maximum distance in grid cells. Defaults to None, which bypasses the check.

int_grid_cells (boolean):

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:

tuple containing:

grid_cells_x (int):

Number of grid cells in the x direction based on the requested distance in metres.

grid_cells_y (int):

Number of grid cells in the y direction based on the requested distance in metres.

Return type:

(tuple)

Raises:

• ValueError – If the projection is not “equal area” (proxied by projection_x/y spatial coordinate names).
• 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.
• ValueError – If the distance in grid cells is negative. (Assuming the distance argument is positive, this indicates one or more spatial axes are not correctly ordered.)
• 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)

Calculate radius size in metres from the given number of gridpoints based on the coordinates on an input cube.

Parameters:

• cube (iris.cube.Cube) – The iris cube that the number of grid points for the radius refers to.
• grid_points (int) – The number of grid points you want to convert.

Returns:

The radius in metres.

Return type:

radius_in_metres (float)

improver.utilities.spatial.get_nearest_coords(cube, latitude, longitude, iname, jname)

Uses the iris cube method nearest_neighbour_index to find the nearest grid points to a given latitude-longitude position.

Parameters:

• cube (iris.cube.Cube) – Cube containing a representative grid.
• latitude/longitude (floats) – Latitude/longitude coordinates of spot data site of interest.
• iname/jname (strings) – Strings giving the names of the y/x coordinates to be searched.

Returns:

Grid coordinates of the nearest grid point to the spot data site.

Return type:

i_latitude/j_latitude (int)

improver.utilities.spatial.lat_lon_determine(cube)

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:trg_crs (cartopy.crs/None)

improver.utilities.spatial.lat_lon_transform(trg_crs, latitude, longitude)

Transforms latitude/longitude coordinate pairs from a latitude/longitude grid into an alternative projection defined by trg_crs.

Parameters:

• trg_crs (cartopy.crs/None) – Target coordinate system in cartopy format or None.
• latitude (float) – Latitude coordinate.
• longitude (float) – Longitude coordinate.

Returns:

Longitude and latitude transformed into the target coordinate system.

Return type:

x, y (floats)

improver.utilities.spatial.transform_grid_to_lat_lon(cube)

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 (np.array):

Array of cube.data.shape of Latitude values

lons (np.array):

Array of cube.data.shape of Longitude values