improver.utilities.forecast_reference_enforcement module
Provides utilities for updating a forecast or forecasts based on a reference.
- class EnforceConsistentForecasts(additive_amount=0.0, multiplicative_amount=1.0, comparison_operator='>=', diff_for_warning=None)[source]
Bases:
PostProcessingPluginEnforce that the forecasts provided are no less than, no greater than, or between some linear function(s) of a reference forecast. For example, wind speed forecasts may be provided as the reference forecast for wind gust forecasts with a requirement that wind gusts are not less than 110% of the corresponding wind speed forecast. Wind speed forecasts of 10 m/s will mean that the resulting wind gust forecast will be at least 11 m/s.
- __init__(additive_amount=0.0, multiplicative_amount=1.0, comparison_operator='>=', diff_for_warning=None)[source]
Initialise class for enforcing a forecast to be either greater than or equal to, or less than or equal to a linear function of a reference forecast. Can also enforce that a forecast is between two bounds created from the reference forecast, if this is the case then a list of two elements must be provided for additive_amount, multiplicative_amount, and comparison_operator.
- Parameters:
additive_amount (
Union[float,List[float]]) – The amount to be added to the reference forecast prior to enforcing consistency between the forecast and reference forecast. If both an additive_amount and multiplicative_amount are specified then addition occurs after multiplication. This option cannot be used for probability forecasts, if it is then an error will be raised.multiplicative_amount (
Union[float,List[float]]) – The amount to multiply the reference forecast by prior to enforcing consistency between the forecast and reference forecast. If both an additive_amount and multiplicative_amount are specified then addition occurs after multiplication. This option cannot be used for probability forecasts, if it is then an error will be raised.comparison_operator (
Union[str,List[str]]) – Determines whether the forecast is enforced to be not less than or not greater than the reference forecast. Valid choices are “>=”, for not less than, and “<=” for not greater than. If provided as a list then each of “>=” and “<=” must be in the list exactly once.diff_for_warning (
Optional[float]) – If assigned, the plugin will raise a warning if any absolute change in forecast value is greater than this value.
- _abc_impl = <_abc_data object>
- static calculate_bound(cube, additive_amount, multiplicative_amount)[source]
Function to calculate a linear transformation of the reference forecast.
- Parameters:
cube (
Cube) – An iris cube.additive_amount (
float) – The amount to be added to the cube. If both an additive_amount and multiplicative_amount are specified then addition occurs after multiplication.multiplicative_amount (
float) – The amount to multiply the cube by. If both an additive_amount and multiplicative_amount are specified then addition occurs after multiplication.
- Return type:
- Returns:
A cube with identical metadata to input cube but with transformed data.
- process(forecast, reference_forecast)[source]
Function to enforce that the values in the forecast cube are not less than or not greater than a linear function of the corresponding values in reference_forecast, or between two bounds generated from two different linear functions of the reference_forecast.
- Parameters:
- Return type:
- Returns:
A forecast cube with identical metadata to forecast but the forecasts are enforced to be within the calculated bounds.
- Raises:
ValueError – If units of forecast and reference cubes are different and cannot be converted to match.
ValueError – If additive_amount and multiplicative_amount are not 0.0 and 1.0, respectively, when a probability forecast is input.
ValueError – If incorrect comparison_operator is input.
ValueError – If contradictory bounds are generated.
ValueError – If any of additive_amount, multiplicative_amount, or comparison_operator are lists when they are not all lists.
- Warns:
Warning – If difference between generated bounds and forecast is greater than diff_for_warning.
- normalise_to_reference(cubes, reference, ignore_zero_total=False)[source]
Update the data in cubes so that the sum of this data is equal to the reference cube. This is done by replacing the data in cubes with a fraction of the data in reference based upon the fraction that each cube contributes to the sum total of data in cubes.
- Parameters:
cubes (
CubeList) – Cubelist containing the cubes to be updated. Must contain at least 2 cubes.reference (
Cube) – Cube with data which the sum of cubes will be forced to be equal to.ignore_zero_total (
bool) – If False, an error will be raised if the sum total of data in input_cubes is zero where the reference cube contains a non-zero value. If True, this case will be ignored, leaving the values in the cubelist as zero rather than ensuring their total equals the corresponding value in reference cube.
- Raises:
ValueError – If length of cubes is less than 2.
ValueError – If any input cubes have a different number of dimensions to reference, or if the dimension coordinates in any of the input cubes do not match the dimension coordinates in reference.
ValueError – If there are instances where the total of the input cubes is zero but the corresponding value in reference is non-zero. This error can be ignored if ignore_zero_total is true.
- Return type:
- Returns:
Cubelist with length equal to the length of cubes. Each cube in the returned cubelist will have metadata matching the cube in the same position in input cubes, but containing different data.
- split_cubes_by_name(cubes, cube_names=None)[source]
Split a list of cubes into two lists; one containing all cubes with names which match cube_names, and the other containing all the other cubes.
- Parameters:
- Return type:
- Returns:
A cubelist containing all cubes with names which match cube_names
A cubelist containing all cubes with names which do not match cube_names