improver.calibration.simple_bias_correction module

Simple bias correction plugins.

class ApplyBiasCorrection[source]

Bases: BasePlugin

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

__init__()[source]: Initialise class for applying simple bias correction.

_abc_impl = <_abc_data object>

_check_forecast_bias_consistent(forecast, bias_data)[source]

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

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)[source]

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.

process(forecast, bias, lower_bound=None, upper_bound=None, fill_masked_bias_values=False)[source]

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.

Parameters:

forecast (Cube) – The cube to which bias correction is to be applied.
bias (CubeList) – The cubelist containing the bias values for which to use in the bias correction.
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 (Optional[bool]) – Flag to specify whether masked areas in the bias data should be filled to an appropriate fill value.

Return type:

Cube

Returns:

Bias corrected forecast cube.

class CalculateForecastBias[source]

Bases: BasePlugin

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

__init__()[source]: Initialise class for calculating forecast bias.

_abc_impl = <_abc_data object>

_create_bias_cube(forecasts)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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.