improver.utilities.cube_manipulation module

Provides support utilities for cube manipulation.

improver.utilities.cube_manipulation._associate_any_coordinate_with_master_coordinate(cube, master_coord='time', coordinates=None)

Function to convert the given coordinates from scalar coordinates to auxiliary coordinates, where these auxiliary coordinates will be associated with the master coordinate.

For example, forecast_reference_time and forecast_period can be converted from scalar coordinates to auxiliary coordinates, and associated with time.

Parameters:

• cube (Iris cube) – Cube requiring addition of the specified coordinates as auxiliary coordinates.
• master_coord (String) – Coordinate that the other coordinates will be associated with.
• coordinates (None or List) – List of coordinates to be associated with the master_coord.

Returns:

Cube where the the requested coordinates have been added to the cube as auxiliary coordinates and associated with the desired master coordinate.

Return type:

forecast_data (Iris cube)

Raises:

ValueError – If the master coordinate is not present on the cube.

improver.utilities.cube_manipulation._check_bounds_ranges(cube, coord_list)

Check the bounds ranges on a given list of coordinates match at each point along that dimension. For example: to check time and forecast period ranges for accumulations to avoid blending 1 hr with 3 hr accumulations.

Parameters:

• cube (iris.cube.Cube) – Input cube with dimensional coordinates in coord_list
• coord_list (list) – List of string coordinate names to check bounds

Raises:

ValueError – If bounds ranges at different points are incompatible

improver.utilities.cube_manipulation._check_coord_bounds(cubes)

Function to check for dimension coordinate bounds that do not match. If a coordinate is not present in all cubes, it is ignored.

Parameters:

cubes (iris.cube.CubeList) – List of cubes to check the cell methods and revise. These are modified in place.

Raises:

• ValueError – If some but not all cubes have bounds on a shared dimension coordinate.
• ValueError – If existing bounds values on shared dimension coordinates do not match.

improver.utilities.cube_manipulation._equalise_cell_methods(cubes)

Function to equalise cell methods that do not match.

Parameters:cubes (iris.cube.CubeList) – List of cubes to check the cell methods and revise. Returns:List of cubes with revised cell methods. Currently the cell methods are simply deleted if they do not match. Return type:cubelist (iris.cube.CubeList) Warns:Warning – If only a single cube.

improver.utilities.cube_manipulation._equalise_cube_attributes(cubes, model_id_attr=None)

Function to equalise attributes that do not match.

Parameters:

• cubes (Iris cubelist) – List of cubes to check the attributes and revise.
• model_id_attr (str) – Name of cube attribute used to identify the model for grid blending or None.

Returns:

Note: This internal function modifies the incoming cubes

Return type:

cubelist (Iris cubelist)

Warns:

Warning – If it does not know what to do with an unmatching attribute. Default is to delete it.

improver.utilities.cube_manipulation._equalise_cube_coords(cubes)

Function to equalise coordinates that do not match.

Parameters:

cubes (Iris cubelist) – List of cubes to check the coords and revise.

Returns:

List of cubes with revised coords. The number of cubes in cubelist may be greater than the original number of cubes as the original cubes will be sliced so that that they can be merged together. Merging can only create new coords not add to existing mismatching coords. Note: This internal function modifies the incoming cubes

Return type:

cubelist (Iris cubelist)

Raises:

• ValueError – If coordinates in error_keys do not match.
• ValueError – If model_id has more than one point.

improver.utilities.cube_manipulation._equalise_cubes(cubes_in, model_id_attr=None, merging=True)

Function to equalise cubes where they do not match.

Parameters:cubes_in (Iris cubelist) – List of cubes to check and equalise.

Kwargs:

model_id_attr (str):

Name of cube attribute used to identify the model for grid blending or None.

merging (bool):

Flag for whether equalisation is for merging or concatenation.

Returns:List of cubes with revised cubes. If merging the number of cubes in cubelist may be greater than the original number of cubes as the original cubes will be sliced so that that they can be merged together. Merging can only create new coords not add to existing mismatching coords. Return type:cubelist (Iris cubelist)

improver.utilities.cube_manipulation._slice_over_coordinate(cubes, coord_to_slice_over)

Function slice over the requested coordinate, promote the sliced coordinate into a dimension coordinate to help concatenation.

Parameters:

• cubes (Iris cubelist or Iris cube) – Cubes to be concatenated.
• coords_to_slice_over (List) – Coordinates to be sliced over.

Returns:

Iris CubeList

CubeList containing sliced cubes.

improver.utilities.cube_manipulation.build_coordinate(data, long_name=None, standard_name=None, var_name=None, coord_type=<class 'iris.coords.DimCoord'>, data_type=None, units='1', bounds=None, coord_system=None, template_coord=None, custom_function=None)

Construct an iris.coord.Dim/Auxcoord using the provided options.

Parameters:

• data (number/list/np.array) – List or array of values to populate the coordinate points.
• long_name (str (optional)) – Name of the coordinate to be built.
• standard_name (str (optional)) – CF Name of the coordinate to be built.
• var_name (str (optional)) – Variable name
• coord_type (iris.coord.AuxCoord or iris.coord.DimCoord (optional)) – Selection between Dim and Aux coord.
• data_type (<type> (optional)) – The data type of the coordinate points, e.g. int
• units (str (optional)) – String defining the coordinate units.
• bounds (np.array (optional)) – A (len(data), 2) array that defines coordinate bounds.
• coord_system (iris.coord_systems.<coord_system> (optional)) – A coordinate system in which the dimension coordinates are defined.
• template_coord (iris.coord) – A coordinate to copy.
• custom_function (function (optional)) – A function to apply to the data values before constructing the coordinate, e.g. np.nan_to_num.

Returns:

Dim or Auxcoord as chosen.

Return type:

crd_out(iris coordinate)

improver.utilities.cube_manipulation.clip_cube_data(cube, minimum_value, maximum_value)

Apply np.clip to data in a cube to ensure that the limits do not go beyond the provided minimum and maximum values.

Parameters:

• cube (iris.cube.Cube) – The cube that has been processed and contains data that is to be clipped.
• minimum_value (int or float) – The minimum value, with data in the cube that falls below this threshold set to it.
• maximum_value (int or float) – The maximum value, with data in the cube that falls above this threshold set to it.

Returns:

The processed cube with the data clipped to the limits of the original preprocessed cube.

Return type:

result (iris.cube.Cube)

improver.utilities.cube_manipulation.compare_attributes(cubes, attribute_filter=None)

Function to compare attributes of cubes

Parameters:cubes (Iris cubelist) – List of cubes to compare (must be more than 1) Keyword Arguments:  attribute_filter (string or None) – A string to filter which attributes are actually compared. If None all attributes are compared. Returns:List of dictionaries of unmatching attributes Return type:unmatching_attributes (List) Warns:Warning – If only a single cube is supplied

improver.utilities.cube_manipulation.compare_coords(cubes)

Function to compare the coordinates of the cubes

Parameters:cubes (Iris cubelist) – List of cubes to compare (must be more than 1) Returns:List of dictionaries of unmatching coordinates Number of dictionaries equals number of cubes unless cubes is a single cube in which case unmatching_coords returns an empty list. Return type:unmatching_coords (List) Warns:Warning – If only a single cube is supplied

improver.utilities.cube_manipulation.concatenate_cubes(cubes_in, coords_to_slice_over=None, master_coord='time', coordinates_for_association=None)

Function to concatenate cubes, accounting for differences in the history attribute, and allow promotion of forecast_reference_time and forecast_period coordinates from scalar coordinates to auxiliary coordinates to allow concatenation.

Parameters:

• cubes_in (Iris cubelist or Iris cube) – Cubes to be concatenated.
• coords_to_slice_over (List) – Coordinates to be sliced over.
• master_coord (String) – Coordinate that the other coordinates will be associated with.
• coordinates_for_association (List) – List of coordinates to be associated with the master_coord.

Returns:

Concatenated / merge cube.

Return type:

result (Iris cube)

improver.utilities.cube_manipulation.enforce_coordinate_ordering(cube, coord_names, anchor='start', promote_scalar=False, raise_exception=False)

Function to ensure that the requested coordinate within the cube are in the desired position.

The reordering can either be anchored to the start or end of the available dimension coordinates using the “anchor” keyword argument. If desired, all the dimension coordinates can be reordered by specifying the coordinate names in the desired order.

Note that the input cube is used as the output cube apart from if promote_scalar = True when a new cube instance is generated with an extra leading dimension.

Parameters:

• cube (iris.cube.Cube) – Cube where the ordering will be enforced to match the order within the coord_names. This input cube will be modified as part of this function.
• coord_names (list or str) – List of the names of the coordinates to order. If a string is passed in, only the single specified coordinate is reordered.
• anchor (str) – String to define where within the range of possible dimensions the specified coordinates should be located. If all the names of all the dimension coordinates are specified within the coord_names argument then this argument effectively does nothing. The options are either: “start” or “end”. “start” indicates that the coordinates are inserted as the first coordinates within the cube. “end” indicates that the coordinates are inserted as the last coordinates within the cube. For example, if the specified coordinate names are [“time”, “realization”] then “realization” will be the last coordinate within the cube, whilst “time” will be the last but one coordinate within the cube.
• promote_scalar (bool) – If True, any coordinates that are matched and are not dimension coordinates are promoted to dimension coordinates. If False, any coordinates that are matched and are not dimension coordinates will not be considered in the reordering.
• raise_exception (bool) – Option as to whether an exception should be raised, if the requested coordinate is not present.

Returns:

Cube where the requirement for the dimensions to be in a particular order will have been enforced.

Return type:

cube (iris.cube.Cube)

Raises:

• ValueError – The anchor argument must have a value of either start or end.
• CoordinateNotFoundError – The requested coordinate is not available on the cube.
• ValueError – Multiple coordinates match the partial name provided.

improver.utilities.cube_manipulation.get_filtered_attributes(cube, attribute_filter=None)

Build dictionary of attributes that match the attribute_filter. If the attribute_filter is None, return all attributes.

Parameters:cube (iris.cube.Cube) – A cube from which attributes partially matching the attribute_filter will be returned. Keyword Arguments:  attribute_filter (string or None) – A string to match, or partially match, against attributes to build a filtered attribute dictionary. If None, all attributes are returned. Returns:A dictionary of attributes partially matching the attribute_filter that were found on the input cube. Return type:attributes (dict)

improver.utilities.cube_manipulation.merge_cubes(cubes, model_id_attr=None, blend_coord=None)

Function to merge cubes, accounting for differences in the attributes, and coords.

Parameters:cubes (Iris cubelist or Iris cube) – Cubes to be merged.

Kwargs:

model_id_attr (str):

Name of cube attribute used to identify the model for grid blending or None.

blend_coord (str):

Name of coordinate over which merged cube is to be blended, or None. If “time”, triggers bounds range checks to avoid passing eg mismatched accumulation periods into blending.

Returns:Merged cube. Return type:result (Iris cube)

improver.utilities.cube_manipulation.sort_coord_in_cube(cube, coord, order='ascending')

Sort a cube based on the ordering within the chosen coordinate. Sorting can either be in ascending or descending order. This code is based upon https://gist.github.com/pelson/9763057.

Parameters:

• cube (iris.cube.Cube) – The input cube to be sorted.
• coord (string) – Name of the coordinate to be sorted.
• order (string) – Choice of how to order the sorted coordinate. Options are either “ascending” or “descending”.

Returns:

Cube where the chosen coordinate has been sorted into either ascending or descending order.

Return type:

iris.cube.Cube

Warns:

Warning if the coordinate being processed is a circular coordinate.

improver.utilities.cube_manipulation.strip_var_names(cubes)

Strips var_name from the cube and from all coordinates to help concatenation.

Parameters:cubes (Iris cubelist or Iris cube) – Cubes to be concatenated. Returns:CubeList containing original cubes without a var_name on the cube, or on the coordinates. Note: This internal function modifies the incoming cubes Return type:cubes (Iris CubeList)