Iris helper functions

Auxiliary functions for iris.

Functions:

add_leading_dim_to_cube(cube, dim_coord)	Add new leading dimension to cube.
date2num(date, unit[, dtype])	Convert datetime object into numeric value with requested dtype.
merge_cube_attributes(cubes[, delimiter])	Merge attributes of all given cubes in-place.

esmvalcore.iris_helpers.add_leading_dim_to_cube(cube, dim_coord)

Add new leading dimension to cube.

An input cube with shape (x, ..., z) will be transformed to a cube with shape (w, x, ..., z) where w is the length of dim_coord. Note that the data is broadcasted to the new shape.

Parameters:

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

• dim_coord (iris.coords.DimCoord) – Dimensional coordinate that is used to describe the new leading dimension. Needs to be 1D.

Returns:

Transformed input cube with new leading dimension.

Return type:

iris.cube.Cube

Raises:

CoordinateMultiDimError – dim_coord is not 1D.

esmvalcore.iris_helpers.date2num(date, unit, dtype=<class 'numpy.float64'>)

Convert datetime object into numeric value with requested dtype.

This is a custom version of cf_units.Unit.date2num() that guarantees the correct dtype for the return value.

Parameters:

• date (datetime.datetime or cftime.datetime) –

• unit (cf_units.Unit) –

• dtype (a numpy dtype) –

Returns:

The return value of unit.date2num with the requested dtype.

Return type:

numpy.ndarray of type dtype

esmvalcore.iris_helpers.merge_cube_attributes(cubes: Sequence[Cube], delimiter: str = ' ') → None

Merge attributes of all given cubes in-place.

After this operation, the attributes of all given cubes are equal. This is useful for operations that combine cubes, such as iris.cube.CubeList.merge_cube() or iris.cube.CubeList.concatenate_cube().

Note

This function differs from iris.util.equalise_attributes() in this respect that it does not delete attributes that are not identical but rather concatenates them (sorted) using the given delimiter. E.g., the attributes exp: historical and exp: ssp585 end up as exp: historical ssp585 using the default delimiter = ' '.

Parameters:

• cubes – Input cubes whose attributes will be modified in-place.

• delimiter – Delimiter that is used to concatenate non-identical attributes.