improver.utilities.cube_extraction module

Utilities to parse a list of constraints and extract matching subcube

class ExtractLevel(positive_correlation, value_of_level)

Bases: BasePlugin

Class for extracting a pressure or height surface from data-on-levels.

__init__(positive_correlation, value_of_level)

Sets up Class

Parameters:

• positive_correlation (bool) – Set to True when the variable generally increases as pressure increase or when the variable generally increases as height decreases.

• value_of_level (float) – The value of the input cube for which the pressure or height level is required

_abc_impl = <_abc_data object>

_make_template_cube(result_data, variable_on_levels)

Creates a cube of the variable on a pressure or height level based on the input cube

Return type:

Cube

static _one_way_fill(data, coordinate_axis, coordinate_points, v_increment, reverse=False)

Scans through the pressure or height axis forwards or backwards, filling any missing data with the previous value plus (or minus in reverse) the specified increment. Running this in both directions will therefore populate all columns so long as there is at least one valid data point to start with.

coordinate_grid(variable_on_levels)

Creates a pressure or height grid of the same shape as variable_on_levels cube. It is populated at every grid square and for every realization with a column of all pressure or height levels taken from variable_on_levels’s pressure or height coordinate

Parameters:

variable_on_levels (Cube) – Cube of some variable with pressure or height levels

Return type:

ndarray

Returns:

An n dimensional array with the same dimensions as variable_on_levels containing, at every grid square and for every realization, a column of all pressure or height levels taken from variable_on_levels’s pressure or height coordinate

fill_invalid(cube)

Populate any invalid values in the source data with the neighbouring value in that column plus a small difference (determined by the least_significant_digit attribute, or 10^-2). This results in columns that do not have repeated values as repeated values confuse the stratify.interpolate method.

Parameters:

cube (Cube) – Cube of variable on levels (3D) (modified in-place).

process(variable_on_levels)

Extracts the pressure or height level (depending on which is present on the cube) where the environment variable first intersects self.value_of_level starting at a pressure or height value near the surface and ascending in altitude from there. Where the surface falls outside the available data, the maximum or minimum of the surface will be returned, even if the source data has no value at that point.

Parameters:

variable_on_levels (Cube) – A cube of data on pressure or height levels

Return type:

Cube

Returns:

A cube of the environment pressure or height at self.value_of_level

Raises:

NotImplementError – If variable_on_levels has both a height and pressure coordinate

apply_extraction(cube, constraint, units=None, use_original_units=True, longitude_constraint=None)

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

Parameters:

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

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

• units (Optional[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.

• longitude_constraint (Optional[List]) – List containing the min and max values for the longitude. This has to be treated separately to the normal constraints due to the circular nature of longitude.

Return type:

Cube

Returns:

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

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 (Union[float, List[float]]) – Constraint values that are being used to match against values in a cube for the purposes of extracting elements of the cube.

Return type:

Union[Callable, List[int]]

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.

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 (Cube) – The cube from which a subcube is to be extracted.

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

• units (Optional[List[str]]) – 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.

Return type:

Optional[Cube]

Returns:

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

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[str]) – List of string constraints with keys and values split by “=”: e.g: [“kw1=val1”, “kw2 = val2”, “kw3=val3”], where the vals could include ranges e.g. [0:20] or ranges with a step value e.g. [0:20:3].

• units (Optional[List[str]]) – 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.

Return type:

Tuple[Constraint, Optional[Dict], Optional[float], Optional[Dict]]

Returns:

• A combination of all the constraints that were supplied.

• A dictionary of unit keys and values

• A list containing the min and max values for a longitude constraint

• A dictionary of coordinate and the step value, i.e. a step of 2 will skip every other point

parse_range_string_to_dict(value)

Splits up a string in the form “[min:max:step]” into a list of [min, max, step].

Parameters:

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

Return type:

Dict[str, str]

Returns:

A list containing the min and max (and step).

thin_cube(cube, thinning_dict)

Thin the coordinate by taking every X points, defined in the thinning dict as {coordinate: X}

Parameters:

• cube (Cube) – The cube containing the coordinates to be thinned.

• thinning_dict (Dict[str, int]) – A dictionary of coordinate and the step value, i.e. a step of 2 will skip every other point

Return type:

Cube

Returns:

A cube with thinned coordinates.