improver.cli.generate_realizations module

Contents

improver.cli.generate_realizations module#

Convert NetCDF files to realizations.

process(cube, raw_cube=None, *, realizations_count=None, sampling='quantile', random_seed=None, tie_break='random', ensure_evenly_spaced_realizations=True, ignore_ecc_bounds_exceedance=False, skip_ecc_bounds=False, distribution='gamma', nan_mask_value=0.0, scale_percentiles_to_probability_lower_bound=False)[source]#

Converts an incoming cube into one containing realizations.

Parameters:

  • cube (iris.cube.Cube) –

    A cube to be processed. Must contain either:

    • A realization dimension (returned unchanged), or

    • A percentile coordinate (resampled and optionally reordered), or

    • Probabilities (converted to percentiles, then resampled and

      optionally reordered).

  • raw_cube (iris.cube.Cube) – Cube of raw (not post processed) weather data. If this argument is given ensemble realizations will be created from percentiles by reshuffling them in correspondence to the rank order of the raw ensemble. Otherwise, the percentiles are rebadged as realizations. If the sampling option is set to “transformation”, this cube will be used to fit a distribution to the data at each grid point, and the percentiles will be generated from this distribution.

  • realizations_count (int) – The number of ensemble realizations in the output.

  • sampling (str) –

    Type of sampling of the distribution to produce a set of percentiles e.g. quantile or random.

    Accepted options for sampling are:

    • Quantile: A regular set of equally-spaced percentiles aimed

      at dividing a Cumulative Distribution Function into blocks of equal probability. This is the default option.

    • Random: A random set of ordered percentiles.

    • Transformation: Percentiles are generated by fitting a

      distribution to the data. This generates a different set of percentiles at each grid point, based on the local distribution of probabilities. Follows Schefzik et al., 2013.

  • random_seed (int) – Option to specify a value for the random seed when reordering percentiles. This value is for testing purposes only, to ensure reproduceable outputs. It should not be used in real time operations as it may introduce a bias into the reordered forecasts.

  • tie_break (str) – Option to specify the tie breaking method when reordering percentiles. The available methods are “random” (default), to tie-break randomly, and “realization”, to tie-break by assigning values to the highest numbered realizations first.

  • ensure_evenly_spaced_realizations (bool) – If True, the plugin will ensure that the output realizations are evenly spaced in percentile space are centered on the 50th percentile, and partition the space. If False, no check is performed. True is the default.

  • ignore_ecc_bounds_exceedance (bool) – If True where percentiles (calculated as an intermediate output before realization) exceed the ECC bounds range, raises a warning rather than an exception. False is the default.

  • skip_ecc_bounds (bool) – If True, ECC bounds are not included either when percentiles are resampled as an intermediate step prior to creating realizations or when probabilities are converted to percentiles as an intermediate step prior to creating realizations. This has the effect that percentiles outside of the range given by the input percentiles will be computed by nearest neighbour interpolation from the nearest available percentile, rather than using linear interpolation between the nearest available percentile and the ECC bound. False is the default.

  • distribution (str) – Valid if the “transformation” option is selected for sampling the probability distribution. Type of distribution to fit (currently only ‘gamma’ is supported).

  • nan_mask_value (float) – Valid if the “transformation” option is selected for sampling the probability distribution. Value to mask as NaN before calculating mean and std. This option might be most useful for a diagnostic, such as precipitation rate, where there is a high frequency of zero values. If None, no masking is performed. Default is 0.0.

  • scale_percentiles_to_probability_lower_bound (bool) – Valid if the “transformation” option is selected for sampling the probability distribution. If True, the minimum value of the calculated percentiles will be set to the minimum CDF probability implied by the input probabilities, rather than zero. This has the effect of restricting the percentiles to the non-zero part of the distribution, which is useful when there is a high probability of zero values (e.g., for precipitation). When False, percentiles are calculated over the full [0, 1] range, regardless of the input probabilities. Default is False.

Returns:

The processed cube.

Return type:

iris.cube.Cube

Raises:

  • ValueError – If the input cube does not contain a percentile coordinate or probability coordinates that can then be converted to a realization coordinate.

  • ValueError – If neither realizations_count nor raw_cube is provided.

Contents

This Page