improver.ensemble_copula_coupling.utilities module

This module defines the utilities required for Ensemble Copula Coupling plugins.

improver.ensemble_copula_coupling.utilities.choose_set_of_percentiles(no_of_percentiles, sampling='quantile')

Function to create percentiles.

Parameters

• no_of_percentiles (int) – Number of percentiles.

• 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.

  • Random: A random set of ordered percentiles.

Returns

Percentiles calculated using the sampling technique specified.

Return type

list of float

Raises

ValueError – if the sampling option is not one of the accepted options.

References

For further details, Flowerdew, J., 2014. Calibrating ensemble reliability whilst preserving spatial structure. Tellus, Series A: Dynamic Meteorology and Oceanography, 66(1), pp.1-20. Schefzik, R., Thorarinsdottir, T.L. & Gneiting, T., 2013. Uncertainty Quantification in Complex Simulation Models Using Ensemble Copula Coupling. Statistical Science, 28(4), pp.616-640.

improver.ensemble_copula_coupling.utilities.concatenate_2d_array_with_2d_array_endpoints(array_2d, low_endpoint, high_endpoint)

For a 2d array, add a 2d array as the lower and upper endpoints. The concatenation to add the lower and upper endpoints to the 2d array are performed along the second (index 1) dimension.

Parameters

• array_2d (numpy.ndarray) – 2d array of values

• low_endpoint (float or int) – Number used to create a 2d array of a constant value as the lower endpoint.

• high_endpoint (float or int) – Number of used to create a 2d array of a constant value as the upper endpoint.

Returns

2d array of values after padding with the low_endpoint and high_endpoint.

Return type

numpy.ndarray

improver.ensemble_copula_coupling.utilities.create_cube_with_percentiles(percentiles, template_cube, cube_data, cube_unit=None)

Create a cube with a percentile coordinate based on a template cube. The resulting cube will have an extra percentile coordinate compared with the template cube. The shape of the cube_data should be the shape of the desired output cube.

Parameters

• percentiles (list) – Ensemble percentiles. There should be the same number of percentiles as the first dimension of cube_data.

• template_cube (iris.cube.Cube) – Cube to copy all coordinates from. The template_cube does not contain any existing percentile coordinate. Metadata is also copied from this cube.

• cube_data (numpy.ndarray) – Data to insert into the template cube. The shape of the cube_data, excluding the dimension associated with the percentile coordinate, should be the same as the shape of template_cube. For example, template_cube shape is (3, 3, 3), whilst the cube_data is (10, 3, 3, 3), where there are 10 percentiles.

• cube_unit (cf_units.Unit) – The units of the data within the cube

Returns

Cube containing a percentile coordinate as the zeroth dimension coordinate in addition to the coordinates and metadata from the template cube.

Return type

iris.cube.Cube

improver.ensemble_copula_coupling.utilities.get_bounds_of_distribution(bounds_pairing_key, desired_units)

Gets the bounds of the distribution and converts the units of the bounds_pairing to the desired_units.

This method gets the bounds values and units from the imported dictionaries: BOUNDS_FOR_ECDF and units_of_BOUNDS_FOR_ECDF. The units of the bounds are converted to be the desired units.

Parameters

• bounds_pairing_key (str) – Name of key to be used for the BOUNDS_FOR_ECDF dictionary, in order to get the desired bounds_pairing.

• desired_units (cf_units.Unit) – Units to which the bounds_pairing will be converted.

Returns

Lower and upper bound to be used as the ends of the empirical cumulative distribution function, converted to have the desired units.

Return type

bounds_pairing (tuple)

Raises

KeyError – If the bounds_pairing_key is not within the BOUNDS_FOR_ECDF dictionary.

improver.ensemble_copula_coupling.utilities.insert_lower_and_upper_endpoint_to_1d_array(array_1d, low_endpoint, high_endpoint)

For a 1d array, add a lower and upper endpoint.

Parameters

• array_1d (numpy.ndarray) – 1d array of values

• low_endpoint (float or int) – Number of use as the lower endpoint.

• high_endpoint (float or int) – Number of use as the upper endpoint.

Returns

1d array of values padded with the low_endpoint and high_endpoint.

Return type

numpy.ndarray

improver.ensemble_copula_coupling.utilities.restore_non_probabilistic_dimensions(array_to_reshape, original_cube, input_probabilistic_dimension_name, output_probabilistic_dimension_length)

Reshape a 2d array, so that it has the dimensions of the original cube, whilst ensuring that the probabilistic dimension is the first dimension.

Parameters

• array_to_reshape (numpy.ndarray) – The array that requires reshaping.

• original_cube (iris.cube.Cube) – Cube containing the desired shape to be reshaped to, apart from the probabilistic dimension, for example, [probabilistic_dimension, time, y, x].

• input_probabilistic_dimension_name (str) – Name of the dimension within the original cube, which represents the probabilistic dimension.

• output_probabilistic_dimension_length (int) – Length of the probabilistic dimension, which will be used to create the shape to which the array_to_reshape will be reshaped to.

Returns

The array after reshaping.

Return type

numpy.ndarray

Raises

• ValueError – If the probabilistic dimension is not the first on the original_cube.

• CoordinateNotFoundError – If the input_probabilistic_dimension_name is not a coordinate on the original_cube.