Tweak extract_point preprocessor: explain what it returns if one point coord outside cube and add explicit test (#1584)

* explicit test for full masked data

* explicitly say cube fully masked data

* fix docs

* fix docstring

Author: valeriupredoi

doc/recipe/preprocessor.rst

@@ -1654,6 +1654,11 @@ match the respective latitude and longitude coordinate to those of the
 input coordinates. If the input coordinate is a scalar, the dimension
 will be missing in the output cube (that is, it will be a scalar).
 
+If the point to be extracted has at least one of the coordinate point
+values outside the interval of the cube's same coordinate values, then
+no extrapolation will be performed, and the resulting extracted cube
+will have fully masked data.
+
 Parameters:
   * ``cube``: the input dataset cube.
   * ``latitude``, ``longitude``: coordinates (as floating point

esmvalcore/preprocessor/_regrid.py

@@ -387,6 +387,11 @@ def extract_point(cube, latitude, longitude, scheme):
     scalar, the dimension will be missing in the output cube (that is,
     it will be a scalar).
 
+    If the point to be extracted has at least one of the coordinate point
+    values outside the interval of the cube's same coordinate values, then
+    no extrapolation will be performed, and the resulting extracted cube
+    will have fully masked data.
+
     Parameters
     ----------
     cube : cube
@@ -400,8 +405,11 @@ def extract_point(cube, latitude, longitude, scheme):
 
     Returns
     -------
-    Returns a cube with the extracted point(s), and with adjusted
-    latitude and longitude coordinates (see above).
+    :py:class:`~iris.cube.Cube`
+        Returns a cube with the extracted point(s), and with adjusted
+        latitude and longitude coordinates (see above). If desired point
+        outside values for at least one coordinate, this cube will have fully
+        masked data.
 
     Raises
     ------

tests/integration/preprocessor/_regrid/test_extract_point.py

@@ -51,6 +51,12 @@ def test_extract_point__single_linear(self):
         self.assertEqual(point.shape, (3,))
         self.assert_array_equal(point.data, masked)
 
+        point = extract_point(self.cube, 30, 30, scheme='nearest')
+        self.assertEqual(point.shape, (3,))
+        # do it the proletarian way, back to basics is good sometimes
+        assert np.ma.is_masked(point.data)
+        assert point.data.mask.all()
+
     def test_extract_point__single_nearest(self):
         """Test nearest match when extracting a single point"""