<a id="regridding-schemes"></a>

# Regridding schemes

Iris natively supports data regridding with its [`iris.cube.Cube.regrid()`](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.cube.html#iris.cube.Cube.regrid)
method and a set of predefined regridding schemes provided in the
[`analysis`](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.analysis.html#module-iris.analysis) module (further details are given on [this](https://scitools-iris.readthedocs.io/en/latest/userguide/interpolation_and_regridding.html)
page).
Here, further regridding schemes are provided that are compatible with
[`iris.cube.Cube.regrid()`](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.cube.html#iris.cube.Cube.regrid).

Example:

```python
from esmvalcore.preprocessor.regrid_schemes import IrisESMFRegrid

regridded_cube = cube.regrid(target_grid, IrisESMFRegrid(method="conservative"))
```

<a id="module-esmvalcore.preprocessor.regrid_schemes"></a>

Regridding schemes.

**Classes:**

| [`GenericFuncScheme`](#esmvalcore.preprocessor.regrid_schemes.GenericFuncScheme)(func, \*\*kwargs)             | Regridding with a generic function.                                                                       |
|--------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------|
| [`GenericRegridder`](#esmvalcore.preprocessor.regrid_schemes.GenericRegridder)(src_cube, tgt_cube, func, ...) | Generic function regridder.                                                                               |
| [`IrisESMFRegrid`](#esmvalcore.preprocessor.regrid_schemes.IrisESMFRegrid)(method[, mdtol, ...])            | [iris-esmf-regrid](https://iris-esmf-regrid.readthedocs.io/en/stable/index.html) based regridding scheme. |
| [`UnstructuredLinear`](#esmvalcore.preprocessor.regrid_schemes.UnstructuredLinear)()                            | Unstructured bilinear regridding scheme.                                                                  |
| [`UnstructuredLinearRegridder`](#esmvalcore.preprocessor.regrid_schemes.UnstructuredLinearRegridder)(src_cube, tgt_cube) | Unstructured bilinear regridder.                                                                          |
| [`UnstructuredNearest`](#esmvalcore.preprocessor.regrid_schemes.UnstructuredNearest)()                           | Unstructured nearest-neighbor regridding scheme.                                                          |

### *class* esmvalcore.preprocessor.regrid_schemes.GenericFuncScheme(func: Callable, \*\*kwargs: Any)

Regridding with a generic function.

This class can be used in [`iris.cube.Cube.regrid()`](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.cube.html#iris.cube.Cube.regrid).

Does support lazy regridding if func does.

* **Parameters:**
  * **func** (*Callable*) – Generic regridding function with signature f(src_cube: Cube, grid_cube:
    Cube, \*\*kwargs) -> Cube.
  * **\*\*kwargs** (*Any*) – Keyword arguments for the generic regridding function.

**Methods:**

| [`regridder`](#esmvalcore.preprocessor.regrid_schemes.GenericFuncScheme.regridder)(src_cube, tgt_cube)   | Get regridder.   |
|----------------------------------------------------------------------------------|------------------|

#### regridder(src_cube: Cube, tgt_cube: Cube) → [GenericRegridder](#esmvalcore.preprocessor.regrid_schemes.GenericRegridder)

Get regridder.

* **Parameters:**
  * **src_cube** (*Cube*) – Cube defining the source grid.
  * **tgt_cube** (*Cube*) – Cube defining the target grid.
* **Returns:**
  Regridder instance.
* **Return type:**
  [GenericRegridder](#esmvalcore.preprocessor.regrid_schemes.GenericRegridder)

### *class* esmvalcore.preprocessor.regrid_schemes.GenericRegridder(src_cube: Cube, tgt_cube: Cube, func: Callable, \*\*kwargs: Any)

Generic function regridder.

Does support lazy regridding if func does. Does not support weights
caching.

* **Parameters:**
  * **src_cube** (*Cube*) – Cube defining the source grid.
  * **tgt_cube** (*Cube*) – Cube defining the target grid.
  * **func** (*Callable*) – Generic regridding function with signature f(src_cube: Cube, grid_cube:
    Cube, \*\*kwargs) -> Cube.
  * **\*\*kwargs** (*Any*) – Keyword arguments for the generic regridding function.

### *class* esmvalcore.preprocessor.regrid_schemes.IrisESMFRegrid(method: Literal['bilinear', 'conservative', 'nearest'], mdtol: [float](https://docs.python.org/3/builtins/functions.html#float) | [None](https://docs.python.org/3/builtins/constants.html#None) = None, use_src_mask: [bool](https://docs.python.org/3/builtins/functions.html#bool) | np.ndarray | [None](https://docs.python.org/3/builtins/constants.html#None) = None, use_tgt_mask: [bool](https://docs.python.org/3/builtins/functions.html#bool) | np.ndarray | [None](https://docs.python.org/3/builtins/constants.html#None) = None, collapse_src_mask_along: Iterable[[str](https://docs.python.org/3/builtins/stdtypes.html#str)] = ('Z',), collapse_tgt_mask_along: Iterable[[str](https://docs.python.org/3/builtins/stdtypes.html#str)] = ('Z',), src_resolution: [int](https://docs.python.org/3/builtins/functions.html#int) | [None](https://docs.python.org/3/builtins/constants.html#None) = None, tgt_resolution: [int](https://docs.python.org/3/builtins/functions.html#int) | [None](https://docs.python.org/3/builtins/constants.html#None) = None, tgt_location: Literal['face', 'node'] | [None](https://docs.python.org/3/builtins/constants.html#None) = None)

[iris-esmf-regrid](https://iris-esmf-regrid.readthedocs.io/en/stable/index.html) based regridding scheme.

This regridding scheme is a thin wrapper around the regridders provided by
[`esmf_regrid`](https://iris-esmf-regrid.readthedocs.io/en/stable/_api_generated/esmf_regrid.html#module-esmf_regrid) with improved handling of masks. This allows using
these regridders from the [regrid preprocessor](../recipe/preprocessor.html.md#horizontal-regridding)
function.

Supports lazy regridding.

* **Parameters:**
  * **method** (*Literal* *[* *'bilinear'* *,*  *'conservative'* *,*  *'nearest'* *]*) – Either “conservative”, “bilinear” or “nearest”. Corresponds to the
    [`esmpy`](https://earthsystemmodeling.org/esmpy_doc/release/latest/html/intro.html#module-esmpy) methods
    [`CONSERVE`](https://earthsystemmodeling.org/esmpy_doc/release/latest/html/RegridMethod.html#esmpy.api.constants.RegridMethod.CONSERVE),
    [`BILINEAR`](https://earthsystemmodeling.org/esmpy_doc/release/latest/html/RegridMethod.html#esmpy.api.constants.RegridMethod.BILINEAR) or
    [`NEAREST_STOD`](https://earthsystemmodeling.org/esmpy_doc/release/latest/html/RegridMethod.html#esmpy.api.constants.RegridMethod.NEAREST_STOD) used to
    calculate regridding weights.
  * **mdtol** ([*float*](https://docs.python.org/3/builtins/functions.html#float) *|* *None*) – Tolerance of missing data. The value returned in each element of
    the returned array will be masked if the fraction of masked data
    exceeds `mdtol`. `mdtol=0` means no missing data is tolerated while
    `mdtol=1` will mean the resulting element will be masked if and only
    if all the contributing elements of data are masked. If no value is
    given, this will default to 1 for conservative regridding and 0
    otherwise. Only available for methods ‘bilinear’ and ‘conservative’.
  * **use_src_mask** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool) *|* *np.ndarray* *|* *None*) – If True, derive a mask from the source cube data,
    which will tell [`esmpy`](https://earthsystemmodeling.org/esmpy_doc/release/latest/html/intro.html#module-esmpy) which points to ignore. If an array is
    provided, that will be used.
    If set to [`None`](https://docs.python.org/3/builtins/constants.html#None), it will be set to [`True`](https://docs.python.org/3/builtins/constants.html#True) for methods
    `'bilinear'` and `'conservative'` and to [`False`](https://docs.python.org/3/builtins/constants.html#False) for method
    `'nearest'`. This default may be changed to [`True`](https://docs.python.org/3/builtins/constants.html#True) for all
    schemes once [SciTools-incubator/iris-esmf-regrid#368](https://github.com/SciTools-incubator/iris-esmf-regrid/issues/368)
    has been resolved.
  * **use_tgt_mask** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool) *|* *np.ndarray* *|* *None*) – If True, derive a mask from of the target cube,
    which will tell [`esmpy`](https://earthsystemmodeling.org/esmpy_doc/release/latest/html/intro.html#module-esmpy) which points to ignore. If an array is
    provided, that will be used.
    If set to [`None`](https://docs.python.org/3/builtins/constants.html#None), it will be set to [`True`](https://docs.python.org/3/builtins/constants.html#True) for methods
    `'bilinear'` and `'conservative'` and to [`False`](https://docs.python.org/3/builtins/constants.html#False) for method
    `'nearest'`. This default may be changed to [`True`](https://docs.python.org/3/builtins/constants.html#True) for all
    schemes once [SciTools-incubator/iris-esmf-regrid#368](https://github.com/SciTools-incubator/iris-esmf-regrid/issues/368) has been
    resolved.
  * **collapse_src_mask_along** (*Iterable* *[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str) *]*) – When deriving the mask from the source cube data, collapse the mask
    along the dimensions identified by these axes or coordinates. Only
    points that are masked at all time (`'T'`), vertical levels
    (`'Z'`), or both time and vertical levels (`'TZ'`) will be
    considered masked. Instead of the axes `'T'` and `'Z'`,
    coordinate names can also be provided. For any cube dimensions not
    specified here, the first slice along the coordinate will be used to
    determine the mask.
  * **collapse_tgt_mask_along** (*Iterable* *[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str) *]*) – When deriving the mask from the target cube data, collapse the mask
    along the dimensions identified by these axes or coordinates. Only
    points that are masked at all time (`'T'`), vertical levels
    (`'Z'`), or both time and vertical levels (`'TZ'`) will be
    considered masked. Instead of the axes `'T'` and `'Z'`,
    coordinate names can also be provided. For any cube dimensions not
    specified here, the first slice along the coordinate will be used to
    determine the mask.
  * **src_resolution** ([*int*](https://docs.python.org/3/builtins/functions.html#int) *|* *None*) – If present, represents the amount of latitude slices per source cell
    given to ESMF for calculation. If resolution is set, the source cube
    must have strictly increasing bounds (bounds may be transposed
    plus or minus 360 degrees to make the bounds strictly increasing).
    Only available for method ‘conservative’.
  * **tgt_resolution** ([*int*](https://docs.python.org/3/builtins/functions.html#int) *|* *None*) – If present, represents the amount of latitude slices per target cell
    given to ESMF for calculation. If resolution is set, the target cube
    must have strictly increasing bounds (bounds may be transposed
    plus or minus 360 degrees to make the bounds strictly increasing).
    Only available for method ‘conservative’.
  * **tgt_location** (*Literal* *[* *'face'* *,*  *'node'* *]*  *|* *None*) – Only used if the target grid is an [`iris.mesh.MeshXY`](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.mesh.html#iris.mesh.MeshXY). Describes
    the location for data on the mesh. Either `'face'` or `'node'` for
    bilinear or nearest neighbour regridding, can only be `'face'` for
    first order conservative regridding.

#### kwargs

Keyword arguments that will be provided to the regridder.

**Methods:**

| [`regridder`](#esmvalcore.preprocessor.regrid_schemes.IrisESMFRegrid.regridder)(src_cube, tgt_cube)   | Create an [iris-esmf-regrid](https://iris-esmf-regrid.readthedocs.io/en/stable/index.html) based regridding function.   |
|----------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------|

#### regridder(src_cube: [Cube](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.cube.html#iris.cube.Cube), tgt_cube: [Cube](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.cube.html#iris.cube.Cube) | [MeshXY](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.mesh.components.html#iris.mesh.components.MeshXY)) → [ESMFAreaWeightedRegridder](https://iris-esmf-regrid.readthedocs.io/en/stable/_api_generated/esmf_regrid.schemes.html#esmf_regrid.schemes.ESMFAreaWeightedRegridder) | [ESMFBilinearRegridder](https://iris-esmf-regrid.readthedocs.io/en/stable/_api_generated/esmf_regrid.schemes.html#esmf_regrid.schemes.ESMFBilinearRegridder) | [ESMFNearestRegridder](https://iris-esmf-regrid.readthedocs.io/en/stable/_api_generated/esmf_regrid.schemes.html#esmf_regrid.schemes.ESMFNearestRegridder)

Create an [iris-esmf-regrid](https://iris-esmf-regrid.readthedocs.io/en/stable/index.html) based regridding function.

* **Parameters:**
  * **src_cube** ([*Cube*](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.cube.html#iris.cube.Cube)) – Cube defining the source grid.
  * **tgt_cube** ([*Cube*](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.cube.html#iris.cube.Cube) *|* [*MeshXY*](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.mesh.components.html#iris.mesh.components.MeshXY)) – Cube defining the target grid.
* **Returns:**
  * [`esmf_regrid.schemes.ESMFAreaWeightedRegridder`](https://iris-esmf-regrid.readthedocs.io/en/stable/_api_generated/esmf_regrid.schemes.html#esmf_regrid.schemes.ESMFAreaWeightedRegridder) or
  * [`esmf_regrid.schemes.ESMFBilinearRegridder`](https://iris-esmf-regrid.readthedocs.io/en/stable/_api_generated/esmf_regrid.schemes.html#esmf_regrid.schemes.ESMFBilinearRegridder) or
  * [`esmf_regrid.schemes.ESMFNearestRegridder`](https://iris-esmf-regrid.readthedocs.io/en/stable/_api_generated/esmf_regrid.schemes.html#esmf_regrid.schemes.ESMFNearestRegridder) – An [iris-esmf-regrid](https://iris-esmf-regrid.readthedocs.io/en/stable/index.html) regridder.
* **Return type:**
  [*ESMFAreaWeightedRegridder*](https://iris-esmf-regrid.readthedocs.io/en/stable/_api_generated/esmf_regrid.schemes.html#esmf_regrid.schemes.ESMFAreaWeightedRegridder) | [*ESMFBilinearRegridder*](https://iris-esmf-regrid.readthedocs.io/en/stable/_api_generated/esmf_regrid.schemes.html#esmf_regrid.schemes.ESMFBilinearRegridder) | [*ESMFNearestRegridder*](https://iris-esmf-regrid.readthedocs.io/en/stable/_api_generated/esmf_regrid.schemes.html#esmf_regrid.schemes.ESMFNearestRegridder)

### *class* esmvalcore.preprocessor.regrid_schemes.UnstructuredLinear

Unstructured bilinear regridding scheme.

This class can be used in [`iris.cube.Cube.regrid()`](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.cube.html#iris.cube.Cube.regrid).

Supports lazy regridding.

#### WARNING
This will drop all cell measures, ancillary variables and aux factories,
and any auxiliary coordinate that spans the dimension of the unstrucutred
grid.

**Methods:**

| [`regridder`](#esmvalcore.preprocessor.regrid_schemes.UnstructuredLinear.regridder)(src_cube, tgt_cube)   | Get regridder.   |
|----------------------------------------------------------------------------------|------------------|

#### regridder(src_cube: [Cube](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.cube.html#iris.cube.Cube), tgt_cube: [Cube](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.cube.html#iris.cube.Cube)) → [UnstructuredLinearRegridder](#esmvalcore.preprocessor.regrid_schemes.UnstructuredLinearRegridder)

Get regridder.

* **Parameters:**
  * **src_cube** ([*Cube*](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.cube.html#iris.cube.Cube)) – Cube defining the source grid.
  * **tgt_cube** ([*Cube*](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.cube.html#iris.cube.Cube)) – Cube defining the target grid.
* **Returns:**
  Regridder instance.
* **Return type:**
  [UnstructuredLinearRegridder](#esmvalcore.preprocessor.regrid_schemes.UnstructuredLinearRegridder)

### *class* esmvalcore.preprocessor.regrid_schemes.UnstructuredLinearRegridder(src_cube: [Cube](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.cube.html#iris.cube.Cube), tgt_cube: [Cube](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.cube.html#iris.cube.Cube))

Unstructured bilinear regridder.

Supports lazy regridding and weights caching.

#### WARNING
This will drop all cell measures, ancillary variables and aux factories,
and any auxiliary coordinate that spans the dimension of the unstrucutred
grid.

* **Parameters:**
  * **src_cube** (*Cube*) – Cube defining the source grid.
  * **tgt_cube** (*Cube*) – Cube defining the target grid.

### *class* esmvalcore.preprocessor.regrid_schemes.UnstructuredNearest

Unstructured nearest-neighbor regridding scheme.

This class is a wrapper around [`iris.analysis.UnstructuredNearest`](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.analysis.html#iris.analysis.UnstructuredNearest)
that removes any additional X or Y coordinates prior to regridding if
necessary. It can be used in [`iris.cube.Cube.regrid()`](https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.cube.html#iris.cube.Cube.regrid).

**Methods:**

| [`regridder`](#esmvalcore.preprocessor.regrid_schemes.UnstructuredNearest.regridder)(src_cube, tgt_cube)   | Get regridder.   |
|----------------------------------------------------------------------------------|------------------|

#### regridder(src_cube: Cube, tgt_cube: Cube) → UnstructuredNearestNeigbourRegridder

Get regridder.

* **Parameters:**
  * **src_cube** (*Cube*) – Cube defining the source grid.
  * **tgt_cube** (*Cube*) – Cube defining the target grid.
* **Returns:**
  Regridder instance.
* **Return type:**
  UnstructuredNearestNeigbourRegridder