# Iris helper functions

Auxiliary functions for [`iris`](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.html#module-iris).

**Functions:**

| [`add_leading_dim_to_cube`](#esmvalcore.iris_helpers.add_leading_dim_to_cube)(cube, dim_coord)      | Add new leading dimension to cube.                                                                                               |
|------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------|
| [`dataset_to_iris`](#esmvalcore.iris_helpers.dataset_to_iris)(dataset[, filepath, ...])     | Convert dataset to [`CubeList`](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.cube.html#iris.cube.CubeList). |
| [`date2num`](#esmvalcore.iris_helpers.date2num)(date, unit[, dtype])                 | Convert datetime object into numeric value with requested dtype.                                                                 |
| [`has_irregular_grid`](#esmvalcore.iris_helpers.has_irregular_grid)(cube)                      | Check if a cube has an irregular grid.                                                                                           |
| [`has_regular_grid`](#esmvalcore.iris_helpers.has_regular_grid)(cube)                        | Check if a cube has a regular grid.                                                                                              |
| [`has_unstructured_grid`](#esmvalcore.iris_helpers.has_unstructured_grid)(cube)                   | Check if a cube has an unstructured grid.                                                                                        |
| [`ignore_iris_vague_metadata_warnings`](#esmvalcore.iris_helpers.ignore_iris_vague_metadata_warnings)()         | Ignore specific warnings.                                                                                                        |
| [`ignore_warnings_context`](#esmvalcore.iris_helpers.ignore_warnings_context)([warnings_to_ignore]) | Ignore warnings (context manager).                                                                                               |
| [`merge_cube_attributes`](#esmvalcore.iris_helpers.merge_cube_attributes)(cubes[, delimiter])     | Merge attributes of all given cubes in-place.                                                                                    |
| [`rechunk_cube`](#esmvalcore.iris_helpers.rechunk_cube)(cube, complete_coords[, ...])    | Rechunk cube so that it is not chunked along given dimensions.                                                                   |
| [`safe_convert_units`](#esmvalcore.iris_helpers.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: Cube, dim_coord: DimCoord) → Cube

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** (*Cube*) – Input cube.
  * **dim_coord** (*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](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.cube.html#iris.cube.Cube)
* **Raises:**
  [**iris.exceptions.CoordinateMultiDimError**](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.exceptions.html#iris.exceptions.CoordinateMultiDimError) – `dim_coord` is not 1D.

### esmvalcore.iris_helpers.dataset_to_iris(dataset: xr.Dataset | [ncdata.NcData](https://ncdata.readthedocs.io/en/stable/details/api/ncdata.html#ncdata.NcData), filepath: [str](https://docs.python.org/3/builtins/stdtypes.html#str) | Path | [None](https://docs.python.org/3/builtins/constants.html#None) = None, ignore_warnings: [list](https://docs.python.org/3/builtins/stdtypes.html#list)[[dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), Any]] | [None](https://docs.python.org/3/builtins/constants.html#None) = None) → [iris.cube.CubeList](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.cube.html#iris.cube.CubeList)

Convert dataset to [`CubeList`](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.cube.html#iris.cube.CubeList).

* **Parameters:**
  * **dataset** (*xr.Dataset* *|* [*ncdata.NcData*](https://ncdata.readthedocs.io/en/stable/details/api/ncdata.html#ncdata.NcData)) – The dataset object to convert.
  * **filepath** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str) *|* *Path* *|* *None*) – The path that the dataset was loaded from.
  * **ignore_warnings** ([*list*](https://docs.python.org/3/builtins/stdtypes.html#list) *[*[*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict) *[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str) *,* *Any* *]* *]*  *|* *None*) – Keyword arguments passed to [`warnings.filterwarnings()`](https://docs.python.org/3/library/warnings.html#warnings.filterwarnings) used to
    ignore warnings during data loading. Each list element corresponds
    to one call to [`warnings.filterwarnings()`](https://docs.python.org/3/library/warnings.html#warnings.filterwarnings).
* **Returns:**
  [`CubeList`](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.cube.html#iris.cube.CubeList) containing the requested cubes.
* **Return type:**
  [iris.cube.CubeList](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.cube.html#iris.cube.CubeList)
* **Raises:**
  [**TypeError**](https://docs.python.org/3/builtins/exceptions.html#TypeError) – Invalid type for `dataset` given.

### 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()`](https://cf-units.readthedocs.io/en/stable/unit.html#cf_units.Unit.date2num) that
guarantees the correct dtype for the return value.

* **Parameters:**
  * **date** ([`datetime.datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime) or [`cftime.datetime`](https://unidata.github.io/cftime/api.html#cftime.datetime))
  * **unit** ([`cf_units.Unit`](https://cf-units.readthedocs.io/en/stable/unit.html#cf_units.Unit))
  * **dtype** (*a numpy dtype*)
* **Returns:**
  The return value of `unit.date2num` with the requested dtype.
* **Return type:**
  [`numpy.ndarray`](https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html#numpy.ndarray) of type dtype

### esmvalcore.iris_helpers.has_irregular_grid(cube: [Cube](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.cube.html#iris.cube.Cube)) → [bool](https://docs.python.org/3/builtins/functions.html#bool)

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*](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.cube.html#iris.cube.Cube)) – Cube to be checked.
* **Returns:**
  `True` if input cube has an irregular grid, else `False`.
* **Return type:**
  [bool](https://docs.python.org/3/builtins/functions.html#bool)

### esmvalcore.iris_helpers.has_regular_grid(cube: [Cube](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.cube.html#iris.cube.Cube)) → [bool](https://docs.python.org/3/builtins/functions.html#bool)

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*](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.cube.html#iris.cube.Cube)) – Cube to be checked.
* **Returns:**
  `True` if input cube has a regular grid, else `False`.
* **Return type:**
  [bool](https://docs.python.org/3/builtins/functions.html#bool)

### esmvalcore.iris_helpers.has_unstructured_grid(cube: [Cube](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.cube.html#iris.cube.Cube)) → [bool](https://docs.python.org/3/builtins/functions.html#bool)

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*](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.cube.html#iris.cube.Cube)) – Cube to be checked.
* **Returns:**
  `True` if input cube has an unstructured grid, else `False`.
* **Return type:**
  [bool](https://docs.python.org/3/builtins/functions.html#bool)

### esmvalcore.iris_helpers.ignore_iris_vague_metadata_warnings() → Generator[[None](https://docs.python.org/3/builtins/constants.html#None)]

Ignore specific warnings.

This can be used as a context manager. See also
[https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.warnings.html#iris.warnings.IrisVagueMetadataWarning](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.warnings.html#iris.warnings.IrisVagueMetadataWarning).

* **Return type:**
  Generator[None]

### esmvalcore.iris_helpers.ignore_warnings_context(warnings_to_ignore: [list](https://docs.python.org/3/builtins/stdtypes.html#list)[[dict](https://docs.python.org/3/builtins/stdtypes.html#dict)[[str](https://docs.python.org/3/builtins/stdtypes.html#str), Any]] | [None](https://docs.python.org/3/builtins/constants.html#None) = None) → Generator[[None](https://docs.python.org/3/builtins/constants.html#None)]

Ignore warnings (context manager).

* **Parameters:**
  **warnings_to_ignore** ([*list*](https://docs.python.org/3/builtins/stdtypes.html#list) *[*[*dict*](https://docs.python.org/3/builtins/stdtypes.html#dict) *[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str) *,* *Any* *]* *]*  *|* *None*) – Additional warnings to ignore (by default, Iris warnings about missing
  CF-netCDF measure variables and invalid units are ignored).
* **Return type:**
  Generator[None]

### esmvalcore.iris_helpers.merge_cube_attributes(cubes: Sequence[Cube], delimiter: [str](https://docs.python.org/3/builtins/stdtypes.html#str) = ' ') → [None](https://docs.python.org/3/builtins/constants.html#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()`](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.cube.html#iris.cube.CubeList.merge_cube) or
[`iris.cube.CubeList.concatenate_cube()`](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.cube.html#iris.cube.CubeList.concatenate_cube).

#### NOTE
This function differs from [`iris.util.equalise_attributes()`](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.util.html#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*](https://docs.python.org/3/builtins/stdtypes.html#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](https://docs.python.org/3/builtins/stdtypes.html#str)], remaining_dims: [int](https://docs.python.org/3/builtins/functions.html#int) | Literal['auto'] = 'auto') → Cube

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*](https://docs.python.org/3/builtins/stdtypes.html#str) *]*) – (Names of) coordinates along which the output cube should not be
    chunked.
  * **remaining_dims** ([*int*](https://docs.python.org/3/builtins/functions.html#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](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.cube.html#iris.cube.Cube)

### esmvalcore.iris_helpers.safe_convert_units(cube: [Cube](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.cube.html#iris.cube.Cube), units: [str](https://docs.python.org/3/builtins/stdtypes.html#str) | [Unit](https://cf-units.readthedocs.io/en/stable/unit.html#cf_units.Unit)) → [Cube](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.cube.html#iris.cube.Cube)

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

This is a safe version of [`esmvalcore.preprocessor.convert_units()`](esmvalcore.preprocessor.html.md#esmvalcore.preprocessor.convert_units)
that will raise an error if the input cube’s
[`standard_name`](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.cube.html#iris.cube.Cube.standard_name) has been changed.

* **Parameters:**
  * **cube** ([*Cube*](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.cube.html#iris.cube.Cube)) – Input cube (modified in place).
  * **units** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str) *|* [*Unit*](https://cf-units.readthedocs.io/en/stable/unit.html#cf_units.Unit)) – New units.
* **Returns:**
  Converted cube. Just returned for convenience; input cube is modified
  in place.
* **Return type:**
  [iris.cube.Cube](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.cube.html#iris.cube.Cube)
* **Raises:**
  * [**iris.exceptions.UnitConversionError**](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.exceptions.html#iris.exceptions.UnitConversionError) – Old units are unknown.
  * [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError) – Old units are not convertible to new units or unit conversion required
        change of standard_name.