improver.blending.weighted_blend module
Module containing classes for doing weighted blending by collapsing a whole dimension.
- class MergeCubesForWeightedBlending(blend_coord, weighting_coord=None, model_id_attr=None, record_run_attr=None)[source]
Bases:
BasePluginPrepares cubes for cycle and grid blending
- __init__(blend_coord, weighting_coord=None, model_id_attr=None, record_run_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 (
Optional[str]) – The coordinate across which weights will be scaled in a multi-model blend.model_id_attr (
Optional[str]) – Name of attribute used to identify model for grid blending.record_run_attr (
Optional[str]) – Name of attribute used to record models and cycles blended. Ignored if None.
- Raises:
ValueError – If trying to blend over model when model_id_attr is not set
- _abc_impl = <_abc_data 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 (
Union[List[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
- Return type:
- static _remove_blend_time(cube)[source]
If present on input, remove existing blend time coordinate (as this will be replaced on blending)
- Return type:
- static _remove_deprecation_warnings(cube)[source]
Remove deprecation warnings from forecast period and forecast reference time coordinates so that these can be merged before blending
- Return type:
- process(cubes_in, cycletime=None)[source]
Prepares merged input cube for cycle and grid blending. Makes updates to metadata (attributes and time-type coordinates) ONLY in so far as these are needed to ensure inputs can be merged into a single cube.
- Parameters:
- Return type:
- Returns:
Merged cube.
- Raises:
ValueError – If self.blend_coord is not present on all cubes (unless blending over models)
- class PercentileBlendingAggregator[source]
Bases:
objectClass 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:
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.
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.
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- static aggregate(data, axis, percentiles, arr_weights)[source]
Function to blend percentile data over a given dimension. The input percentile data must be provided with the blend coord as the first axis and the percentile coord as the second (these are re-ordered after aggregator initialisation at the start of this function). Weights data must be provided with the blend coord as the first dimension.
- Parameters:
data (
ndarray) – Array containing the data to blend.axis (
int) – The index of the coordinate dimension in the cube. This dimension will be aggregated over.percentiles (
ndarray) – Array of percentile values e.g [0, 20.0, 50.0, 70.0, 100.0], same size as the percentile (second) dimension of data.arr_weights (
ndarray) – Array of weights, same shape as data, but without the percentile dimension (weights do not vary with percentile).
Note “weights” has special meaning in Aggregator, hence using a different name for this variable.
- Return type:
- Returns:
Array 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.
- 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 (
ndarray) – Array containing the percentile values to blend, with shape: (length of coord to blend, num of percentiles)percentiles (
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 (
ndarray) – Array of weights, same size as the axis dimension of data, that we will blend over.
- Return type:
- Returns:
Array containing the weighted percentile blend data across the chosen coord
- class WeightedBlendAcrossWholeDimension(blend_coord, timeblending=False)[source]
Bases:
PostProcessingPluginApply 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_impl = <_abc_data object>
- static _normalise_weights(weights)[source]
Checks that weights across the leading blend dimension sum up to 1. If not, normalise across the blending dimension ignoring any points at which the sum of weights is zero.
- 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 (
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.
- Return type:
- static check_percentile_coord(cube)[source]
Determines if the cube to be blended has a percentile dimension coordinate.
- Parameters:
cube (
Cube) – The cube to be checked for a percentile coordinate.- Return type:
- Returns:
True if there is a multi-valued percentile dimension; False if not
- 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.
- get_weights_array(cube, weights)[source]
Given a 1 or multidimensional cube of weights, reshape and broadcast these to the shape of the data cube. If no weights are provided, an array of weights is returned that equally weights all slices across the blending coordinate.
- percentile_weighted_mean(cube, weights)[source]
Blend percentile data using the weights provided.
- Parameters:
- Return type:
- Returns:
The cube with percentile values blended over self.blend_coord, with suitable weightings applied.
- process(cube, weights=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 (
Cube) – Cube to blend across the coord.weights (
Optional[Cube]) – Cube of blending weights. This will have 1 or 3 dimensions, corresponding either to blend dimension on the input cube with or without and additional 2 spatial dimensions. If None, the input cube is blended with equal weights across the blending dimension.
- Return type:
- Returns:
Containing the weighted blend across the chosen coordinate (typically forecast reference time or model).
- 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 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:
- Return type:
- Returns:
An array of weights that matches the cube data shape.
- 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.