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)[source]

Check keyword argument for predict() functions.

Parameters

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

Raises

RuntimeErrorreturn_var and return_cov are both set to True in the keyword arguments.

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

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

AttributeErrordataset does not contain one of the attributes.

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

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)[source]

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

Parameters
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)[source]

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)[source]

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)[source]

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

  • ValueErrorlandsea_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)[source]

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)[source]

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
esmvaltool.diag_scripts.mlr.get_input_data(cfg, pattern=None, check_mlr_attributes=True, ignore=None)[source]

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)[source]

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
esmvaltool.diag_scripts.mlr.get_new_path(cfg, old_path)[source]

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)[source]

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)[source]

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()[source]

Ignore warnings given by WARNINGS_TO_IGNORE.

esmvaltool.diag_scripts.mlr.square_root_metadata(cube)[source]

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)[source]

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
Returns

Input units raised to given power.

Return type

cf_units.Unit

Raises