improver.blending.weighted_blend module

Module containing classes for doing weighted blending by collapsing a whole dimension.

class improver.blending.weighted_blend.MergeCubesForWeightedBlending(blend_coord, weighting_coord=None, model_id_attr=None)[source]

Bases: improver.BasePlugin

Prepares cubes for cycle and grid blending

__init__(blend_coord, weighting_coord=None, model_id_attr=None)[source]

Initialise the class

Parameters

  • blend_coord (str) – Name of coordinate over which blending will be performed. For multi-model blending this is flexible to any string containing “model”. For all other coordinates this is prescriptive: cube.coord(blend_coord) must return an iris.coords.Coord instance for all cubes passed into the “process” method.

  • weighting_coord (str or None) – The coordinate across which weights will be scaled in a multi-model blend.

  • model_id_attr (str or None) – Name of attribute used to identify model for grid blending. None for cycle blending.

Raises

ValueError – If trying to blend over model when model_id_attr is not set

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

Adds numerical model ID and string model configuration scalar coordinates to input cubes if self.model_id_attr is specified. Sets the original attribute value to “blend”, in anticipation. Modifies cubes in place.

Parameters

cubelist (iris.cube.CubeList) – List of cubes to be merged for blending

Raises

  • ValueError – If self.model_id_attr is not present on all cubes

  • ValueError – If input cubelist contains cubes from the same model

process(cubes_in, cycletime=None)[source]

Prepares merged input cube for cycle and grid blending

Parameters

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

  • cycletime (str or None) – The cycletime in a YYYYMMDDTHHMMZ format e.g. 20171122T0100Z. Can be used in rationalise_blend_time_coordinates.

Returns

Merged cube.

Return type

iris.cube.Cube

Raises

ValueError – If self.blend_coord is not present on all cubes (unless blending over models)

class improver.blending.weighted_blend.PercentileBlendingAggregator[source]

Bases: object

Class for the percentile blending aggregator

This class implements the method described by Combining Probabilities by Caroline Jones, 2017. This method implements blending in probability space.

The steps are:

  1. At each geographic point in the cube we take the percentile threshold’s values across the percentile dimensional coordinate. We recalculate, using linear interpolation, their probabilities in the pdf of the other points across the coordinate we are blending over. Thus at each point we have a set of thresholds and their corresponding probability values in each of the probability spaces across the blending coordinate.

  2. We do a weighted blend across all the probability spaces, combining all the thresholds in all the points in the coordinate we are blending over. This gives us an array of thresholds and an array of blended probabilities for each of the grid points.

  3. We convert back to the original percentile values, again using linear interpolation, resulting in blended values at each of the original percentiles.

References

Combining Probabilities by Caroline Jones, 2017: https://github.com/metoppv/improver/files/1128018/ Combining_Probabilities.pdf

static aggregate(data, axis, arr_percent, arr_weights, perc_dim)[source]
Blend percentile aggregate function to blend percentile data

along a given axis of a cube.

Parameters

  • data (numpy.ndarray) – Array containing the data to blend

  • axis (int) – The index of the coordinate dimension in the cube. This dimension will be aggregated over.

  • arr_percent (numpy.ndarray) – Array of percentile values e.g [0, 20.0, 50.0, 70.0, 100.0], same size as the percentile dimension of data.

  • arr_weights (numpy.ndarray) – Array of weights, same size as the axis dimension of data.

  • perc_dim (int) – The index of the percentile coordinate

  • percent and weights have special meaning in Aggregator ((Note) – hence the rename.)

Returns

containing the weighted percentile blend data across the chosen coord. The dimension associated with axis has been collapsed, and the rest of the dimensions remain.

Return type

numpy.ndarray

static blend_percentiles(perc_values, percentiles, weights)[source]
Blend percentiles function, to calculate the weighted blend across

a given axis of percentile data for a single grid point.

Parameters

  • perc_values (numpy.ndarray) – Array containing the percentile values to blend, with shape: (length of coord to blend, num of percentiles)

  • percentiles (numpy.ndarray) – Array of percentile values e.g [0, 20.0, 50.0, 70.0, 100.0], same size as the percentile dimension of data.

  • weights (numpy.ndarray) – Array of weights, same size as the axis dimension of data, that we will blend over.

Returns

Array containing the weighted percentile blend data across the chosen coord

Return type

numpy.ndarray

class improver.blending.weighted_blend.WeightedBlendAcrossWholeDimension(blend_coord, timeblending=False)[source]

Bases: improver.BasePlugin

Apply a Weighted blend to a cube, collapsing across the whole dimension. Uses one of two methods, either weighted average, or the maximum of the weighted probabilities.

__init__(blend_coord, timeblending=False)[source]

Set up for a Weighted Blending plugin

Parameters

  • blend_coord (str) – The name of the coordinate dimension over which the cube will be blended.

  • timeblending (bool) – With the default of False the cube being blended will be checked to ensure that slices across the blending coordinate all have the same validity time. Setting this to True will bypass this test, as is necessary for triangular time blending.

Raises

ValueError – If the blend coordinate is “threshold”.

_abc_cache = <_weakrefset.WeakSet object>
_abc_negative_cache = <_weakrefset.WeakSet object>
_abc_negative_cache_version = 213
_abc_registry = <_weakrefset.WeakSet object>
static _get_cycletime_point(input_cube, cycletime)[source]

For cycle and model blending, establish the single forecast reference time to set on the cube after blending.

Parameters

  • input_cube (iris.cube.Cube) – Cube to be blended

  • cycletime (str or None) – The cycletime in a YYYYMMDDTHHMMZ format e.g. 20171122T0100Z. If None, the latest forecast reference time is used.

Returns

Forecast reference time point in units of input cube coordinate

Return type

numpy.int64

_set_coords_to_remove(input_cube)[source]

Generate a list of coordinate names associated with the blend dimension. Unless these are time-related coordinates, they should be removed after blending.

Parameters

input_cube (iris.cube.Cube) – Cube to be blended

_set_forecast_reference_time_and_period(blended_cube)[source]

For cycle and model blending, update the forecast reference time and forecast period coordinate points to the single most recent value, rather than the blended average, and remove any bounds from the forecast reference time. Modifies cube in place.

Parameters

blended_cube (iris.cube.Cube) –

_update_blended_metadata(blended_cube, attributes_dict)[source]

Update metadata after blending: - For cycle and model blending, set a single forecast reference time and period using self.cycletime_point or the latest cube contributing to the blend - Remove scalar coordinates that were previously associated with the blend dimension - Update attributes as specified via process arguments - Set any missing mandatory arguments to their default values Modifies cube in place.

Parameters
check_compatible_time_points(cube)[source]

Check that the time coordinate only contains a single time. Data varying over the blending coordinate should all be for the same validity time unless we are triangular time blending. In this case the timeblending flag should be true and this function will not raise an exception.

Parameters

cube (iris.cube.Cube) – The cube upon which the compatibility of the time coords is being checked.

Raises

ValueError – If blending over forecast reference time on a cube with multiple times.

static check_percentile_coord(cube)[source]

Determines if the cube to be blended has a percentile dimension coordinate.

Parameters

cube (iris.cube.Cube) – The cube to be checked for a percentile coordinate.

Returns

None if no percentile dimension coordinate is found. If such a coordinate is found it is returned.

Return type

iris.coords.DimCoord or None

Raises

  • ValueError – If there is a percentile coord and it is not a dimension coord in the cube.

  • ValueError – If there is a percentile dimension with only one point, we need at least two points in order to do the blending.

static check_weights(weights, blend_dim)[source]

Checks that weights across the blending dimension sum up to 1.

Parameters

  • weights (numpy.ndarray) – Array of weights shaped to match the data cube.

  • blend_dim (int) – The dimension in the weights array that is being collapsed.

Raises

ValueError – Raised if the weights do not sum to 1 over the blending dimension.

non_percentile_weights(cube, weights)[source]

Given a 1 or multidimensional cube of weights, reshape and broadcast these in such a way as to make them applicable to the data cube. If no weights are provided, an array of weights is returned that equally weights all slices across the blending coordinate of the cube.

Parameters
Returns

An array of weights that matches the cube data shape.

Return type

numpy.ndarray

percentile_weighted_mean(cube, weights, perc_coord)[source]

Blend percentile data using the weights provided.

Parameters
Returns

The cube with percentile values blended over self.blend_coord, with suitable weightings applied.

Return type

iris.cube.Cube

percentile_weights(cube, weights, perc_coord)[source]

Given a 1, or multidimensional cube of weights, reshape and broadcast these in such a way as to make them applicable to the data cube. If no weights are provided, an array of weights is returned that equally weights all slices across the blending coordinate of the cube.

For percentiles the dimensionality of the weights cube is checked against the cube without including the percentile coordinate for which no weights are likely to ever be provided (e.g. we don’t want to weight different percentiles differently across the blending coordinate). Reshape and broadcast to match the data shape excluding the percentile dimension before finally broadcasting to match at the end.

Parameters
Returns

An array of weights that matches the cube data shape.

Return type

numpy.ndarray

process(cube, weights=None, cycletime=None, attributes_dict=None)[source]
Calculate weighted blend across the chosen coord, for either

probabilistic or percentile data. If there is a percentile coordinate on the cube, it will blend using the PercentileBlendingAggregator but the percentile coordinate must have at least two points.

Parameters

  • cube (iris.cube.Cube) – Cube to blend across the coord.

  • weights (iris.cube.Cube) – Cube of blending weights. If None, the diagnostic cube is blended with equal weights across the blending dimension.

  • cycletime (str) – The cycletime in a YYYYMMDDTHHMMZ format e.g. 20171122T0100Z. This can be used to manually set the forecast reference time on the output blended cube. If not set, the most recent forecast reference time from the contributing cubes is used.

  • attributes_dict (dict or None) – Changes to cube attributes to be applied after blending. See amend_attributes() for required format. If mandatory attributes are not set here, default values are used.

Returns

containing the weighted blend across the chosen coord.

Return type

iris.cube.Cube

Raises

  • TypeError – If the first argument not a cube.

  • CoordinateNotFoundError – If coordinate to be collapsed not found in cube.

  • CoordinateNotFoundError – If coordinate to be collapsed not found in provided weights cube.

  • ValueError – If coordinate to be collapsed is not a dimension.

static shape_weights(cube, weights)[source]

The function shapes weights to match the diagnostic cube. A 1D cube of weights that vary across the blending coordinate will be broadcast to match the complete multidimensional cube shape. A multidimensional cube of weights will be checked to ensure that the coordinate names match between the two cubes. If they match the order will be enforced and then the shape will be checked. If the shapes match the weights will be returned as an array.

Parameters
Returns

An array of weights that matches the cube data shape.

Return type

numpy.ndarray

Raises

  • ValueError – If weights cube coordinates do not match the diagnostic cube in the case of a multidimensional weights cube.

  • ValueError – If weights cube shape is not broadcastable to the data cube shape.

weighted_mean(cube, weights)[source]

Blend data using a weighted mean using the weights provided.

Parameters
Returns

The cube with values blended over self.blend_coord, with suitable weightings applied.

Return type

iris.cube.Cube