improver.blending.weights module

Module to create the weights used to blend data.

class improver.blending.weights.ChooseDefaultWeightsLinear(y0val=None, slope=0.0, ynval=None)

Bases: object

Calculate Default Weights using Linear Function.

__init__(y0val=None, slope=0.0, ynval=None)

Set up for calculating default weights using linear function

Keyword Arguments:  

• y0val (None or positive float) – Relative value of starting point.
• slope (float) – Slope of the line. Default = 0.0 (equal weights).
• ynval (float or None) – Relative weights of last point. Default value is None

slope OR ynval should be set but NOT BOTH.

If y0val value is not set or set to None then the code uses default values of y0val = 20.0 and ynval = 2.0.

equal weights when slope = 0.0 or y0val = ynval

linear_weights(num_of_weights)

Create linear weights

Parameters:

• num_of_weights (Positive Integer) – Number of weights to create.
• y0val (Positive float) – relative value of starting point. Default = 1.0
• slope (float) – slope of the line. Default = 0.0 (equal weights)
• ynval (Positive float or None) – Relative weights of last point. Default value is None

Returns:

array of weights, sum of all weights = 1.0

Return type:

weights (numpy.array)

Raises:

• ValueError – an inappropriate value of y0val is input.
• ValueError – both slope and ynval are set at input.

process(cube, coord_name, coord_vals=None, coord_unit='no_unit', weights_distrib_method='evenly')

Calculated weights for a given cube and coord.

Parameters:

• cube (iris.cube.Cube) – Cube to blend across the coord.
• coord_name (string) – Name of coordinate in the cube to be blended.
• coord_vals (string) – String list of values which are expected on the coordinate to be blended over.
• coord_unit (cf_units.Unit) – The unit in which the coord_exp_vals have been passed in.
• weights_distrib_method (string) – The method to use when redistributing weights in cases where there are some forecasts missing. Options: “evenly”, “proportional”.

Returns:

1D array of normalised (sum = 1.0) weights matching length of cube dimension to be blended

Return type:

weights (numpy.array)

Raises:

TypeError – input is not a cube

class improver.blending.weights.ChooseDefaultWeightsNonLinear(cval=0.85)

Bases: object

Calculate Default Weights using NonLinear Function.

__init__(cval=0.85)

Set up for calculating default weights using non-linear function.

Parameters:cval (float) – Value greater than 0, less than equal 1.0 default = 0.85 equal weights when cval = 1.0

nonlinear_weights(num_of_weights)

Create nonlinear weights.

Parameters:num_of_weights (Positive Integer) – Number of weights to create. Returns:array of weights, sum of all weights = 1.0 Return type:weights (numpy.array) Raises:ValueError – an inappropriate value of cval is input.

process(cube, coord_name, coord_vals=None, coord_unit='no_unit', weights_distrib_method='evenly')

Calculated weights for a given cube and coord.

Parameters:

• cube (iris.cube.Cube) – Cube to blend across the coord.
• coord_name (string) – Name of coordinate in the cube to be blended.
• coord_vals (string) – String list of values which are expected on the coordinate to be blended over.
• coord_unit (cf_units.Unit) – The unit in which the coord_exp_vals have been passed in.
• weights_distrib_method (string) – The method to use when redistributing weights in cases where there are some forecasts missing. Options: “evenly”, “proportional”.

Returns:

1D array of normalised (sum = 1.0) weights matching length of cube dimension to be blended

Return type:

weights (numpy.array)

Raises:

TypeError – input is not a cube

class improver.blending.weights.ChooseDefaultWeightsTriangular(width, units='no_unit')

Bases: object

Calculate Default Weights using a Triangular Function.

__init__(width, units='no_unit')

Set up for calculating default weights using triangular function.

Parameters:

• width (float) – The width of the triangular function from the centre point.
• units (cf_units.Unit) – The cf units of the width and midpoint.

process(cube, coord_name, midpoint)

Calculate triangular weights for a given cube and coord.

Parameters:

• cube (iris.cube.Cube) – Cube to blend across the coord.
• coord_name (string) – Name of coordinate in the cube to be blended.
• midpoint (float) – The centre point of the triangular function. This is assumed to be provided in the same units as “self.width”, ie “self.parameter_units” as initialised.

Returns:

1D array of normalised (sum = 1.0) weights matching length of cube dimension to be blended

Return type:

weights (numpy.array)

Raises:

TypeError – input is not a cube

static triangular_weights(coord_vals, midpoint, width)

Create triangular weights.

Parameters:

• coord_vals (numpy array) – An array of coordinate values that we want to calculate weights for.
• midpoint (float) – The centre point of the triangular function.
• width (float) – The width of the triangular function from the centre point.

Returns:

array of weights, sum of all weights should equal 1.0.

Return type:

weights (numpy.array)

class improver.blending.weights.ChooseWeightsLinear(weighting_coord_name, config_dict, config_coord_name='model_configuration')

Bases: object

Plugin to interpolate weights linearly to the required points, where original weights are provided as a configuration dictionary

__init__(weighting_coord_name, config_dict, config_coord_name='model_configuration')

Set up for calculating linear weights from a dictionary or input cube

Parameters:

• weighting_coord_name (str) – Standard name of the coordinate along which the weights will be interpolated. For example, if the intention is to provide weights varying with forecast period, then this argument would be “forecast_period”. This coordinate must be included within the configuration dictionary.
• config_dict (dict) – Dictionary containing the configuration information, namely an initial set of weights and information regarding the points along the specified coordinate at which the weights are valid. An example dictionary is shown below.

Keyword Arguments:  

config_coord_name (str) – Name of the coordinate used to select the configuration. For example, if the intention is to create weights that scale differently with the weighting_coord for different models, then “model_configuration” would be the config_coord.

Dictionary of format:

{
    "uk_det": {
        "forecast_period": [7, 12],
        "weights": [1, 0],
        "units": "hours"
    }
    "uk_ens": {
        "forecast_period": [7, 12, 48, 54]
        "weights": [0, 1, 1, 0]
        "units": "hours"
    }
}

_calculate_weights(cube)

Method to wrap the calls to other methods to support calculation of the weights by interpolation.

Parameters:cube (iris.cube.Cube) – Cube containing the coordinate information that will be used for setting up the interpolation and create the new weights cube. Returns:Cube containing the output from the interpolation. This has been renamed using the self.weights_key_name but otherwise matches the input cube. Return type:new_weights_cube (iris.cube.Cube)

_check_config_dict()

Check whether the items within the configuration dictionary are present and of matching lengths.

Raises:

• ValueError – If items within the configuration dictionary are not of matching lengths.
• KeyError – If the required items are not present in the configuration dictionary.

_create_new_weights_cube(cube, weights)

Create a cube to contain the output of the interpolation. It is currently assumed that the output weights matches the size of the input cube.

Parameters:

• cube (iris.cube.Cube) – Cube containing the coordinate information that will be used for setting up the new_weights_cube.
• weights (np.ndarray) – Weights calculated following interpolation.

Returns:

Cube containing the output from the interpolation. This has the same shape as “cube”, without the x and y dimensions.

Return type:

new_weights_cube (iris.cube.Cube)

_define_slice(cube)

Returns a list of coordinates over which to slice the input cube to create a list of cubes for blending.

Parameters:cube (iris.cube.Cube) – Cube input to plugin Returns:List of coordinates defining the slice to iterate over Return type:slice_list (list)

_get_interpolation_inputs_from_dict(cube)

Generate inputs required for linear interpolation.

Parameters:cube (iris.cube.Cube) – Cube containing the coordinate information that will be used for setting up the interpolation inputs. Returns:tuple containing

source_points (np.ndarray):

Points within the configuration dictionary that will be used as the input to the interpolation.

target_points (np.ndarray):

Points within the cube that will be the target points for the interpolation.

source_weights (np.ndarray):

Weights from the configuration dictionary that will be used as the input to the interpolation.

fill_value (tuple):

Values that be used if extrapolation is required. The fill values will be used as constants that are extrapolated if the target_points are outside the source_points provided. These are equal to the first and last values provided by the source weights.

Return type:(tuple)

static _interpolate_to_find_weights(source_points, target_points, source_weights, fill_value, axis=0)

Use of scipy.interpolate.interp1d to interpolate source_weights (valid at source_points) onto target_points grid. This allows the specification of an axis for the interpolation, so that the source_weights can be a multi-dimensional numpy array.

Parameters:

• source_points (np.ndarray) – Points within the configuration dictionary that will be used as the input to the interpolation.
• target_points (np.ndarray) – Points within the cube that will be the target points for the interpolation.
• source_weights (np.ndarray) – Weights from the configuration dictionary that will be used as the input to the interpolation.
• fill_value (tuple) – Values to be used if extrapolation is required. The fill values are used for target_points that are outside the source_points grid.

