improver.cube_combiner module

Module containing plugins for combining cubes

class Combine(operation, broadcast_to_threshold=False, minimum_realizations=None, new_name=None, cell_method_coordinate=None)[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_to_threshold=False, minimum_realizations=None, new_name=None, cell_method_coordinate=None)[source]
Parameters

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

  • broadcast_to_threshold (bool) – If True, broadcast input cubes to the threshold coord prior to combining - a threshold 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.

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

Bases: BasePlugin

Plugin for combining cubes using linear operators

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

Create a CubeCombiner plugin

Parameters

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

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 _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

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 CubeMultiplier(broadcast_to_threshold=False)[source]

Bases: CubeCombiner

Class to multiply input cubes

The behaviour for the “multiply” operation is different from other types of cube combination. You can either apply a factor that conditions an input probability field - that is, to apply Bayes Theorem, or separate out a fraction of a variable (e.g. rain from precipitation). The first input field is used as the source of ALL input metadata. The factor(s) by which this is multiplied are not compared for any mis-match in scalar coordinates.

__init__(broadcast_to_threshold=False)[source]

Create a CubeMultiplier plugin

Parameters

broadcast_to_threshold (bool) – True if the first cube has a threshold coordinate to which the following cube(s) need(s) to be broadcast prior to combining data.

_abc_impl = <_abc_data object>
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

_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.

static _update_cell_methods(cell_methods, original_name, new_diagnostic_name)[source]

Update any cell methods that include a comment that refers to the diagnostic name to refer instead to the new diagnostic name. Those cell methods that do not include the diagnostic name are passed through unmodified.

Parameters

  • cell_methods (Tuple[CellMethod]) – The cell methods found on the cube that is being used as the metadata template.

  • original_name (str) – The full name of the metadata template cube.

  • new_diagnostic_name (str) – The new diagnostic name to use in the modified cell methods.

Return type

List[CellMethod]

Returns

A list of modified cell methods to replace the originals.

process(cube_list, new_diagnostic_name)[source]

Multiply data from a list of input cubes into a single cube. The first cube in the input list provides the combined cube metadata.

Parameters

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

  • new_diagnostic_name (str) – New name for the combined diagnostic. This should be the diagnostic name, eg rainfall_rate or rainfall_rate_in_vicinity, rather than the name of the probabilistic output cube.

Return type

Cube

Returns

Cube containing the combined data.

Raises

  • ValueError – If the cube_list contains only one cube.

  • TypeError – If combining data results in float64 data.

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)