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_regular_grid(cube)

Check if a cube has a regular 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.

safe_convert_units(cube, units)

Safe unit conversion (change of standard_name not allowed; in-place).
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:
Returns:

Transformed input cube with new leading dimension.

Return type:

iris.cube.Cube

Raises:

iris.exceptions.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:
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.

“Irregular” refers to a general curvilinear grid with 2D latitude and 2D longitude coordinates with common dimensions.

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

Check if a cube has a regular grid.

“Regular” refers to a rectilinear grid with 1D latitude and 1D longitude coordinates orthogonal to each other.

Parameters:

cube (Cube) – Cube to be checked.

Returns:

True if input cube has a regular grid, else False.

Return type:

bool

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

Check if a cube has an unstructured grid.

“Unstructured” refers to a grid with 1D latitude and 1D longitude coordinates with common dimensions (i.e., a simple list of points).

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 cube should not be chunked.

  • 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:

iris.cube.Cube

esmvalcore.iris_helpers.safe_convert_units(cube: Cube, units: str | Unit) → Cube[source]#

Safe unit conversion (change of standard_name not allowed; in-place).

This is a safe version of esmvalcore.preprocessor.convert_units() that will raise an error if the input cube’s standard_name has been changed.

Parameters:

  • cube (Cube) – Input cube (modified in place).

  • units (str | Unit) – New units.

Returns:

Converted cube. Just returned for convenience; input cube is modified in place.

Return type:

iris.cube.Cube

Raises: