improver.utilities.cube_extraction module

Utilities to parse a list of constraints and extract matching subcube

improver.utilities.cube_extraction.apply_extraction(cube, constraint, units=None, use_original_units=True)

Using a set of constraints, extract a subcube from the provided cube if it is available.

Parameters

• cube (iris.cube.Cube) – The cube from which a subcube is to be extracted.

• constraint (iris.Constraint or iris.ConstraintCombination) – The constraint or ConstraintCombination that will be used to extract a subcube from the input cube.

• units (dict) – A dictionary of units for the constraints. Supplied if any coordinate constraints are provided in different units from those of the input cube (eg precip in mm/h for cube threshold in m/s).

• use_original_units (bool) – Boolean to state whether the coordinates used in the extraction should be converted back to their original units. The default is True, indicating that the units should be converted back to the original units.

Returns

A single cube matching the input constraints, or None if no subcube is found within cube that matches the constraints.

Return type

iris.cube.Cube

improver.utilities.cube_extraction.create_constraint(value)

Constructs an appropriate constraint for matching numerical values if they are floating point. If not, the original values are returned as a list (even if they were single valued on entry).

Parameters

value (float/int or list of float/int) – Constraint values that are being used to match against values in a cube for the purposes of extracting elements of the cube.

Returns

If the input value(s) are floating point this function returns a lambda function that will enable for approximate matching to ensure they can be matched to cube values. If the inputs are int or non-numeric, they will be returned unchanged, except for single values that will have become lists.

Return type

lambda function or list

improver.utilities.cube_extraction.create_range_constraint(coord_name, value)

Create a constraint that is representative of a range.

Parameters

• coord_name (str) – Name of the coordinate for which the constraint will be created.

• value (str) – A string containing the range information. It is assumed that the input value is of the form: “[2:10]”.

Returns

The constraint that has been created to represent the range.

Return type

iris.Constraint

improver.utilities.cube_extraction.extract_subcube(cube, constraints, units=None, use_original_units=True)

Using a set of constraints, extract a subcube from the provided cube if it is available.

Parameters

• cube (iris.cube.Cube) – The cube from which a subcube is to be extracted.

• constraints (list) – List of string constraints with keys and values split by “=”: e.g: [“kw1=val1”, “kw2 = val2”, “kw3=val3”].

• units (list) – List of units (as strings) corresponding to each coordinate in the list of constraints. One or more “units” may be None, and units may only be associated with coordinate constraints.

• use_original_units (bool) – Boolean to state whether the coordinates used in the extraction should be converted back to their original units. The default is True, indicating that the units should be converted back to the original units.

Returns

A single cube matching the input constraints, or None if no subcube is found within cube that matches the constraints.

Return type

iris.cube.Cube or None

improver.utilities.cube_extraction.is_complex_parsing_required(value)

Determine if the string being parsed requires complex parsing. Currently, this is solely determined by the presence of a colon (:).

Parameters

value (str) – A string that will be parsed.

Returns

Flag value to indicate whether the string requires complex parsing.

Return type

bool

improver.utilities.cube_extraction.parse_constraint_list(constraints, units=None)

For simple constraints of a key=value format, these are passed in as a list of strings and converted to key-value pairs prior to creating the constraints. For more complex constraints, the list of strings given as input are evaluated by parsing for specific identifiers and then the constraints are created as required. The simple key-value pairs and other constraints are merged into a single constraint.

Parameters

• constraints (list) – List of string constraints with keys and values split by “=”: e.g: [“kw1=val1”, “kw2 = val2”, “kw3=val3”].

• units (list) – List of units (as strings) corresponding to each coordinate in the list of constraints. One or more “units” may be None, and units may only be associated with coordinate constraints.

Returns

tuple containing:

constraints (iris.Constraint or iris._constraints.ConstraintCombination):

A combination of all the constraints that were supplied.

units_dict (dictionary or None):

A dictionary of unit keys and values

Return type

(tuple)