improver.calibration.simple_bias_correction module

Simple bias correction plugins.

class ApplyBiasCorrection(lower_bound=None, upper_bound=None, fill_masked_bias_values=False)

Bases: BasePlugin

A Plugin to apply a simple bias correction on a per member basis using the specified bias values.

__init__(lower_bound=None, upper_bound=None, fill_masked_bias_values=False)

Initialise class for applying simple bias correction.

Parameters:

• lower_bound (Optional[float]) – A lower bound below which all values will be remapped to after the bias correction step.

• upper_bound (Optional[float]) – An upper bound above which all values will be remapped to after the bias correction step.

• fill_masked_bias_values (bool) – Flag to specify whether masked areas in the bias data should be filled to an appropriate fill value.

_abc_impl = <_abc._abc_data object>

_check_forecast_bias_consistent(forecast, bias_data)

Check that forecast and bias values are defined over the same valid-hour and forecast-period.

Checks that between the bias_data Cubes there is a common hour value for the forecast_reference_time and single coordinate value for forecast_period. Then check forecast Cube contains the same hour value for the forecast_reference_time and the same forecast_period coordinate value.

Parameters:

• forecast (Cube) – Cube containing forecast data to be bias-corrected.

• bias – CubeList containing bias data to use in bias-correction.

Return type:

None

_get_mean_bias(bias_values)

Evaluate the mean bias from the input cube(s) in bias_values.

Where multiple cubes are provided, each bias value must represent a single forecast_reference_time to ensure that the resultant value is the true mean over the set of reference forecasts. This is done by checking the forecast_reference_time bounds; if a bias_value is defined over a range of frt values (ie. bounds exist) an error will be raised.

Parameters:

bias_values (CubeList) – Cubelist containing the input bias cube(s).

Return type:

Cube

Returns:

Cube containing the mean bias evaluated from set of bias_values.

_split_forecasts_and_bias(cubes)

Wrapper for the split_forecasts_and_bias_files function.

Parameters:

cubes (CubeList) – Cubelist containing the input forecast and bias cubes.

Returns:

• Cube containing the forecast data to be bias-corrected.

• Cubelist containing the bias data to use in bias-correction. Or None if no bias data is provided.

process(*cubes)

Split then apply bias correction using the specified bias values.

Where the bias data is defined point-by-point, the bias-correction will also be applied in this way enabling a form of statistical downscaling where coherent biases exist between a coarse forecast dataset and finer truth dataset.

Where a lower bound is specified, all values that fall below this lower bound (after bias correction) will be remapped to this value to ensure physically realistic values.

If fill_masked_bias_values is True, the masked areas in bias data will be filled using an appropriate fill value to leave the forecast data unchanged in the masked areas.

If no bias correction is provided, then the forecast is returned, unaltered.

Parameters:

cubes (Union[Cube, CubeList]) – A list of cubes containing: - A Cube containing the forecast to be calibrated. The input format is expected to be realizations. - A cube or cubelist containing forecast bias data over a specified set of forecast reference times. If a list of cubes is passed in, each cube should represent the forecast error for a single forecast reference time; the mean value will then be evaluated over the forecast_reference_time coordinate.

Return type:

Cube

Returns:

Bias corrected forecast cube.

class CalculateForecastBias

Bases: BasePlugin

A plugin to evaluate the forecast bias from the historical forecast and truth value(s).

__init__()

Initialise class for calculating forecast bias.

_abc_impl = <_abc._abc_data object>

_create_bias_cube(forecasts)

Create a cube to store the forecast bias data.

Where multiple reference forecasts values are provided via forecasts, the time dimension will be collapsed to a single value represented by a single forecast_reference_time with bounds set using the range of forecast_reference_time values present in forecasts.

Parameters:

forecasts (Cube) – Cube containing the reference forecasts to use in calculation of forecast bias.

Return type:

Cube

Returns:

A copy of the forecasts cube with the attributes updated to reflect the cube is the forecast error of the associated diagnostic. If a time dimension is present in the forecasts, this will be collapsed to a single value.

_define_metadata(forecasts)

Define metadata for forecast bias cube, whilst ensuring any mandatory attributes are also populated.

Parameters:

forecasts (Cube) – The source cube from which to get pre-existing metadata.

Return type:

Dict[str, str]

Returns:

A dictionary of attributes that are appropriate for the bias cube.

_ensure_single_valued_forecast(forecasts)

Check to see if an ensemble based dimension (realization, percentile, threshold) is present. If threshold dim present, or realization/percentile dimensions have multiple values a ValueError will be raised. Otherwise the percentile/realization dim coord is demoted to an aux coord.

Parameters:

forecast – Cube containing historical forecast values used in bias correction.

Return type:

Cube

Returns:

Cube with unit realization/percentile dim coords demoted to aux coordinate.

process(historic_forecasts, truths)

Evaluate forecast bias over the set of historic forecasts and associated truth values.

The historical forecasts are expected to be representative single-valued forecasts (eg. control or ensemble mean forecast). If a non-unit ensemble based dimension (realization, threshold or percentile) is present then a ValueError will be raised.

The bias here is evaluated point-by-point and the associated bias cube will retain the same spatial dimensions as the input cubes. By using a point-by-point approach, the bias-correction enables a form of statistical downscaling where coherent biases exist between a coarse forecast dataset and finer truth dataset.

Where multiple forecasts values are provided, forecasts must have consistent forecast period and valid-hour. The resultant value returned is the mean value over the set of forecast/truth pairs.

Parameters:

• historic_forecasts (Cube) – Cube containing one or more historic forecasts over which to evaluate the forecast bias.

• truths (Cube) – Cube containing one or more truth values from which to evaluate the forecast bias.

Return type:

Cube

Returns:

A cube containing the forecast bias values evaluated over the set of historic forecasts and truth values.

apply_additive_correction(forecast, bias, fill_masked_bias_values=True)

Apply additive correction to forecast using the specified bias values, where the bias is expected to be defined as forecast - truth.

Parameters:

• forecast (Cube) – Cube containing the forecast to which bias correction is to be applied.

• bias (Cube) – Cube containing the bias values to apply to the forecast.

Return type:

ndarray

Returns:

An array containing the corrected forecast values.

evaluate_additive_error(forecasts, truths, collapse_dim)

Evaluate the mean additive error (error = forecast - truth) between the forecast and truth dataset.

Parameters:

• forecasts (Cube) – Cube containing set of historic forecasts.

• truths (Cube) – Cube containing set of corresponding truth values.

• collapse_dim (str) – Dim coordinate over which to evaluate the mean value.

Return type:

ndarray

Returns:

An array containing the mean additive forecast error values.