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')[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 whilemdtol=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
.
- regridder(src_grid, tgt_grid, use_src_mask=None, use_tgt_mask=None, tgt_location='face')[source]#
Create regridder to perform regridding from
src_grid
totgt_grid
.- Parameters:
src_grid (
iris.cube.Cube
) – TheCube
defining the source.tgt_grid (
iris.cube.Cube
oriris.experimental.ugrid.Mesh
) – The unstructuredMesh
defining the target.use_src_mask (
ArrayLike
or bool, optional) – Array describing which elementsesmpy
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 elementsesmpy
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
.
- Returns:
- A callable instance of a regridder with the interface:
regridder(cube)
… where
cube
is aCube
with the same grid assrc_grid
that is to be regridded to the grid oftgt_grid
.
- A callable instance of a regridder with the interface:
- Return type:
- Raises:
ValueError – If
use_src_mask
oruse_tgt_mask
are True while the masks onsrc_grid
ortgt_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')[source]#
Bases:
_ESMFRegridder
Regridder class for conservative regridding of
Cube
\ s.Create regridder for conversions between
src
andtgt
.- Parameters:
src (
iris.cube.Cube
) – The rectilinearCube
providing the source.tgt (
iris.cube.Cube
oriris.experimental.ugrid.Mesh
) – The unstructuredMesh
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 whilemdtol=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) – IfNone
,esmpy
will be used to calculate regridding weights. Otherwise,esmpy
will be bypassed andprecomputed_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
andtgt
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
andtgt
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 insrc
ortgt
. 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 insrc
ortgt
. 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
.
- Raises:
ValueError – If
use_src_mask
oruse_tgt_mask
are True while the masks onsrc
ortgt
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)[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
.
- regridder(src_grid, tgt_grid, use_src_mask=None, use_tgt_mask=None, tgt_location=None)[source]#
Create regridder to perform regridding from
src_grid
totgt_grid
.- Parameters:
src_grid (
iris.cube.Cube
) – TheCube
defining the source.tgt_grid (
iris.cube.Cube
oriris.experimental.ugrid.Mesh
) – The unstructuredMesh
defining the target.use_src_mask (
ArrayLike
or bool, optional) – Array describing which elementsesmpy
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 elementsesmpy
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
.
- Returns:
- A callable instance of a regridder with the interface:
regridder(cube)
… where
cube
is aCube
with the same grid assrc_grid
that is to be regridded to the grid oftgt_grid
.
- A callable instance of a regridder with the interface:
- Return type:
- Raises:
ValueError – If
use_src_mask
oruse_tgt_mask
are True while the masks onsrc_grid
ortgt_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)[source]#
Bases:
_ESMFRegridder
Regridder class for bilinear regridding of
Cube
\ s.Create regridder for conversions between
src
andtgt
.- Parameters:
src (
iris.cube.Cube
) – The rectilinearCube
providing the source.tgt (
iris.cube.Cube
oriris.experimental.ugrid.Mesh
) – The unstructuredMesh
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 whilemdtol=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) – IfNone
,esmpy
will be used to calculate regridding weights. Otherwise,esmpy
will be bypassed andprecomputed_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 insrc
ortgt
. 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 insrc
ortgt
. 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
.
- Raises:
ValueError – If
use_src_mask
oruse_tgt_mask
are True while the masks onsrc
ortgt
respectively are not constant over non-horizontal dimensions.
- class esmf_regrid.schemes.ESMFNearest(use_src_mask=False, use_tgt_mask=False, tgt_location=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
.
- regridder(src_grid, tgt_grid, use_src_mask=None, use_tgt_mask=None, tgt_location=None)[source]#
Create regridder to perform regridding from
src_grid
totgt_grid
.- Parameters:
src_grid (
iris.cube.Cube
) – TheCube
defining the source.tgt_grid (
iris.cube.Cube
oriris.experimental.ugrid.Mesh
) – The unstructuredMesh
defining the target.use_src_mask (
ArrayLike
or bool, optional) – Array describing which elementsesmpy
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 elementsesmpy
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
.
- Returns:
- A callable instance of a regridder with the interface:
regridder(cube)
… where
cube
is aCube
with the same grid assrc_grid
that is to be regridded to the grid oftgt_grid
.
- A callable instance of a regridder with the interface:
- Return type:
- Raises:
ValueError – If
use_src_mask
oruse_tgt_mask
are True while the masks onsrc_grid
ortgt_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)[source]#
Bases:
_ESMFRegridder
Regridder class for nearest (source to destination) regridding of
Cube
\ s.Create regridder for conversions between
src
andtgt
.- Parameters:
src (
iris.cube.Cube
) – The rectilinearCube
providing the source.tgt (
iris.cube.Cube
oriris.experimental.ugrid.Mesh
) – The unstructuredMesh
defining the target.precomputed_weights (
scipy.sparse.spmatrix
, optional) – IfNone
,esmpy
will be used to calculate regridding weights. Otherwise,esmpy
will be bypassed andprecomputed_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 insrc
ortgt
. 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 insrc
ortgt
. 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
.
- Raises:
ValueError – If
use_src_mask
oruse_tgt_mask
are True while the masks onsrc
ortgt
respectively are not constant over non-horizontal dimensions.
- esmf_regrid.schemes.regrid_rectilinear_to_rectilinear(src_cube, grid_cube, mdtol=0, method='conservative', src_resolution=None, tgt_resolution=None)[source]#
Regrid rectilinear
Cube
onto another rectilinear grid.Return a new
Cube
withdata
values calculated using the area weighted mean ofdata
values fromsrc_cube
regridded onto the horizontal grid ofgrid_cube
.- Parameters:
src_cube (
iris.cube.Cube
) – A rectilinear instance ofCube
that supplies the data, metadata and coordinates.grid_cube (
iris.cube.Cube
) – A rectilinear instance ofCube
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
\ ‘sdata
array will be masked if the fraction of masked data in the overlapping cells ofsrc_cube
exceedsmdtol
. This fraction is calculated based on the area of masked cells within each target cell.mdtol=0
means no missing data is tolerated whilemdtol=1
will mean the resulting element will be masked if and only if all the overlapping cells ofsrc_cube
are masked.method (str, default="conservative") – Either “conservative”, “bilinear” or “nearest”. Corresponds to the
esmpy
methodsCONSERVE
,BILINEAR
orNEAREST_STOD
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: