improver.utilities.cube_manipulation module

Provides support utilities for cube manipulation.

class improver.utilities.cube_manipulation.ConcatenateCubes(master_coord, coords_to_associate=None, coords_to_slice_over=None)[source]

Bases: improver.BasePlugin

Class adding functionality to iris.concatenate_cubes().

Accounts for differences in attributes and allows promotion of scalar coordinates to be associated with the dimension over which concatenation is to be performed (eg can promote forecast_period to auxiliary for single time point cube inputs).

__init__(master_coord, coords_to_associate=None, coords_to_slice_over=None)[source]

Initialise parameters

Parameters

  • master_coord (str) – Coordinate to concatenate over.

  • coords_to_associate (list) – List of coordinates to be associated with the master_coord. If master_coord is “time” this should be “forecast_reference_time” OR “forecast_period”, NOT both.

  • coords_to_slice_over (list) – Dimension coordinates to slice over before concatenation. May cause the dimension order to change from input to output cubes.

_abc_cache = <_weakrefset.WeakSet object>
_abc_negative_cache = <_weakrefset.WeakSet object>
_abc_negative_cache_version = 213
_abc_registry = <_weakrefset.WeakSet object>
_associate_any_coordinate_with_master_coordinate(cube)[source]

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_period can be converted from scalar coordinate to auxiliary coordinate to be associated with a time dimension.

Parameters

cube (iris.cube.Cube) – Cube requiring promotion of the specified coordinates to auxiliary coordinates, to be associated with the master coordinate dimension.

Returns

Cube where the the requested coordinates have been promoted to auxiliary coordinates.

Return type

iris.cube.Cube

Raises

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

static _slice_over_coordinate(cubes, coord_to_slice_over)[source]

Function slices over the requested coordinate in each cube within a cubelist. The sliced coordinate is promoted into a one-point dimension to help concatenation. If the coord_to_slice_over is not found on a cube, the cube is added to the list in its original form.

Parameters
Returns

CubeList containing sliced cubes.

Return type

iris.cube.CubeList

process(cubes_in)[source]

Processes a list of cubes to ensure compatibility before calling the iris.cube.CubeList.concatenate_cube() method. Removes mismatched attributes, strips var_names from the cube and coordinates, and slices over any requested dimensions to avoid coordinate mismatch errors (eg for concatenating cubes with differently numbered realizations).

If the input is a single Cube or CubeList of length 1, the input cube is returned unmodified.

Parameters

cubes_in (iris.cube.CubeList or iris.cube.Cube) – Cube or list of cubes to be concatenated

Returns

Cube concatenated along master coord

Return type

iris.cube.Cube

Raises

ValueError – If master coordinate is not present on all “cubes_in”

class improver.utilities.cube_manipulation.MergeCubes[source]

Bases: improver.BasePlugin

Class adding functionality to iris.merge_cubes()

Accounts for differences in attributes, cell methods and bounds ranges to avoid merge failures and anonymous dimensions.

__init__()[source]

Initialise constants

_abc_cache = <_weakrefset.WeakSet object>
_abc_negative_cache = <_weakrefset.WeakSet object>
_abc_negative_cache_version = 213
_abc_registry = <_weakrefset.WeakSet object>
static _check_time_bounds_ranges(cube)[source]

Check the bounds on any dimensional time coordinates after merging. For example, to check time and forecast period ranges for accumulations to avoid blending 1 hr with 3 hr accumulations. If points on the coordinate are not compatible, raise an error.

Parameters

cube (iris.cube.Cube) – Merged cube

static _equalise_cell_methods(cubelist)[source]

Function to equalise cell methods that do not match. Modifies cubes in place.

Parameters

cubelist (iris.cube.CubeList) – List of cubes to check the cell methods and revise.

process(cubes_in, check_time_bounds_ranges=False)[source]

Function to merge cubes, accounting for differences in attributes, coordinates and cell methods. Note that cubes with different sets of coordinates (as opposed to cubes with the same coordinates with different values) cannot be merged.

If the input is a single Cube, this is returned unmodified. A CubeList of length 1 is checked for mismatched time bounds before returning the single Cube (since a CubeList of this form may be the result of premature iris merging on load).

Parameters

  • cubes_in (iris.cube.CubeList or iris.cube.Cube) – Cubes to be merged.

  • check_time_bounds_ranges (bool) – Flag to check whether scalar time bounds ranges match. This is for when we are expecting to create a new “time” axis through merging for eg precipitation accumulations, where we want to make sure that the bounds match so that we are not eg combining 1 hour with 3 hour accumulations.

Returns

Merged cube.

Return type

iris.cube.Cube

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)[source]

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

Parameters

  • data (int or list of numpy.ndarray) – List or array of values to populate the coordinate points.

  • long_name (str) – Name of the coordinate to be built.

  • standard_name (str) – CF Name of the coordinate to be built.

  • var_name (str) – Variable name

  • coord_type (iris.coords.Coord) – Selection between Dim and Aux coord.

  • data_type (<type>) – The data type of the coordinate points, e.g. int

  • units (str) – String defining the coordinate units.

  • bounds (numpy.ndarray) – A (len(data), 2) array that defines coordinate bounds.

  • coord_system (iris.coord_systems.<coord_system>) – A coordinate system in which the dimension coordinates are defined.

  • template_coord (iris.coords.Coord) – A coordinate to copy.

  • custom_function (function) – A function to apply to the data values before constructing the coordinate, e.g. np.nan_to_num.

Returns

The constructed coord.

Return type

iris.coords.Coord

improver.utilities.cube_manipulation.clip_cube_data(cube, minimum_value, maximum_value)[source]

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

iris.cube.Cube

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

Function to compare attributes of cubes

Parameters

  • cubes (iris.cube.CubeList) – List of cubes to compare (must be more than 1)

  • attribute_filter (str 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

list of dict

Warns

Warning – If only a single cube is supplied

improver.utilities.cube_manipulation.compare_coords(cubes)[source]

Function to compare the coordinates of the cubes

Parameters

cubes (iris.cube.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

list of dict

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)[source]

Wrapper for the ConcatenateCubes.process method

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.cube.CubeList or iris.cube.Cube) – Cubes to be concatenated.

  • coords_to_slice_over (list) – Coordinates to be sliced over.

  • master_coord (str) – 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 cube.

Return type

iris.cube.Cube

improver.utilities.cube_manipulation.enforce_coordinate_ordering(cube, coord_names, anchor_start=True)[source]

Function to reorder dimensions within a cube. Note that the input cube is modified in place.

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_start (bool) – Define whether the specified coordinates should be moved to the start (True) or end (False) of the list of dimensions. If True, the coordinates are inserted as the first dimensions in the order in which they are provided. If False, the coordinates are moved to the end. 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.

improver.utilities.cube_manipulation.equalise_cube_attributes(cubes, silent=None)[source]

Function to remove attributes that do not match between all cubes in the list. Cubes are modified in place.

Parameters

  • cubes (iris.cube.CubeList) – List of cubes to check the attributes and revise.

  • silent (list or None) – List of attributes to remove silently if unmatched.

Warns

UserWarning – If an unmatched attribute is not in the “silent” list, a warning will be raised.

NOTE 16/05/19: iris.experimental now has an equalise_attributes function, which removes any unmatched attributes without raising a warning.

TODO replace this function with the iris version once it is promoted into the standard iris package. At that time, the silent_attributes member of the MergeCubes and ConcatenateCubes classes becomes obsolete and should be removed.

improver.utilities.cube_manipulation.expand_bounds(result_cube, cubelist, expanded_coords)[source]

Alter a coord such that bounds are expanded to cover the entire range of the input cubes.

For example, in the case of time cubes if the input cubes have bounds of [0000Z, 0100Z] & [0100Z, 0200Z] then the output cube will have bounds of [0000Z,0200Z]

Parameters

  • result_cube (iris.cube.Cube) – A cube with metadata for the results.

  • cubelist (iris.cube.CubeList) – The list of cubes with coordinates to be combined

  • expanded_coords (dict or None) –

    Coordinates over which bounds should be expanded as a key, with the value indicating whether the upper or mid point of the coordinate should be used as the point value, e.g. {‘time’: ‘upper’}.

    ’mid’ - halfway between the bounds
    ’upper’ - equal to the upper bound

Returns

Cube with coords expanded.

n.b. If argument point == ‘mid’ then python will convert result.coord(‘coord’).points[0] to a float UNLESS the coord units contain ‘seconds’. This is to ensure that midpoints are not rounded down, for example when times are in hours.

Return type

iris.cube.Cube

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

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.

  • attribute_filter (str 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

dict

improver.utilities.cube_manipulation.merge_cubes(cubes)[source]

Wrapper for MergeCubes().process()

Parameters

cubes (iris.cube.CubeList or iris.cube.Cube) – Cubes to be merged.

Returns

Merged cube.

Return type

iris.cube.Cube

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

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 (str) – Name of the coordinate to be sorted.

  • order (str) – 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)[source]

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

Parameters

cubes (iris.cube.CubeList or iris.cube.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

iris.cube.CubeList