Regridding schemes#

Iris natively supports data regridding with its iris.cube.Cube.regrid() method and a set of predefined regridding schemes provided in the analysis module (further details are given on this page). Here, further regridding schemes are provided that are compatible with iris.cube.Cube.regrid().

Example:

from esmvalcore.preprocessor.regrid_schemes import ESMPyAreaWeighted

regridded_cube = cube.regrid(target_grid, ESMPyAreaWeighted())

Regridding schemes.

Classes:

`ESMPyAreaWeighted`([mask_threshold])	ESMPy area-weighted regridding scheme.
`ESMPyLinear`([mask_threshold])	ESMPy bilinear regridding scheme.
`ESMPyNearest`([mask_threshold])	ESMPy nearest-neighbor regridding scheme.
`ESMPyRegridder`(src_cube, tgt_cube[, method, ...])	General ESMPy regridder.
`GenericFuncScheme`(func, **kwargs)	Regridding with a generic function.
`GenericRegridder`(src_cube, tgt_cube, func, ...)	Generic function regridder.
`IrisESMFRegrid`(method[, mdtol, ...])	iris-esmf-regrid based regridding scheme.
`UnstructuredLinear`()	Unstructured bilinear regridding scheme.
`UnstructuredLinearRegridder`(src_cube, tgt_cube)	Unstructured bilinear regridder.
`UnstructuredNearest`()	Unstructured nearest-neighbor regridding scheme.

class esmvalcore.preprocessor.regrid_schemes.ESMPyAreaWeighted(mask_threshold: float = 0.99)[source]#

ESMPy area-weighted regridding scheme.

This class can be used in iris.cube.Cube.regrid().

Does not support lazy regridding.

Deprecated since version 2.12.0: This scheme has been deprecated and is scheduled for removal in version 2.14.0. Please use IrisESMFRegrid instead.

Methods:

regridder(src_cube, tgt_cube)

Get regridder.

Parameters:: mask_threshold (float)

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

Get regridder.

Parameters:

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

Returns:

Regridder instance.

Return type:

ESMPyRegridder

class esmvalcore.preprocessor.regrid_schemes.ESMPyLinear(mask_threshold: float = 0.99)[source]#

ESMPy bilinear regridding scheme.

This class can be used in iris.cube.Cube.regrid().

Does not support lazy regridding.

Deprecated since version 2.12.0: This scheme has been deprecated and is scheduled for removal in version 2.14.0. Please use IrisESMFRegrid instead.

Methods:

regridder(src_cube, tgt_cube)

Get regridder.

Parameters:: mask_threshold (float)

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

Get regridder.

Parameters:

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

Returns:

Regridder instance.

Return type:

ESMPyRegridder

class esmvalcore.preprocessor.regrid_schemes.ESMPyNearest(mask_threshold: float = 0.99)[source]#

ESMPy nearest-neighbor regridding scheme.

This class can be used in iris.cube.Cube.regrid().

Does not support lazy regridding.

Deprecated since version 2.12.0: This scheme has been deprecated and is scheduled for removal in version 2.14.0. Please use IrisESMFRegrid instead.

Methods:

regridder(src_cube, tgt_cube)

Get regridder.

Parameters:: mask_threshold (float)

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

Get regridder.

Parameters:

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

Returns:

Regridder instance.

Return type:

ESMPyRegridder

class esmvalcore.preprocessor.regrid_schemes.ESMPyRegridder(src_cube: Cube, tgt_cube: Cube, method: str = 'linear', mask_threshold: float = 0.99)[source]#

General ESMPy regridder.

Does not support lazy regridding nor weights caching.

Deprecated since version 2.12.0: This regridder has been deprecated and is scheduled for removal in version 2.14.0. Please use IrisESMFRegrid to create an iris-esmf-regrid regridder instead.

Parameters:

src_cube (Cube) – Cube defining the source grid.
tgt_cube (Cube) – Cube defining the target grid.
method (str) – Regridding algorithm. Must be one of linear, area_weighted, nearest.
mask_threshold (float) – Threshold used to regrid mask of input cube.

