DOC: interpolate: add a note on data with different scales

doc/source/tutorial/interpolate/ND_regular_grid.rst

@@ -80,8 +80,15 @@ and
     >>> np.allclose(result_rgi, result_interpn, atol=1e-15)
     True
 
+.. note::
 
-Finally, we note that if you are dealing with data on Cartesian grids with
-integer coordinates, e.g. resampling image data, these routines may not be the
-optimal choice. Consider using `scipy.ndimage.map_coordinates` instead.
+    If you are dealing with data on Cartesian grids with
+    integer coordinates, e.g. resampling image data, these routines may not be
+    the optimal choice. Consider using `scipy.ndimage.map_coordinates` instead.
+
+.. note::
+
+    If the input data is such that input dimensions have incommensurate
+    units and differ by many orders of magnitude, the interpolant may have
+    numerical artifacts. Consider rescaling the data before interpolating.
 

doc/source/tutorial/interpolate/ND_unstructured.rst

@@ -74,6 +74,12 @@ All these interpolation methods rely on triangulation of the data using the
     despite its name --- is not the right tool. Use `RegularGridInterpolator`
     instead.
 
+.. note::
+
+    If the input data is such that input dimensions have incommensurate
+    units and differ by many orders of magnitude, the interpolant may have
+    numerical artifacts. Consider rescaling the data before interpolating
+    or use the ``rescale=True`` keyword argument to `griddata`.
 
 
 .. _tutorial-interpolate_RBF:

doc/source/tutorial/interpolate/smoothing_splines.rst

@@ -400,6 +400,14 @@ formally corresponds to interpolation, :math:`g(x_i, y_j) = z_{i, j}`.
     For scattered data interpolation, prefer `griddata`; for data on a regular
     grid, prefer `RegularGridInterpolator`. 
 
+
+.. note::
+
+    If the input data, ``x`` and ``y``, is such that input dimensions
+    have incommensurate units and differ by many orders of magnitude, the
+    interpolant `math`:g(x, y): may have numerical artifacts. Consider
+    rescaling the data before interpolation.
+
 We now consider the two spline fitting problems in turn.
 
 

scipy/interpolate/_fitpack2.py

@@ -1276,6 +1276,10 @@ class SmoothBivariateSpline(BivariateSpline):
     -----
     The length of `x`, `y` and `z` should be at least ``(kx+1) * (ky+1)``.
 
+    If the input data is such that input dimensions have incommensurate
+    units and differ by many orders of magnitude, the interpolant may have
+    numerical artifacts. Consider rescaling the data before interpolating.
+
     """
 
     def __init__(self, x, y, z, w=None, bbox=[None] * 4, kx=3, ky=3, s=None,
@@ -1361,6 +1365,10 @@ class LSQBivariateSpline(BivariateSpline):
     -----
     The length of `x`, `y` and `z` should be at least ``(kx+1) * (ky+1)``.
 
+    If the input data is such that input dimensions have incommensurate
+    units and differ by many orders of magnitude, the interpolant may have
+    numerical artifacts. Consider rescaling the data before interpolating.
+
     """
 
     def __init__(self, x, y, z, tx, ty, w=None, bbox=[None]*4, kx=3, ky=3,
@@ -1454,6 +1462,13 @@ class RectBivariateSpline(BivariateSpline):
     bisplev :
         a function to evaluate a bivariate B-spline and its derivatives
 
+    Notes
+    -----
+
+    If the input data is such that input dimensions have incommensurate
+    units and differ by many orders of magnitude, the interpolant may have
+    numerical artifacts. Consider rescaling the data before interpolating.
+
     """
 
     def __init__(self, x, y, z, bbox=[None] * 4, kx=3, ky=3, s=0):

scipy/interpolate/_fitpack_impl.py

@@ -868,6 +868,10 @@ def bisplrep(x, y, z, w=None, xb=None, xe=None, yb=None, ye=None,
     See `bisplev` to evaluate the value of the B-spline given its tck
     representation.
 
+    If the input data is such that input dimensions have incommensurate
+    units and differ by many orders of magnitude, the interpolant may have
+    numerical artifacts. Consider rescaling the data before interpolation.
+
     References
     ----------
     .. [1] Dierckx P.:An algorithm for surface fitting with spline functions

scipy/interpolate/_rgi.py

@@ -104,6 +104,10 @@ class RegularGridInterpolator:
 
     .. versionadded:: 1.9
 
+    If the input data is such that dimensions have incommensurate
+    units and differ by many orders of magnitude, the interpolant may have
+    numerical artifacts. Consider rescaling the data before interpolating.
+
     Examples
     --------
     **Evaluate a function on the points of a 3-D grid**
@@ -551,6 +555,10 @@ def interpn(points, values, xi, method="linear", bounds_error=True,
     the 0 position of the returned array, values_x, so its shape is
     instead ``(1,) + values.shape[ndim:]``.
 
+    If the input data is such that input dimensions have incommensurate
+    units and differ by many orders of magnitude, the interpolant may have
+    numerical artifacts. Consider rescaling the data before interpolation.
+
     Examples
     --------
     Evaluate a simple example function on the points of a regular 3-D grid: