Add multi-dimensional extrapolation example and mention different behavior of kwargs in interp (#3956)

* Add note for different behavior of kwargs in 1-d and n-d interpolation

* Add multi-dimensional extrapolation example

* Update whats-new.rst

Author: matrss

doc/interpolation.rst

@@ -150,8 +150,14 @@ Additional keyword arguments can be passed to scipy's functions.
 
     # fill 0 for the outside of the original coordinates.
     da.interp(x=np.linspace(-0.5, 1.5, 10), kwargs={'fill_value': 0.0})
-    # extrapolation
+    # 1-dimensional extrapolation
     da.interp(x=np.linspace(-0.5, 1.5, 10), kwargs={'fill_value': 'extrapolate'})
+    # multi-dimensional extrapolation
+    da = xr.DataArray(np.sin(0.3 * np.arange(12).reshape(4, 3)),
+                      [('time', np.arange(4)),
+                       ('space', [0.1, 0.2, 0.3])])
+
+    da.interp(time=4, space=np.linspace(-0.1, 0.5, 10), kwargs={'fill_value': None})
 
 
 Advanced Interpolation

doc/whats-new.rst

@@ -98,6 +98,10 @@ Documentation
   (:pull:`3935`). By `Spencer Clark <https://github.com/spencerkclark>`_.
 - Updated the list of current core developers. (:issue:`3892`)
   By `Tom Nicholas <https://github.com/TomNicholas>`_.
+- Add example for multi-dimensional extrapolation and note different behavior
+  of ``kwargs`` in :py:meth:`Dataset.interp` and :py:meth:`DataArray.interp`
+  for 1-d and n-d interpolation (:pull:`3956`).
+  By `Matthias Riße <https://github.com/risebell>`_.
 
 Internal Changes
 ~~~~~~~~~~~~~~~~

xarray/core/dataarray.py

@@ -1366,7 +1366,9 @@ def interp(
             first. If True, x has to be an array of monotonically increasing
             values.
         kwargs: dictionary
-            Additional keyword passed to scipy's interpolator.
+            Additional keyword arguments passed to scipy's interpolator. Valid
+            options and their behavior depend on if 1-dimensional or
+            multi-dimensional interpolation is used.
         ``**coords_kwargs`` : {dim: coordinate, ...}, optional
             The keyword arguments form of ``coords``.
             One of coords or coords_kwargs must be provided.

xarray/core/dataset.py

@@ -2570,7 +2570,9 @@ def interp(
             coordinates are assumed to be an array of monotonically increasing
             values.
         kwargs: dictionary, optional
-            Additional keyword passed to scipy's interpolator.
+            Additional keyword arguments passed to scipy's interpolator. Valid
+            options and their behavior depend on if 1-dimensional or
+            multi-dimensional interpolation is used.
         **coords_kwargs : {dim: coordinate, ...}, optional
             The keyword arguments form of ``coords``.
             One of coords or coords_kwargs must be provided.