class esmvalcore.preprocessor.regrid_schemes.GenericFuncScheme(func: Callable, **kwargs)[source]#

Regridding with a generic function.

This class can be used in 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 – Keyword arguments for the generic regridding function.

Methods:

regridder(src_cube, tgt_cube)

Get regridder.

regridder(src_cube: Cube, tgt_cube: Cube) → GenericRegridder[source]#

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

class esmvalcore.preprocessor.regrid_schemes.GenericRegridder(src_cube: Cube, tgt_cube: Cube, func: Callable, **kwargs)[source]#

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 – Keyword arguments for the generic regridding function.

class esmvalcore.preprocessor.regrid_schemes.IrisESMFRegrid(method: Literal['bilinear', 'conservative', 'nearest'], mdtol: float | None = None, use_src_mask: None | bool | np.ndarray = None, use_tgt_mask: None | bool | np.ndarray = None, collapse_src_mask_along: Iterable[str] = ('Z',), collapse_tgt_mask_along: Iterable[str] = ('Z',), src_resolution: int | None = None, tgt_resolution: int | None = None, tgt_location: Literal['face', 'node'] | None = None)[source]#

iris-esmf-regrid based regridding scheme.

Supports lazy regridding.

Parameters:

method (Literal['bilinear', 'conservative', 'nearest']) – Either “conservative”, “bilinear” or “nearest”. Corresponds to the esmpy methods CONSERVE, BILINEAR or NEAREST_STOD used to calculate regridding weights.
mdtol (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 (None | bool | np.ndarray) – If True, derive a mask from the source cube data, which will tell esmpy which points to ignore. If an array is provided, that will be used. If set to None, it will be set to True for methods 'bilinear' and 'conservative' and to False for method 'nearest'. This default may be changed to True for all schemes once SciTools-incubator/iris-esmf-regrid#368 has been resolved.
use_tgt_mask (None | bool | np.ndarray) – If True, derive a mask from of the target cube, which will tell esmpy which points to ignore. If an array is provided, that will be used. If set to None, it will be set to True for methods 'bilinear' and 'conservative' and to False for method 'nearest'. This default may be changed to True for all schemes once SciTools-incubator/iris-esmf-regrid#368 has been resolved.
collapse_src_mask_along (Iterable[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]) – 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 | 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 | 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. 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(src_cube, tgt_cube)

Create an iris-esmf-regrid based regridding function.

regridder(src_cube: Cube, tgt_cube: Cube | MeshXY) → ESMFAreaWeightedRegridder | ESMFBilinearRegridder | ESMFNearestRegridder[source]#

Create an iris-esmf-regrid based regridding function.

Parameters:

src_cube (Cube) – Cube defining the source grid.
tgt_cube (Cube | MeshXY) – Cube defining the target grid.

Returns:

esmf_regrid.schemes.ESMFAreaWeightedRegridder or
esmf_regrid.schemes.ESMFBilinearRegridder or
esmf_regrid.schemes.ESMFNearestRegridder – An iris-esmf-regrid regridder.

Return type:

ESMFAreaWeightedRegridder | ESMFBilinearRegridder | ESMFNearestRegridder

class esmvalcore.preprocessor.regrid_schemes.UnstructuredLinear[source]#

Unstructured bilinear regridding scheme.

This class can be used in 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(src_cube, tgt_cube)

Get regridder.

regridder(src_cube: Cube, tgt_cube: Cube) → UnstructuredLinearRegridder[source]#

Get regridder.

Parameters:

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

Returns:

Regridder instance.

Return type:

UnstructuredLinearRegridder

class esmvalcore.preprocessor.regrid_schemes.UnstructuredLinearRegridder(src_cube: Cube, tgt_cube: Cube)[source]#

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

Unstructured nearest-neighbor regridding scheme.

This class is a wrapper around 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().

Methods:

regridder(src_cube, tgt_cube)

Get regridder.

regridder(src_cube: Cube, tgt_cube: Cube) → UnstructuredNearestNeigbourRegridder[source]#

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

Regridding schemes#

This Page