improver.cube_combiner module

Module containing plugins for combining cubes

class Combine(operation, broadcast=None, minimum_realizations=None, new_name=None, cell_method_coordinate=None, expand_bound=True)[source]

Bases: BasePlugin

Combine input cubes.

Combine the input cubes into a single cube using the requested operation. The first cube in the input list provides the template for output metadata. If coordinates are expanded as a result of this combine operation (e.g. expanding time for accumulations / max in period) the upper bound of the new coordinate will also be used as the point for the new coordinate.

__init__(operation, broadcast=None, minimum_realizations=None, new_name=None, cell_method_coordinate=None, expand_bound=True)[source]
Parameters:

  • operation (str) – An operation to use in combining input cubes. One of: +, -, *, add, subtract, multiply, min, max, mean

  • broadcast (str) – If specified, broadcast input cubes to the stated coord prior to combining - the coord must already exist on the first input cube.

  • minimum_realizations (int) – If specified, the input cubes will be filtered to ensure that only realizations that include all available lead times are combined. If the number of realizations that meet this criteria are fewer than this integer, an error will be raised. Minimum value is 1.

  • new_name (str) – New name for the resulting dataset.

  • cell_method_coordinate (str) – If specified, a cell method is added to the output with the coordinate provided. This is only available for max, min and mean operations.

  • expand_bound (bool) – If True then coord bounds will be extended to represent all cubes being combined.

_abc_impl = <_abc_data object>
process(cubes)[source]

Preprocesses the cubes, then passes them to the appropriate plugin

Parameters:

cubes (iris.cube.CubeList or list of iris.cube.Cube) – An iris CubeList to be combined.

Returns:

Returns a cube with the combined data.

Return type:

result (iris.cube.Cube)

Raises:

  • TypeError – If input list of cubes is empty

  • ValueError – If minimum_realizations aren’t met, or less than one were requested.

class CubeCombiner(operation, cell_method_coordinate=None, broadcast=None, expand_bound=True)[source]

Bases: BasePlugin

Plugin for combining cubes using linear operators

COMBINE_OPERATORS = {'*': <ufunc 'multiply'>, '+': <ufunc 'add'>, '-': <ufunc 'subtract'>, 'add': <ufunc 'add'>, 'max': <ufunc 'maximum'>, 'mean': <ufunc 'add'>, 'min': <ufunc 'minimum'>, 'multiply': <ufunc 'multiply'>, 'subtract': <ufunc 'subtract'>}
__init__(operation, cell_method_coordinate=None, broadcast=None, expand_bound=True)[source]

Create a CubeCombiner plugin

Parameters:

  • operation (str) – Operation (+, - etc) to apply to the incoming cubes.

  • cell_method_coordinate (Optional[str]) – If specified, a cell method is added to the output with the coordinate provided. This is only available for max, min and mean operations.

  • broadcast (Optional[str]) – If specified, broadcast input cubes to the stated coord prior to combining - the coord must already exist on the first input cube.

  • expand_bound (bool) – If True then coord bounds will be extended to represent all cubes being combined.

Raises:

ValueError – if operation is not recognised in dictionary

_abc_impl = <_abc_data object>
_add_cell_method(cube)[source]

Add a cell method to record the operation undertaken.

Parameters:

cube (Cube) – Cube to which a cell method will be added.

Raises:

ValueError – If a cell_method_coordinate is provided and the operation is not max, min or mean.

Return type:

None

static _check_dimensions_match(cube_list, comparators=[<built-in function eq>])[source]

Check all coordinate dimensions on the input cubes match according to the comparators specified.

Parameters:

  • cube_list (Union[List[Cube], CubeList]) – List of cubes to compare

  • comparators (List[Callable]) – Comparison operators, at least one of which must return “True” for each coordinate in order for the match to be valid

Raises:

ValueError – If dimension coordinates do not match

Return type:

None

_combine_cube_data(cube_list)[source]

Perform cumulative operation to combine cube data

Parameters:

cube_list (Union[List[Cube], CubeList]) –

Return type:

Cube

Returns:

Combined cube

Raises:

TypeError – if the operation results in an escalated datatype

static _coords_are_broadcastable(coord1, coord2)[source]

Broadcastable coords will differ only in length, so create a copy of one with the points and bounds of the other and compare. Also ensure length of at least one of the coords is 1.

Return type:

bool

static _get_expanded_coord_names(cube_list)[source]

Get names of coordinates whose bounds need expanding and points recalculating after combining cubes. These are the scalar coordinates that are present on all input cubes, but have different values.

Parameters:

cube_list (Union[List[Cube], CubeList]) – List of cubes to that will be combined

Return type:

List[str]

Returns:

List of coordinate names to expand

_setup_coords_for_broadcast(cube_list)[source]

Adds a scalar threshold to any subsequent cube in cube_list so that they all match the dimensions, in order, of the first cube in the list

Parameters:

cube_list (CubeList) –

Return type:

CubeList

Returns:

Updated version of cube_list

Raises:

  • CoordinateNotFoundError – if there is no threshold coordinate on the first cube in the list

  • TypeError – if there is a scalar threshold coordinate on any of the later cubes, which would indicate that the cube is only valid for a single threshold and should not be broadcast to all thresholds.

process(cube_list, new_diagnostic_name)[source]

Combine data and metadata from a list of input cubes into a single cube, using the specified operation to combine the cube data. The first cube in the input list provides the template for the combined cube metadata. If coordinates are expanded as a result of this combine operation (e.g. expanding time for accumulations / max in period) the upper bound of the new coordinate will also be used as the point for the new coordinate.

Parameters:

  • cube_list (Union[List[Cube], CubeList]) – List of cubes to combine.

  • new_diagnostic_name (str) – New name for the combined diagnostic.

Return type:

Cube

Returns:

Cube containing the combined data.

Raises:

ValueError – If the cube_list contains only one cube.

class MaxInTimeWindow(minimum_realizations=None)[source]

Bases: BasePlugin

Find the maximum within a time window for a period diagnostic. For example, find the maximum 3-hour precipitation accumulation within a 24 hour window.

__init__(minimum_realizations=None)[source]

Initialise class.

Parameters:

minimum_realizations (int) – If specified, the input cubes will be filtered to ensure that only realizations that include all available lead times are combined. If the number of realizations that meet this criteria are fewer than this integer, an error will be raised. Minimum value is 1.

_abc_impl = <_abc_data object>
_check_input_cubes(coords)[source]

Check that the input cubes are period diagnostics i.e. where the time coordinate has bounds representing a period and that the bounds represent a consistent period.

Parameters:

coords (List[Union[AuxCoord, DimCoord]]) – The time coordinates extracted from the input cubes.

Raises:

  • ValueError – The input cubes do not have bounds.

  • ValueError – The input cubes do not all have bounds.

  • ValueError – The input cubes have bounds that imply mismatching periods.

_correct_metadata(cube, coords_in_hours)[source]

Correct metadata in particular to ensure that the cell methods are updated to represent a period for a time window diagnostic.

Parameters:

  • cube (Cube) – Cube representating the maximum over a time window for a period diagnostic.

  • coords_in_hours (List[Union[AuxCoord, DimCoord]]) – List of time coordinates in units of hours since 1970-01-01 00:00:00.

Return type:

Cube

Returns:

Cube representating the maximum over a time window for a period diagnostic with appropriate metadata.

_get_coords_in_hours(cubes)[source]

Get the time coordinates from the input cubes in units of hours since 1970-01-01 00:00:00.

Parameters:

cubes (List[Cube]) – Cubes from which the time coordinates will be extracted.

Return type:

List[Union[AuxCoord, DimCoord]]

Returns:

The time coordinates extracted from the input cubes.

process(cubes)[source]

Compute the maximum probability or maximum diagnostic value within a time window for a period diagnostic using the Combine plugin. The resulting cube has a time coordinate with bounds that represent the time window whilst the cell method has been updated to represent the period recorded on the input cubes. For example, the time window might be 24 hours, whilst the period might be 3 hours.

Parameters:

cubes (iris.cube.CubeList or list of iris.cube.Cube) – An iris CubeList to be combined.

Returns:

Returns a cube with the combined data.

Return type:

result (iris.cube.Cube)