esmf_regrid.schemes module#

Provides an iris interface for regridding.

class esmf_regrid.schemes.ESMFAreaWeighted(mdtol=0, use_src_mask=False, use_tgt_mask=False, tgt_location='face', esmf_args=None)[source]#

Bases: object

A scheme which can be recognised by iris.cube.Cube.regrid().

This class describes an area-weighted regridding scheme for regridding between horizontal grids/meshes. It uses esmpy to handle calculations and allows for different coordinate systems.

Area-weighted scheme for regridding between rectilinear grids.

Parameters:

mdtol (float, default=0) – Tolerance of missing data. The value returned in each element of the returned array will be masked if the fraction of missing data exceeds mdtol. This fraction is calculated based on the area of masked cells within each target cell. mdtol=0 means no masked data is tolerated while mdtol=1 will mean the resulting element will be masked if and only if all the overlapping elements of the source grid are masked.
use_src_mask (bool, default=False) – If True, derive a mask from source cube which will tell esmpy which points to ignore.
use_tgt_mask (bool, default=False) – If True, derive a mask from target cube which will tell esmpy which points to ignore.
tgt_location (str or None, default="face") – Either “face” or “node”. Describes the location for data on the mesh if the target is not a Cube.
esmf_args (dict, optional) – A dictionary of arguments to pass to ESMF. For the sake of reference, These arguments are recorded as a property of this regridder and are stored when the regridder is saved .

regridder(src_grid, tgt_grid, src_resolution=None, tgt_resolution=None, use_src_mask=None, use_tgt_mask=None, tgt_location='face', esmf_args=None, precomputed_weights=None)[source]#

Create regridder to perform regridding from src_grid to tgt_grid.

Parameters:

src_grid (iris.cube.Cube) – The Cube defining the source. If this cube has a grid defined by latitude/longitude coordinates, those coordinates must have bounds.
tgt_grid (iris.cube.Cube or iris.mesh.MeshXY) – The unstructured MeshXY defining the target. If this cube has a grid defined by latitude/longitude coordinates, those coordinates must have bounds.
src_resolution (int, optional) – If present, represents the amount of latitude slices per source/target cell given to ESMF for calculation. If resolution is set, src and tgt respectively must have strictly increasing bounds (bounds may be transposed plus or minus 360 degrees to make the bounds strictly increasing).
tgt_resolution (int, optional) – If present, represents the amount of latitude slices per source/target cell given to ESMF for calculation. If resolution is set, src and tgt respectively must have strictly increasing bounds (bounds may be transposed plus or minus 360 degrees to make the bounds strictly increasing).
use_src_mask (ArrayLike or bool, optional) – Array describing which elements esmpy will ignore on the src_grid. If True, the mask will be derived from src_grid.
use_tgt_mask (ArrayLike or bool, optional) – Array describing which elements esmpy will ignore on the tgt_grid. If True, the mask will be derived from tgt_grid.
tgt_location (str or None, default="face") – Either “face” or “node”. Describes the location for data on the mesh if the target is not a Cube.
esmf_args (dict, optional) – A dictionary of arguments to pass to ESMF. For the sake of reference, These arguments are recorded as a property of this regridder and are stored when the regridder is saved .

Returns:

A callable instance of a regridder with the interface: regridder(cube): … where cube is a Cube with the same grid as src_grid that is to be regridded to the grid of tgt_grid.

Return type:

ESMFAreaWeightedRegridder

Raises:

ValueError – If use_src_mask or use_tgt_mask are True while the masks on src_grid or tgt_grid respectively are not constant over non-horizontal dimensions.

class esmf_regrid.schemes.ESMFAreaWeightedRegridder(src, tgt, mdtol=0, precomputed_weights=None, src_resolution=None, tgt_resolution=None, use_src_mask=False, use_tgt_mask=False, tgt_location='face', esmf_args=None)[source]#

Bases: _ESMFRegridder

Regridder class for conservative regridding of Cube\ s.

Create regridder for conversions between src and tgt.

Parameters:

src (iris.cube.Cube) – The Cube providing the source. If this cube has a grid defined by latitude/longitude coordinates, those coordinates must have bounds.
tgt (iris.cube.Cube or iris.mesh.MeshXY) – The MeshXY defining the target. If this cube has a grid defined by latitude/longitude coordinates, those coordinates must have bounds.
mdtol (float, default=0) – 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.
precomputed_weights (scipy.sparse.spmatrix, optional) – If None, esmpy will be used to calculate regridding weights. Otherwise, esmpy will be bypassed and precomputed_weights will be used as the regridding weights.
src_resolution (int, optional) – If present, represents the amount of latitude slices per source/target cell given to ESMF for calculation. If resolution is set, src and tgt respectively must have strictly increasing bounds (bounds may be transposed plus or minus 360 degrees to make the bounds strictly increasing).
tgt_resolution (int, optional) – If present, represents the amount of latitude slices per source/target cell given to ESMF for calculation. If resolution is set, src and tgt respectively must have strictly increasing bounds (bounds may be transposed plus or minus 360 degrees to make the bounds strictly increasing).
use_src_mask (ArrayLike or bool, default=False) – Either an array representing the cells in the source/target to ignore, or else a boolean value. If True, this array is taken from the mask on the data in src or tgt. If False, no mask will be taken and all points will be used in weights calculation.
use_tgt_mask (ArrayLike or bool, default=False) – Either an array representing the cells in the source/target to ignore, or else a boolean value. If True, this array is taken from the mask on the data in src or tgt. If False, no mask will be taken and all points will be used in weights calculation.
tgt_location (str or None, default="face") – Either “face” or “node”. Describes the location for data on the mesh if the target is not a Cube.
esmf_args (dict, optional) – A dictionary of arguments to pass to ESMF. For the sake of reference, These arguments are recorded as a property of this regridder and are stored when the regridder is saved .

Raises:

ValueError – If use_src_mask or use_tgt_mask are True while the masks on src or tgt respectively are not constant over non-horizontal dimensions or if tgt_location is not “face”.

class esmf_regrid.schemes.ESMFBilinear(mdtol=0, use_src_mask=False, use_tgt_mask=False, tgt_location=None, extrapolate_gaps=False, esmf_args=None)[source]#

Bases: object

A scheme which can be recognised by iris.cube.Cube.regrid().

This class describes a bilinear regridding scheme for regridding between horizontal grids/meshes. It uses esmpy to handle calculations and allows for different coordinate systems.

Area-weighted scheme for regridding between rectilinear grids.

Parameters:

mdtol (float, default=0) – Tolerance of missing data. The value returned in each element of the returned array will be masked if the fraction of missing data exceeds mdtol.
use_src_mask (bool, default=False) – If True, derive a mask from source cube which will tell esmpy which points to ignore.
use_tgt_mask (bool, default=False) – If True, derive a mask from target cube which will tell esmpy which points to ignore.
tgt_location (str or None, default=None) – Either “face” or “node”. Describes the location for data on the mesh if the target is not a Cube.
extrapolate_gaps (bool, default=False) – Use a standard set of ESMF arguments for extrapolation which achieves continuity with bilinear regridding. Useful for situations where gaps between cells would be masked. Note: this overwrites any arguments passed to esmf_args for the keywords “extrap_method”, “extrap_num_src_pnts” or “extrap_dist_exponent”.
esmf_args (dict, optional) – A dictionary of arguments to pass to ESMF. For the sake of reference, These arguments are recorded as a property of this regridder and are stored when the regridder is saved .

regridder(src_grid, tgt_grid, use_src_mask=None, use_tgt_mask=None, tgt_location=None, extrapolate_gaps=False, esmf_args=None, precomputed_weights=None)[source]#

Create regridder to perform regridding from src_grid to tgt_grid.

Parameters:

src_grid (iris.cube.Cube) – The Cube defining the source.
tgt_grid (iris.cube.Cube or iris.mesh.MeshXY) – The unstructured MeshXY defining the target.
use_src_mask (ArrayLike or bool, optional) – Array describing which elements esmpy will ignore on the src_grid. If True, the mask will be derived from src_grid.
use_tgt_mask (ArrayLike or bool, optional) – Array describing which elements esmpy will ignore on the tgt_grid. If True, the mask will be derived from tgt_grid.
tgt_location (str or None, default=None) – Either “face” or “node”. Describes the location for data on the mesh if the target is not a Cube.
extrapolate_gaps (bool, default=False) – Use a standard set of ESMF arguments for extrapolation which achieves continuity with bilinear regridding. Useful for situations where gaps between cells would be masked. Note: this overwrites any arguments passed to esmf_args for the keywords “extrap_method”, “extrap_num_src_pnts” or “extrap_dist_exponent”.
esmf_args (dict, optional) – A dictionary of arguments to pass to ESMF. For the sake of reference, These arguments are recorded as a property of this regridder and are stored when the regridder is saved .

Returns:

A callable instance of a regridder with the interface: regridder(cube): … where cube is a Cube with the same grid as src_grid that is to be regridded to the grid of tgt_grid.

Return type:

ESMFBilinearRegridder

Raises:

ValueError – If use_src_mask or use_tgt_mask are True while the masks on src_grid or tgt_grid respectively are not constant over non-horizontal dimensions.

class esmf_regrid.schemes.ESMFBilinearRegridder(src, tgt, mdtol=0, precomputed_weights=None, use_src_mask=False, use_tgt_mask=False, tgt_location=None, extrapolate_gaps=False, esmf_args=None)[source]#

Bases: _ESMFRegridder

Regridder class for bilinear regridding of Cube\ s.

Create regridder for conversions between src and tgt.

Parameters:

src (iris.cube.Cube) – The Cube providing the source.
tgt (iris.cube.Cube or iris.mesh.MeshXY) – The MeshXY defining the target.
mdtol (float, default=0) – 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.
precomputed_weights (scipy.sparse.spmatrix, optional) – If None, esmpy will be used to calculate regridding weights. Otherwise, esmpy will be bypassed and precomputed_weights will be used as the regridding weights.
use_src_mask (ArrayLike or bool, default=False) – Either an array representing the cells in the source/target to ignore, or else a boolean value. If True, this array is taken from the mask on the data in src or tgt. If False, no mask will be taken and all points will be used in weights calculation.
use_tgt_mask (ArrayLike or bool, default=False) – Either an array representing the cells in the source/target to ignore, or else a boolean value. If True, this array is taken from the mask on the data in src or tgt. If False, no mask will be taken and all points will be used in weights calculation.
tgt_location (str or None, default=None) – Either “face” or “node”. Describes the location for data on the mesh if the target is not a Cube.
extrapolate_gaps (bool, default=False) – Use a standard set of ESMF arguments for extrapolation which achieves continuity with bilinear regridding. Useful for situations where gaps between cells would be masked. Note: this overwrites any arguments passed to esmf_args for the keywords “extrap_method”, “extrap_num_src_pnts” or “extrap_dist_exponent”.
esmf_args (dict, optional) – A dictionary of arguments to pass to ESMF. For the sake of reference, These arguments are recorded as a property of this regridder and are stored when the regridder is saved .

Raises:

ValueError – If use_src_mask or use_tgt_mask are True while the masks on src or tgt respectively are not constant over non-horizontal dimensions.

class esmf_regrid.schemes.ESMFNearest(use_src_mask=False, use_tgt_mask=False, tgt_location=None, esmf_args=None)[source]#

Bases: object

A scheme which can be recognised by iris.cube.Cube.regrid().

This class describes a nearest neighbour regridding scheme for regridding between horizontal grids/meshes. It uses esmpy to handle calculations and allows for different coordinate systems.

Notes

By default, masked data is handled by masking the result when the nearest source point is masked, however, if use_src_mask is True, then the nearest unmasked point is used instead. This differs from other regridding methods where use_src_mask has no effect on the mathematics. Like other methods, when use_src_mask is True, the mask must be constant over all non-horizontal dimensions otherwise an error is thrown.

When two source points are a constant distance from a target point, the decision for which point is used is based on the indexing which ESMF gives the points. ESMF describes this decision as somewhat arbitrary: https://earthsystemmodeling.org/docs/release/latest/ESMF_refdoc/node3.html#SECTION03023000000000000000 As a result of this, while the same object ought to behave consistently for this scheme, there is no guarantee that different objects representing the same equivalent space will behave the same.

Nearest neighbour scheme for regridding between rectilinear grids.

Parameters:

use_src_mask (bool, default=False) – If True, derive a mask from source cube which will tell esmpy which points to ignore.
use_tgt_mask (bool, default=False) – If True, derive a mask from target cube which will tell esmpy which points to ignore.
tgt_location (str or None, default=None) – Either “face” or “node”. Describes the location for data on the mesh if the target is not a Cube.
esmf_args (dict, optional) – A dictionary of arguments to pass to ESMF. For the sake of reference, These arguments are recorded as a property of this regridder and are stored when the regridder is saved .

regridder(src_grid, tgt_grid, use_src_mask=None, use_tgt_mask=None, tgt_location=None, esmf_args=None, precomputed_weights=None)[source]#

Create regridder to perform regridding from src_grid to tgt_grid.

Parameters:

src_grid (iris.cube.Cube) – The Cube defining the source.
tgt_grid (iris.cube.Cube or iris.mesh.MeshXY) – The unstructured MeshXY defining the target.
use_src_mask (ArrayLike or bool, optional) – Array describing which elements esmpy will ignore on the src_grid. If True, the mask will be derived from src_grid.
use_tgt_mask (ArrayLike or bool, optional) – Array describing which elements esmpy will ignore on the tgt_grid. If True, the mask will be derived from tgt_grid.
tgt_location (str or None, default=None) – Either “face” or “node”. Describes the location for data on the mesh if the target is not a Cube.
esmf_args (dict, optional) – A dictionary of arguments to pass to ESMF. For the sake of reference, These arguments are recorded as a property of this regridder and are stored when the regridder is saved .

Returns:

A callable instance of a regridder with the interface: regridder(cube): … where cube is a Cube with the same grid as src_grid that is to be regridded to the grid of tgt_grid.

Return type:

ESMFNearestRegridder

Raises:

ValueError – If use_src_mask or use_tgt_mask are True while the masks on src_grid or tgt_grid respectively are not constant over non-horizontal dimensions.

class esmf_regrid.schemes.ESMFNearestRegridder(src, tgt, precomputed_weights=None, use_src_mask=False, use_tgt_mask=False, tgt_location=None, esmf_args=None)[source]#

Bases: _ESMFRegridder

Regridder class for nearest (source to destination) regridding of Cube\ s.

Create regridder for conversions between src and tgt.

Parameters:

src (iris.cube.Cube) – The Cube providing the source.
tgt (iris.cube.Cube or iris.mesh.MeshXY) – The MeshXY defining the target.
precomputed_weights (scipy.sparse.spmatrix, optional) – If None, esmpy will be used to calculate regridding weights. Otherwise, esmpy will be bypassed and precomputed_weights will be used as the regridding weights.
use_src_mask (ArrayLike or bool, default=False) – Either an array representing the cells in the source/target to ignore, or else a boolean value. If True, this array is taken from the mask on the data in src or tgt. If False, no mask will be taken and all points will be used in weights calculation.
use_tgt_mask (ArrayLike or bool, default=False) – Either an array representing the cells in the source/target to ignore, or else a boolean value. If True, this array is taken from the mask on the data in src or tgt. If False, no mask will be taken and all points will be used in weights calculation.
tgt_location (str or None, default=None) – Either “face” or “node”. Describes the location for data on the mesh if the target is not a Cube.
esmf_args (dict, optional) – A dictionary of arguments to pass to ESMF. For the sake of reference, These arguments are recorded as a property of this regridder and are stored when the regridder is saved .

Raises:

ValueError – If use_src_mask or use_tgt_mask are True while the masks on src or tgt respectively are not constant over non-horizontal dimensions.

esmf_regrid.schemes.regrid_rectilinear_to_rectilinear(src_cube, grid_cube, mdtol=0, method=Method.CONSERVATIVE, src_resolution=None, tgt_resolution=None)[source]#

Regrid rectilinear Cube onto another rectilinear grid.

Return a new Cube with data values calculated using the area weighted mean of data values from src_cube regridded onto the horizontal grid of grid_cube.

Parameters:

src_cube (iris.cube.Cube) – A rectilinear instance of Cube that supplies the data, metadata and coordinates.
grid_cube (iris.cube.Cube) – A rectilinear instance of Cube that supplies the desired horizontal grid definition.
mdtol (float, default=0) – Tolerance of missing data. The value returned in each element of the returned Cube\ ‘s data array will be masked if the fraction of masked data in the overlapping cells of src_cube exceeds mdtol. This fraction is calculated based on the area of masked cells within each target cell. 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 overlapping cells of src_cube are masked.
method (Constants.Method, , default=Constants.Method.CONSERVATIVE) – The method to be used to calculate weights.
src_resolution (int, optional) – If present, represents the amount of latitude slices per source/target cell given to ESMF for calculation.
tgt_resolution (int, optional) – If present, represents the amount of latitude slices per source/target cell given to ESMF for calculation.

Returns:

A new Cube instance.

Return type:

iris.cube.Cube