improver.utilities.mathematical_operations module

Module to contain mathematical operations.

class CalculateClimateAnomalies(ignore_temporal_mismatch=False)

Bases: BasePlugin

Utility functionality to convert an input cube of data to a cube containing anomaly data. If a forecast and a climatological mean are supplied, the anomaly calculated will be forecast - mean. If the climatological standard deviation is also supplied, then a standardized anomaly is calculated as (forecast - mean) / standard deviation

__init__(ignore_temporal_mismatch=False)

Initialise class.

Parameters:

ignore_temporal_mismatch (bool) – If True, ignore mismatch in time coordinates between the input cubes. Default is False. Set to True when converting to the anomaly of a diagnostic cube relative to mean and standard deviation cubes of a different period.

_abc_impl = <_abc._abc_data object>

static _add_reference_epoch_metadata(output_cube, mean_cube)

Add epoch metadata to describe the creation of the anomaly. 1. Add a scalar coordinate ‘reference epoch’ to describe the time period over which the climatology was calculated. The time bounds are inherited from the mean cube. 2. Add a cell method called ‘anomaly’ to describe the operation that was performed.

The output_cube is modified in place.

Return type:

None

_create_output_cube(diagnostic_cube, mean_cube, std_cube=None)

Create a final anomalies cube by copying the diagnostic cube, updating its data with the anomalies data, and updating its metadata.

Return type:

Cube

static _update_cube_name_and_units(output_cube, standardized_anomaly=False)

This method updates the name and units of the given output cube based on whether it represents a standardized anomaly or not. The cube is modified in place.

Parameters:

• output_cube (Cube) – The cube to be updated.

• standardized_anomaly (bool) – Flag indicating if the output is a standardized anomaly. If True, a “_standardized_anomaly” suffix is added to the name and units are made dimensionless (‘1’). If False, an “_anomaly” suffix is added to the name and units are unchanged.

Return type:

None

static calculate_anomalies(diagnostic_cube, mean_cube, std_cube=None)

Calculate climate anomalies from the input cubes.

Return type:

ndarray

process(diagnostic_cube, mean_cube, std_cube=None)

Calculate anomalies from the input cubes.

Parameters:

• diagnostic_cube (Cube) – Cube containing the data to be converted to anomalies.

• mean_cube (Cube) – Cube containing the mean data to be used for the calculation of anomalies.

• std_cube (Optional[Cube]) – Cube containing the standard deviation data to be used for the calculation of standardized anomalies. If not provided, only anomalies (not standardized anomalies) will be calculated.

Returns:

• Name is updated to include “_anomaly” or “_standardized_anomaly” suffix.

• Units are updated to “1” for standardized anomalies.

• A reference epoch coordinate and an “anomaly” cell method are added.

Return type:

Cube containing the result of the calculation with updated metadata

static verify_units_match(diagnostic_cube, mean_cube, std_cube=None)

Check that all cubes have the same units. E.g. to prevent accidental use of cubes with rate data with cubes with accumulation data.

Raises:

• ValueError – If the mean and diagnostic cubes have different units.

• ValueError – If the standard deviation (if supplied) and diagnostic cubes

• have different units. –

Return type:

None

class CalculateForecastValueFromClimateAnomaly(ignore_temporal_mismatch=False)

Bases: BasePlugin

Utility functionality to convert an input cube containing anomaly data to a forecast value cube. If a climatological anomaly and mean are supplied, the forecast values will be calculated by anomaly + mean. If the anomaly is standardized and a standard deviation and mean are supplied, the forecast values will be calculated by (standardized anomaly * standard deviation) + mean.

__init__(ignore_temporal_mismatch=False)

Initialise class.

Parameters:

ignore_temporal_mismatch (bool) – If True, ignore mismatch in time coordinates between the input cubes. Default is False. Set to True when converting from the anomaly of a diagnostic cube relative to mean and standard deviation cubes of a different period.

_abc_impl = <_abc._abc_data object>

_create_output_cube(anomaly_cube, mean_cube, std_cube=None)

Create a final forecast value cube by copying the anomaly cube, updating its data with the forecast values data, and updating its metadata. The replaced metadata would be present on any anomaly cube processed through the plugin CalculateClimateAnomalies and is no longer necessary.

Return type:

Cube

static _remove_reference_epoch_metadata(output_cube)

Remove the reference epoch coordinate and cell method from the output cube if present. The cube is modified in place.

Parameters:

output_cube (Cube) – The cube from which to remove the reference epoch metadata.

Return type:

None

static _update_cube_name_and_units(output_cube, mean_cube)

Set standard_name, long_name, and units on the output_cube using the mean_cube.

Parameters:

output_cube (Cube) – The cube to be updated.

Return type:

None

static calculate_forecast_value(anomaly_cube, mean_cube, std_cube=None)

Calculate forecast values from the input cubes.

Return type:

ndarray

process(anomaly_cube, mean_cube, std_cube=None)

Calculate forecast values from the input cubes.

Parameters:

• anomaly_cube (Cube) – Cube containing the data to be converted to forecast values.

• mean_cube (Cube) – Cube containing the mean data to be used for the calculation of forecast values.

• std_cube (Cube) – Cube containing the standard deviation data to be used for the calculation of forecast values from standardized anomalies. If not provided, only anomalies (not standardized anomalies) should be provided to calculate the forecast values.

Returns:

• Name is updated to remove “_anomaly” or “_standardized_anomaly” suffix.

• Units are converted to the units of the mean cube, if required.

• The reference epoch coordinate and “anomaly” cell method are removed.

Return type:

Cube containing the result of the calculation with updated metadata

static verify_inputs_for_forecast(standardized_anomaly, std_cube=None)

Check that all required inputs are provided for the type of anomaly data (standardized or unstandardized) used. If the anomaly cube is standardized, the standard deviation cube must be provided. If the anomaly cube is not standardized, the standard deviation cube must not be provided. This is to prevent accidental use of standardized anomaly data when the standard deviation is not available.

Raises:

• ValueError – If the anomaly cube is standardized and the standard deviation

• cube is not provided. –

• ValueError – If the anomaly cube is not standardized and the

• standard deviation cube is provided. –

Return type:

None

static verify_units_match(anomaly_cube, mean_cube, standardized_anomaly, std_cube=None)

Check that all required inputs are provided and all cubes have the same units. E.g. to prevent accidental use of cubes with rate data with cubes with accumulation data.

Raises:

• ValueError – If the units of the cubes do not match.

• ValueError – If the cubes are not compatible with the anomaly cube.

Return type:

None

class Integration(coord_name_to_integrate, start_point=None, end_point=None, positive_integration=False)

Bases: BasePlugin

Perform integration along a chosen coordinate. This class currently supports the integration of positive values only, in order to support its usage as part of computing the wet-bulb temperature integral. Generalisation of this class to support standard numerical integration can be undertaken, if required.

__init__(coord_name_to_integrate, start_point=None, end_point=None, positive_integration=False)

Initialise class.

Parameters:

• coord_name_to_integrate (str) – Name of the coordinate to be integrated.

• start_point (Optional[float]) – Point at which to start the integration. Default is None. If start_point is None, integration starts from the first available point.

• end_point (Optional[float]) – Point at which to end the integration. Default is None. If end_point is None, integration will continue until the last available point.

• positive_integration (bool) – Description of the direction in which to integrate. True corresponds to the values within the array increasing as the array index increases. False corresponds to the values within the array decreasing as the array index increases.

_abc_impl = <_abc._abc_data object>

_create_output_cube(template, data, points, bounds)

Populates a template cube with data from the integration

Parameters:

• template (Cube) – Copy of upper or lower bounds cube, based on direction of integration

• data (Union[List[float], ndarray]) – Integrated data

• points (Union[List[float], ndarray]) – Points values for the integrated coordinate. These will not match the template cube if any slices were skipped in the integration, and therefore are used to slice the template cube to match the data array.

• bounds (Union[List[float], ndarray]) – Bounds values for the integrated coordinate

Return type:

Cube

Returns:

Cube with data from integration

_generate_output_name_and_units()

Gets suitable output name and units from input cube metadata

Return type:

Tuple[str, str]

ensure_monotonic_increase_in_chosen_direction(cube)

Ensure that the chosen coordinate is monotonically increasing in the specified direction.

Parameters:

cube (Cube) – The cube containing the coordinate to check. Note that the input cube will be modified by this method.

Return type:

Cube

Returns:

The cube containing a coordinate that is monotonically increasing in the desired direction.

perform_integration(upper_bounds_cube, lower_bounds_cube)

Perform the integration.

Integration is performed by firstly defining the stride as the difference between the upper and lower bound. The contribution from the uppermost half of the stride is calculated by multiplying the upper bound value by 0.5 * stride, and the contribution from the lowermost half of the stride is calculated by multiplying the lower bound value by 0.5 * stride. The contribution from the uppermost half of the stride and the bottom half of the stride is summed.

Integration is performed ONLY over positive values.

Parameters:

• upper_bounds_cube (Cube) – Cube containing the upper bounds to be used during the integration.

• lower_bounds_cube (Cube) – Cube containing the lower bounds to be used during the integration.

Return type:

Cube

Returns:

Cube containing the output from the integration.

prepare_for_integration()

Prepare for integration by creating the cubes needed for the integration. These are separate cubes for representing the upper and lower limits of the integration.

Return type:

Tuple[Cube, Cube]

Returns:

• Cube containing the upper bounds to be used during the integration.

• Cube containing the lower bounds to be used during the integration.

process(cube)

Integrate data along a specified coordinate. Only positive values are integrated; zero and negative values are not included in the sum or as levels on the integrated cube.

Parameters:

cube (Cube) – Cube containing the data to be integrated.

Return type:

Cube

Returns:

The cube containing the result of the integration. This will have the same name and units as the input cube (TODO same name and units are incorrect - fix this).

fast_linear_fit(x_data, y_data, axis=None, keepdims=False, gradient_only=False, with_nan=False)

Uses a simple linear fit approach to calculate the gradient along specified axis (default is to fit all points). Uses vectorized operations, so it’s much faster than using scipy lstsq in a loop. This function does not handle NaNs, but will work with masked arrays.

Parameters:

• x_data (ndarray) – x axis data.

• y_data (ndarray) – y axis data.

• axis (Union[int, Tuple[int, ...], None]) – Optional argument, specifies the axis to operate on. Default is to flatten arrays and fit all points.

• keepdims (bool) – If this is set to True, the axes which are reduced are left in the result as dimensions with size one. With this option, the result will broadcast correctly against the input array.

• gradient_only (bool) – If true only returns the gradient.

• with_nan (bool) – If true, there are NaNs in your data (that you know about).

Return type:

Tuple[ndarray, ndarray]

Returns:

tuple with first element being the gradient between x and y, and the second element being the calculated y-intercepts.

verify_time_coords_match(diagnostic_cube, mean_cube, std_cube=None, ignore_temporal_mismatch=False)

Check that all cubes have compatible time coordinates.

Parameters:

• diagnostic_cube (Cube) – Cube containing the diagnostic or anomaly data.

• mean_cube (Cube) – Cube containing the mean data.

• std_cube (Optional[Cube]) – Cube containing the standard deviation data (optional).

• ignore_temporal_mismatch (bool) – If True, ignore mismatch in time coordinates between the input cubes.

Raises:

ValueError – If the time coordinates of the cubes are incompatible.

Return type:

None