Keyword Arguments:  

axis (int) – Axis along which the interpolation will occur.

Returns:

Weights corresponding to target_points following interpolation.

Return type:

weights (np.ndarray)

_slice_input_cubes(cubes)

From input iris.cube.Cube or iris.cube.CubeList, create a list of cubes with different values of the config coordinate (over which to blend), with irrelevant dimensions sliced out.

Parameters:cubes (iris.cube.Cube or iris.cube.CubeList) – Cubes passed into the plugin. Returns:List of cubes (from which to calculate weights) with dimensions (y, x) if weighting_coord is scalar on the input cube, or (weighting_coord, y, x) if weighting_coord is non-scalar Return type:cubelist (iris.cube.CubeList)

process(cubes)

Calculation of linear weights based on an input dictionary.

Parameters:cubes (iris.cube.Cube or iris.cube.CubeList) – Cubes containing the coordinate (source point) information that will be used for setting up the interpolation. Each cube should have “self.config_coord_name” as a scalar dimension; if a merged cube is passed in, the plugin will split this into a list cubes. Returns:Cube containing the output from the interpolation. DimCoords (such as model_id) will be in sorted-ascending order. Return type:new_weights_cube (iris.cube.Cube)

class improver.blending.weights.WeightsUtilities

Bases: object

Utilities for Weight processing.

__init__()

Initialise class.

static build_weights_cube(cube, weights, blending_coord)

Build a cube containing weights for use in blending.

Parameters:

• cube (iris.cube.Cube) – The cube that is being blended over blending_coord.
• weights (numpy.array) – Array of weights
• blending_coord (string) – Name of the coordinate over which the weights will be used to blend data, e.g. across model name when grid blending.

Returns:

A cube containing the array of weights.

Return type:

weights_cube (iris.cube.Cube)

Raises:

ValueError – If weights array is not of the same length as the coordinate being blended over on cube.

static normalise_weights(weights, axis=None)

Ensures all weights add up to one.

Parameters:

weights (numpy.array) – array of weights

Keyword Arguments:  

axis (int) – The axis that we want to normalise along for a multiple dimensional array. Defaults to None, meaning the whole array is used for the normalisation.

Returns:

array of weights where sum = 1.0

Return type:

normalised_weights (numpy.array)

Raises:

• ValueError – any negative weights are found in input.
• ValueError – sum of weights in the input is 0.

static process_coord(cube, coordinate, coord_exp_vals=None, coord_unit='no_unit')

Calculated weights for a given cube and coord.

Parameters:

• cube (iris.cube.Cube) – Cube to blend across the coord.
• coordinate (string) – Name of coordinate in the cube to be blended.
• coord_exp_vals (string) – String list of values which are expected on the coordinate to be blended over.
• coord_unit (cf_units.Unit) – The unit in which the coord_exp_vals have been passed in.

Returns:

tuple containing:

exp_coord_len (int):

The number of forecasts we expect to blend, based on the length of the coordinate we are going to blend over.

exp_forecast_found (binary mask):

Array showing where the input cube coordinate values agree with the input expected coordinate values.

Return type:

(tuple)

Raises:

• ValueError – the coordinate to blend over does not exist on the cube being blended.
• ValueError – the length of the expected coordinate input is less than the length of the corresponding cube coordinate.
• ValueError – the input coordinate units cannot be converted to the units of the corresponding cube coordinate.

static redistribute_weights(weights, forecast_present, method='evenly')

Redistribute weights if any of the forecasts are missing.

Parameters:

• weights (numpy.ndarray) – Array of weights.
• forecast_present (numpy.ndarray) –

  Size of weights with values set as

  1.0 for present 0.0 for missing.

• method (string) –

  Method to redistribute weights, default evenly.

  Options are:

  evenly - adding the weights from the

  missing forecasts evenly across the remaining forecasts.

  proportional - re-weight according to the

  proportion of the previous weights.

Returns:

Array of weights where sum = 1.0 and missing weights are set to -1.0

Return type:

redistributed_weights (numpy.ndarray)

Raises:

• ValueError – the weights input do not add up to 1.
• ValueError – any of the input weights are negative.
• ValueError – an unexpected number of weights are input.
• ValueError – none of the forecasts expected (according to the user input coord_exp_vals) were found on the cube being blended.
• ValueError – an unknown weights redistribution method is entered (only recognised methods are ‘evenly’ and ‘proportional’).