improver.cli.apply_emos_coefficients module
Script to apply coefficients for Ensemble Model Output Statistics (EMOS), otherwise known as Non-homogeneous Gaussian Regression (NGR).
- process(*cubes, validity_times=None, realizations_count=None, randomise=False, random_seed=None, ignore_ecc_bounds_exceedance=False, tolerate_time_mismatch=False, predictor='mean', land_sea_mask_name=None, percentiles=None)[source]
Applying coefficients for Ensemble Model Output Statistics.
Load in arguments for applying coefficients for Ensemble Model Output Statistics (EMOS), otherwise known as Non-homogeneous Gaussian Regression (NGR). The coefficients are applied to the forecast that is supplied, so as to calibrate the forecast. The calibrated forecast is written to a cube. If no coefficients are provided the input forecast is returned unchanged.
- Parameters:
input_cubes (iris.cube.CubeList) – A list of cubes containing: - A Cube containing the forecast to be calibrated. The input format could be either realizations, probabilities or percentiles. - A cubelist containing the coefficients used for calibration or None. If none then the input, or probability template if provided, is returned unchanged. - Optionally, cubes representing static additional predictors. These static additional predictors are expected not to have a time coordinate. - Optionally, a cube containing the land-sea mask on the same domain as the forecast that is to be calibrated. Land points are specified by ones and sea points are specified by zeros. The presence of a land-sea mask will enable land-only calibration, in which sea points are returned without the application of calibration. If a land-sea mask is provided, the land_sea_mask_name must also be provided, in order to identify the land-sea mask. - Optionally, a cube containing a probability forecast that will be used as a template when generating probability output when the input format of the forecast cube is not probabilities i.e. realizations or percentiles. If no coefficients are provided and a probability template is provided, the probability template forecast will be returned as the uncalibrated probability forecast.
validity_times (List[str]) – Times at which the forecast must be valid. This must be provided as a four digit string (HHMM) where the first two digits represent the hour and the last two digits represent the minutes e.g. 0300 or 0315. If the forecast provided is at a different validity time then no coefficients will be applied.
realizations_count (int) – Option to specify the number of ensemble realizations that will be created from probabilities or percentiles when applying the EMOS coefficients.
randomise (bool) – Option to reorder the post-processed forecasts randomly. If not set, the ordering of the raw ensemble is used. This option is only valid when the input format is realizations.
random_seed (int) – Option to specify a value for the random seed for testing purposes, otherwise the default random seen behaviour is utilised. The random seed is used in the generation of the random numbers used for either the randomise option to order the input percentiles randomly, rather than use the ordering from the raw ensemble, or for splitting tied values within the raw ensemble, so that the values from the input percentiles can be ordered to match the raw ensemble.
ignore_ecc_bounds_exceedance (bool) – If True, where the percentiles exceed the ECC bounds range, raises a warning rather than an exception. This occurs when the current forecasts is in the form of probabilities and is converted to percentiles, as part of converting the input probabilities into realizations.
tolerate_time_mismatch (bool) – If True, tolerate a mismatch in validity time and forecast period for coefficients vs forecasts. Use with caution!
predictor (str) – String to specify the form of the predictor used to calculate the location parameter when estimating the EMOS coefficients. Currently the ensemble mean (“mean”) and the ensemble realizations (“realizations”) are supported as the predictors.
land_sea_mask_name (str) – Name of the land-sea mask cube. This must be provided if a land-sea mask is provided within the list of input cubes, in order to identify the land-sea mask. Providing the land-sea mask ensures that only land points will be calibrated.
percentiles (List[float]) – The set of percentiles used to create the calibrated forecast.
- Returns:
The calibrated forecast cube.
- Return type: