Auxiliary functions for MLR scripts

Convenience functions for MLR diagnostics.

Functions:

check_predict_kwargs(predict_kwargs)	Check keyword argument for predict() functions.
create_alias(dataset, attributes[, delimiter])	Create alias key of a dataset using a list of attributes.
datasets_have_mlr_attributes(datasets[, ...])	Check (MLR) attributes of datasets.
get_1d_cube(x_data, y_data[, x_kwargs, y_kwargs])	Convert 2 arrays to iris.cube.Cube (with single coordinate).
get_absolute_time_units(units)	Convert time reference units to absolute ones.
get_alias(dataset)	Get alias for dataset.
get_all_weights(cube[, area_weighted, ...])	Get all desired weights for a cube.
get_area_weights(cube[, normalize])	Get area weights calculated from grid cell areas.
get_horizontal_weights(cube[, ...])	Get horizontal (latitude/longitude) weights of cube.
get_input_data(cfg[, pattern, ...])	Get input data and check MLR attributes if desired.
get_landsea_fraction_weights(cube, area_type)	Get land/sea fraction weights calculated from Natural Earth files.
get_new_path(cfg, old_path)	Convert old path to new diagnostic path.
get_squared_error_cube(ref_cube, error_datasets)	Get array of squared errors.
get_time_weights(cube[, normalize])	Get time weights of cube calculated from time bounds.
ignore_warnings()	Ignore warnings given by WARNINGS_TO_IGNORE.
square_root_metadata(cube)	Take the square root of the cube metadata.
units_power(units, power)	Raise a cf_units.Unit to given power preserving symbols.

esmvaltool.diag_scripts.mlr.check_predict_kwargs(predict_kwargs)

Check keyword argument for predict() functions.

Parameters:

predict_kwargs (keyword arguments, optional) – Keyword arguments for a predict() function.

Raises:

RuntimeError – return_var and return_cov are both set to True in the keyword arguments.

esmvaltool.diag_scripts.mlr.create_alias(dataset, attributes, delimiter='-')

Create alias key of a dataset using a list of attributes.

Parameters:

• dataset (dict) – Metadata dictionary representing a single dataset.

• attributes (list of str) – List of attributes used to create the alias.

• delimiter (str, optional (default: '-')) – Delimiter used to separate different attributes in the alias.

Returns:

Dataset alias.

Return type:

str

Raises:

AttributeError – dataset does not contain one of the attributes.

esmvaltool.diag_scripts.mlr.datasets_have_mlr_attributes(datasets, log_level='debug', mode='full')

Check (MLR) attributes of datasets.

Parameters:

• datasets (list of dict) – Datasets to check.

• log_level (str, optional (default: 'debug')) – Verbosity level of the logger.

• mode (str, optional (default: 'full')) – Checking mode. Must be one of 'only_missing' (only check if attributes are missing), 'only_var_type' (check only var_type) or 'full' (check both).

Returns:

True if all required attributes are available, False if not.

Return type:

bool

Raises:

ValueError – Invalid value for argument mode is given.

esmvaltool.diag_scripts.mlr.get_1d_cube(x_data, y_data, x_kwargs=None, y_kwargs=None)

Convert 2 arrays to iris.cube.Cube (with single coordinate).

Parameters:

• x_data (numpy.ndarray) – Data for coordinate.

• y_data (numpy.ndarray) – Data for cube.

• x_kwargs (dict) – Keyword arguments passed to iris.coords.AuxCoord.

• y_kwargs (dict) – Keyword arguments passed to iris.cube.Cube.

Returns:

1D cube with single auxiliary coordinate.

Return type:

iris.cube.Cube

Raises:

ValueError – Arrays are not 1D and do not have matching shapes.

esmvaltool.diag_scripts.mlr.get_absolute_time_units(units)

Convert time reference units to absolute ones.

This function converts reference time units (like 'days since YYYY') to absolute ones (like 'days').

Parameters:

units (cf_units.Unit) – Time units to convert.

Returns:

Absolute time units.

Return type:

cf_units.Unit

Raises:

ValueError – If conversion failed (e.g. input units are not time units).

esmvaltool.diag_scripts.mlr.get_alias(dataset)

Get alias for dataset.

Parameters:

dataset (dict) – Dataset metadata.

Returns:

Alias.

Return type:

str

esmvaltool.diag_scripts.mlr.get_all_weights(cube, area_weighted=True, time_weighted=True, landsea_fraction_weighted=None, normalize=False)

Get all desired weights for a cube.

Parameters:

• cube (iris.cube.Cube) – Input cube.

• area_weighted (bool, optional (default: True)) – Use area weights calculated from grid cell areas using iris.analysis.cartography.area_weights(). Only works for regular grids.

• time_weighted (bool, optional (default: True)) – Use time weights calculated from time bounds.

• landsea_fraction_weighted (str, optional) – If given, use land/sea fraction weights calculated from Natural Earth files. Must be one of 'land', 'sea'. Only works for regular grids.

• normalize (bool, optional (default: False)) – Normalize weights with total area and total time range.

Returns:

Area weights.

Return type:

numpy.ndarray

Raises:

• iris.exceptions.CoordinateMultiDimError – Dimension of latitude or longitude coordinate is greater than 1.

• iris.exceptions.CoordinateNotFoundError – Cube does not contain the coordinates latitude and longitude (if used with area_weighted or landsea_fraction_weighted) or cube does not contain the coordinate time (if used with time_weighted).

• ValueError – landsea_fraction_weighted is not one of None, 'land', 'sea' or coordinates latitude and longitude share dimensions.

esmvaltool.diag_scripts.mlr.get_area_weights(cube, normalize=False)

Get area weights calculated from grid cell areas.

Note

Only works for regular grids. Uses iris.analysis.cartography.area_weights() for an approximate calculation of the grid cell areas.

Parameters:

• cube (iris.cube.Cube) – Input cube.

• normalize (bool, optional (default: False)) – Normalize weights with total area.

Returns:

Area weights.

Return type:

numpy.ndarray

Raises:

iris.exceptions.CoordinateNotFoundError – Cube does not contain the coordinates latitude and longitude.

esmvaltool.diag_scripts.mlr.get_horizontal_weights(cube, area_weighted=True, landsea_fraction_weighted=None, normalize=False)

Get horizontal (latitude/longitude) weights of cube.

Parameters:

• cube (iris.cube.Cube) – Input cube.

• area_weighted (bool, optional (default: True)) – Use area weights calculated from grid cell areas using iris.analysis.cartography.area_weights(). Only works for regular grids.

• landsea_fraction_weighted (str, optional) – If given, use land/sea fraction weights calculated from Natural Earth files. Must be one of 'land', 'sea'. Only works for regular grids.

• normalize (bool, optional (default: False)) – Normalize weights with sum of weights over latitude and longitude (i.e. if only area_weighted is given, this is equal to the total area).

Returns:

Horizontal (latitude/longitude) weights.

Return type:

numpy.ndarray

Raises:

• iris.exceptions.CoordinateMultiDimError – Dimension of latitude or longitude coordinate is greater than 1.

• iris.exceptions.CoordinateNotFoundError – Cube does not contain the coordinates latitude and longitude.

• ValueError – landsea_fraction_weighted is not one of 'land', 'sea'.

esmvaltool.diag_scripts.mlr.get_input_data(cfg, pattern=None, check_mlr_attributes=True, ignore=None)

Get input data and check MLR attributes if desired.

Use input_data and ancestors to get all relevant input files.

Parameters:

• cfg (dict) – Recipe configuration.

• pattern (str, optional) – Pattern matched against ancestor file names.

• check_mlr_attributes (bool, optional (default: True)) – If True, only returns datasets with valid MLR attributes. If False, returns all found datasets.

• ignore (list of dict, optional) – Ignore specific datasets by specifying multiple dict`s of metadata. By setting an attribute to ``None`, ignore all datasets which do not have that attribute.

Returns:

List of input datasets.

Return type:

list of dict

Raises:

ValueError – No input data found or at least one dataset has invalid attributes.

esmvaltool.diag_scripts.mlr.get_landsea_fraction_weights(cube, area_type, normalize=False)

Get land/sea fraction weights calculated from Natural Earth files.

Note

The implementation of this feature is not optimal. For large cubes, calculating the land/sea fraction weights might be very slow. Only works for regular grids.

Parameters:

• cube (iris.cube.Cube) – Input cube.

• area_type (str) – Area type. Must be one of 'land' (land fraction weighting) or 'sea' (sea fraction weighting).

• normalize (bool, optional (default: False)) – Normalize weights with total land/sea fraction.

Raises:

• iris.exceptions.CoordinateMultiDimError – Dimension of latitude or longitude coordinate is greater than 1.

• iris.exceptions.CoordinateNotFoundError – Cube does not contain the coordinates latitude and longitude.

• ValueError – area_type is not one of 'land', 'sea' or coordinates latitude and longitude share dimensions.

esmvaltool.diag_scripts.mlr.get_new_path(cfg, old_path)

Convert old path to new diagnostic path.

Parameters:

• cfg (dict) – Recipe configuration.

• old_path (str) – Old path.

Returns:

New diagnostic path.

Return type:

str

esmvaltool.diag_scripts.mlr.get_squared_error_cube(ref_cube, error_datasets)

Get array of squared errors.

Parameters:

• ref_cube (iris.cube.Cube) – Reference cube (determines mask, coordinates and attributes of output).

• error_datasets (list of dict) – List of metadata dictionaries where each dictionary represents a single dataset.

Returns:

Cube containing squared errors.

Return type:

iris.cube.Cube

Raises:

ValueError – Shape of a dataset does not match shape of reference cube.

esmvaltool.diag_scripts.mlr.get_time_weights(cube, normalize=False)

Get time weights of cube calculated from time bounds.

Parameters:

• cube (iris.cube.Cube) – Input cube.

• normalize (bool, optional (default: False)) – Normalize weights with total time range.

Returns:

Time weights.

Return type:

numpy.ndarray

Raises:

iris.exceptions.CoordinateNotFoundError – Cube does not contain the coordinate time.

esmvaltool.diag_scripts.mlr.ignore_warnings()

Ignore warnings given by WARNINGS_TO_IGNORE.

esmvaltool.diag_scripts.mlr.square_root_metadata(cube)

Take the square root of the cube metadata.

Parameters:

cube (iris.cube.Cube) – Cube (will be modified in-place).

esmvaltool.diag_scripts.mlr.units_power(units, power)

Raise a cf_units.Unit to given power preserving symbols.

Raise cf_units.Unit to given power without expanding it first. For example, using units_power(Unit('J'), 2) gives Unit('J2'). In contrast, simply using Unit('J')**2 would yield 'kg2 m4 s-4'.

Parameters:

• units (cf_units.Unit) – Input units.

• power (int) – Desired exponent.

Returns:

Input units raised to given power.

Return type:

cf_units.Unit

Raises:

• TypeError – Argument power is not int-like.

• ValueError – Invalid unit given.