improver.ensemble_copula_coupling.ensemble_copula_coupling_utilities module

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

improver.ensemble_copula_coupling.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 (String) –

  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:

percentiles (List)

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.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.array) – 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:

array_2d (numpy.array)

improver.ensemble_copula_coupling.ensemble_copula_coupling_utilities.create_cube_with_percentiles(percentiles, template_cube, cube_data, custom_name=None, 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 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.array) – 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.

Returns:

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

Return type:

result (Iris.cube.Cube)

improver.ensemble_copula_coupling.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 (String) – 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)

improver.ensemble_copula_coupling.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.array) – 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:

array_1d (numpy.array)

improver.ensemble_copula_coupling.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.array) – 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 (String) – 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.array