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.
`has_irregular_grid`(cube)	Check if a cube has an irregular grid.
`has_unstructured_grid`(cube)	Check if a cube has an unstructured grid.
`merge_cube_attributes`(cubes[, delimiter])	Merge attributes of all given cubes in-place.
`rechunk_cube`(cube, complete_coords[, ...])	Rechunk cube so that it is not chunked along given dimensions.

esmvalcore.iris_helpers.add_leading_dim_to_cube(cube, dim_coord)[source]#

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

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.has_irregular_grid(cube: Cube) → bool[source]#

Check if a cube has an irregular grid.

Parameters:: cube (Cube) – Cube to be checked.
Returns:: True if input cube has an irregular grid, else False.
Return type:: bool

esmvalcore.iris_helpers.has_unstructured_grid(cube: Cube) → bool[source]#

Check if a cube has an unstructured grid.

Parameters:: cube (Cube) – Cube to be checked.
Returns:: True if input cube has an unstructured grid, else False.
Return type:: bool

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

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 (Sequence[Cube]) – Input cubes whose attributes will be modified in-place.
delimiter (str) – Delimiter that is used to concatenate non-identical attributes.

Return type:

None

esmvalcore.iris_helpers.rechunk_cube(cube: Cube, complete_coords: Iterable[Coord | str], remaining_dims: int | Literal['auto'] = 'auto') → Cube[source]#

Rechunk cube so that it is not chunked along given dimensions.

This will rechunk the cube’s data, but also all non-dimensional coordinates, cell measures, and ancillary variables that span at least one of the given dimensions.

Note

This will only rechunk dask arrays. numpy arrays are not changed.

Parameters:

cube (Cube) – Input cube.
complete_coords (Iterable[Coord | str]) – (Names of) coordinates along which the output cubes should not be chunked. The given coordinates must span exactly 1 dimension.
remaining_dims (int | Literal['auto']) – Chunksize of the remaining dimensions.

Returns:

Rechunked cube. This will always be a copy of the input cube.

Return type:

Cube