Add nearest neighbour regridding (#266)

* add nearest neighbour regridding

* fix tests

* further improvements, reintroduce mask keywords

* fix tests

* change test name

* add tests

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* flake fix

* update changelog

* address review comments

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* flake fix

* address review comments

* parameterise test

* add Raises section to docstrings

* fix docstrings

* fill out __all__

* address review comments

* further test parameterisation.

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

CHANGELOG.md

@@ -19,6 +19,11 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
   [@stephenworsley](https://github.com/stephenworsley) with extensive review
   work from [@trexfeathers](https://github.com/trexfeathers)
 
+- [PR#266](https://github.com/SciTools-incubator/iris-esmf-regrid/pull/266)
+  Added Nearest neighbour regridding.
+  [@stephenworsley](https://github.com/stephenworsley)
+  [@HGWright](https://github.com/HGWright)
+
 ### Changed
 
 - [PR#198](https://github.com/SciTools-incubator/iris-esmf-regrid/pull/198)

esmf_regrid/esmf_regridder.py

@@ -10,6 +10,7 @@
 
 __all__ = [
     "GridInfo",
+    "RefinedGridInfo",
     "Regridder",
 ]
 
@@ -76,9 +77,10 @@ def __init__(self, src, tgt, method="conservative", precomputed_weights=None):
             Data output by this regridder will be a :class:`numpy.ndarray` whose
             shape is compatible with ``tgt``.
         method : str
-            Either "conservative" or "bilinear". Corresponds to the :mod:`esmpy` methods
-            :attr:`~esmpy.api.constants.RegridMethod.CONSERVE` or
-            :attr:`~esmpy.api.constants.RegridMethod.BILINEAR` used to calculate weights.
+            Either "conservative", "bilinear" or "nearest". Corresponds to the :mod:`esmpy` methods
+            :attr:`~esmpy.api.constants.RegridMethod.CONSERVE`,
+            :attr:`~esmpy.api.constants.RegridMethod.BILINEAR` or
+            :attr:`~esmpy.api.constants.RegridMethod.NEAREST_STOD` used to calculate weights.
         precomputed_weights : :class:`scipy.sparse.spmatrix`, optional
             If ``None``, :mod:`esmpy` will be used to
             calculate regridding weights. Otherwise, :mod:`esmpy` will be bypassed
@@ -91,9 +93,11 @@ def __init__(self, src, tgt, method="conservative", precomputed_weights=None):
             esmf_regrid_method = esmpy.RegridMethod.CONSERVE
         elif method == "bilinear":
             esmf_regrid_method = esmpy.RegridMethod.BILINEAR
+        elif method == "nearest":
+            esmf_regrid_method = esmpy.RegridMethod.NEAREST_STOD
         else:
             raise ValueError(
-                f"method must be either 'bilinear' or 'conservative', got '{method}'."
+                f"method must be either 'bilinear', 'conservative' or 'nearest', got '{method}'."
             )
         self.method = method
 

esmf_regrid/experimental/unstructured_scheme.py

@@ -56,9 +56,10 @@ def regrid_unstructured_to_rectilinear(
         will mean the resulting element will be masked if and only if all the
         overlapping cells of ``src_cube`` are masked.
     method : str, default="conservative"
-        Either "conservative" or "bilinear". Corresponds to the :mod:`esmpy` methods
+        Either "conservative", "bilinear" or "nearest". Corresponds to the :mod:`esmpy` methods
         :attr:`~esmpy.api.constants.RegridMethod.CONSERVE` or
-        :attr:`~esmpy.api.constants.RegridMethod.BILINEAR` used to calculate weights.
+        :attr:`~esmpy.api.constants.RegridMethod.BILINEAR` or
+        :attr:`~esmpy.api.constants.RegridMethod.NEAREST` used to calculate weights.
     tgt_resolution : int, optional
         If present, represents the amount of latitude slices per cell
         given to ESMF for calculation.
@@ -127,9 +128,10 @@ def __init__(
             if all the contributing elements of data are masked. Defaults to 1
             for conservative regregridding and 0 for bilinear regridding.
         method : str, default="conservative"
-            Either "conservative" or "bilinear". Corresponds to the :mod:`esmpy` methods
-            :attr:`~esmpy.api.constants.RegridMethod.CONSERVE` or
-            :attr:`~esmpy.api.constants.RegridMethod.BILINEAR` used to calculate weights.
+            Either "conservative", "bilinear" or "nearest". Corresponds to the :mod:`esmpy`
+            methods :attr:`~esmpy.api.constants.RegridMethod.CONSERVE` or
+            :attr:`~esmpy.api.constants.RegridMethod.BILINEAR` or
+            :attr:`~esmpy.api.constants.RegridMethod.NEAREST` used to calculate weights.
         precomputed_weights : :class:`scipy.sparse.spmatrix`, optional
             If ``None``, :mod:`esmpy` will be used to
             calculate regridding weights. Otherwise, :mod:`esmpy` will be bypassed
@@ -150,6 +152,12 @@ def __init__(
             in ``tgt``. If False, no mask will be taken and all points
             will be used in weights calculation.
 
+        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.
+
 
         """
         if src.mesh is None:
@@ -219,9 +227,10 @@ def regrid_rectilinear_to_unstructured(
         will mean the resulting element will be masked if and only if all the
         overlapping cells of the ``src_cube`` are masked.
     method : str, default="conservative"
-        Either "conservative" or "bilinear". Corresponds to the :mod:`esmpy` methods
+        Either "conservative", "bilinear" or "nearest". Corresponds to the :mod:`esmpy` methods
         :attr:`~esmpy.api.constants.RegridMethod.CONSERVE` or
-        :attr:`~esmpy.api.constants.RegridMethod.BILINEAR` used to calculate weights.
+        :attr:`~esmpy.api.constants.RegridMethod.BILINEAR` or
+        :attr:`~esmpy.api.constants.RegridMethod.NEAREST` used to calculate weights.
     src_resolution : int, optional
         If present, represents the amount of latitude slices per cell
         given to ESMF for calculation.
@@ -290,9 +299,10 @@ def __init__(
             if all the contributing elements of data are masked. Defaults to 1
             for conservative regregridding and 0 for bilinear regridding.
         method : str, default="conservative"
-            Either "conservative" or "bilinear". Corresponds to the :mod:`esmpy` methods
-            :attr:`~esmpy.api.constants.RegridMethod.CONSERVE` or
-            :attr:`~esmpy.api.constants.RegridMethod.BILINEAR` used to calculate weights.
+            Either "conservative", "bilinear" or "nearest". Corresponds to the :mod:`esmpy`
+            methods :attr:`~esmpy.api.constants.RegridMethod.CONSERVE` or
+            :attr:`~esmpy.api.constants.RegridMethod.BILINEAR` or
+            :attr:`~esmpy.api.constants.RegridMethod.NEAREST` used to calculate weights.
         precomputed_weights : :class:`scipy.sparse.spmatrix`, optional
             If ``None``, :mod:`esmpy` will be used to
             calculate regridding weights. Otherwise, :mod:`esmpy` will be bypassed
@@ -313,6 +323,12 @@ def __init__(
             in ``tgt``. If False, no mask will be taken and all points
             will be used in weights calculation.
 
+        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.
+
         """
         if tgt.mesh is None:
             raise ValueError("tgt has no mesh.")