improver.cli.generate_percentiles module
Script to collapse cube coordinates and calculate percentiled data.
- process(cube, *, coordinates=None, percentiles=None, ignore_ecc_bounds_exceedance=False, skip_ecc_bounds=False, mask_percentiles=False, optimal_crps_percentiles=False)[source]
Collapses cube coordinates and calculate percentiled data.
Calculate percentiled data over a given coordinate by collapsing that coordinate. Typically used to convert realization data into percentiled data, but may calculate over any dimension coordinate. If no coordinate for collapsing over is provided, the realization data will instead be rebadged as percentile data. Alternatively calling this with a dataset containing probabilities will convert those to percentiles using the ensemble copula coupling plugin. If no particular percentiles are given at which to calculate values and no ‘number of percentiles’ to calculate are specified, the following defaults will be used. ‘[0, 5, 10, 20, 25, 30, 40, 50, 60, 70, 75, 80, 90, 95, 100]’
- Parameters:
cube (iris.cube.Cube) – A Cube for processing.
coordinates (str or list) – Coordinate or coordinates over which to collapse data and calculate percentiles; e.g. ‘realization’ or ‘latitude,longitude’. This argument must be provided when collapsing a coordinate or coordinates to create percentiles, but is redundant when converting probabilities to percentiles and may be omitted. Not providing the coordinate(s) with realization data will cause the realizations to be rebadged as percentiles instead. This coordinate(s) will be removed and replaced by a percentile coordinate.
percentiles (list) – Optional definition of percentiles at which to calculate data.
ignore_ecc_bounds_exceedance (bool) – If True, where calculated percentiles are outside the ECC bounds range, raises a warning rather than an exception.
skip_ecc_bounds (bool) – If True, ECC bounds are not included when probabilities are converted to percentiles. 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.
mask_percentiles (bool) – A boolean determining whether the final percentiles should be masked. If True then where the percentile is higher than the probability of the diagnostic existing the outputted percentile will be masked. This masking acts to cap the maximum percentile that can be generated for any grid point relative to the probability of exceeding the highest threshold at that point. For example, if the probability of a temperature exceeding 40C is 5%, the 95th and above percentiles will all be masked. Likewise, if at some grid point the probability of the cloud base being below 15000m (the highest threshold) is 70% then every percentile above the 70th would be masked. This is only implemented to work when converting probabilities to percentiles.
optimal_crps_percentiles (bool) – If True, percentiles are computed following the recommendation of Bröcker, 2012 for optimising the CRPS using the equation: q = (i-0.5)/N, i=1,…,N, where N is the number of realizations. If False, percentiles are computed as equally spaced following the equation: q = i/(1+N), i=1,…,N. Defaults to False.
- Returns:
The processed Cube.
- Return type:
- Raises:
ValueError – If the cube name does not contain ‘probability_of_’ and coordinates isn’t used.
- Warns:
Warning – If ‘probability_of_’ is in the cube name and coordinates is used.
Warning – If ‘probability_of_’ is not in the cube name and mask_percentiles is True.