Repository: scipy/scipy

Issue:
Improve and fix *Spline docstrings and code
<!-- 
Thank you for taking the time to file a bug report. 
Please fill in the fields below, deleting the sections that 
don't apply to your issue. You can view the final output
by clicking the preview button above.
Note: This is a comment, and won't appear in the output.
-->

During the investigation of the issue #9718 I've discovered a few possibilities for both improvements and fixes in the documentation of different *Spline classes in 
https://github.com/scipy/scipy/blob/master/scipy/interpolate/fitpack2.py
I create this issue mainly because it seems to me that it'll be (and must be) more general than #9718
The things below will be mostly about `RectBivariateSpline` class

Things that came into mind:

- In `BivariateSpline` class, as far as I understand,  `RectBivariateSpline` should be added to the end of the sentence, because it subclasses `BivariateSpline`
https://github.com/scipy/scipy/blob/b818978f3580e05a3885006cae337f28bd2aaf7d/scipy/interpolate/fitpack2.py#L931-L933
- Docstring of `RectBivariateSpline` containes a few more inconsistencies: e.g. `tx, ty` in here: https://github.com/scipy/scipy/blob/b818978f3580e05a3885006cae337f28bd2aaf7d/scipy/interpolate/fitpack2.py#L1149-L1152
 although they do not appear in `init`:
https://github.com/scipy/scipy/blob/b818978f3580e05a3885006cae337f28bd2aaf7d/scipy/interpolate/fitpack2.py#L1169
- I have a feeling that "See Also" sections in different Spline's might be more... broad? Consistent? There's not so many of that classes, so why not to mention them all, or at least ensure that if `A -> B` and `A -> C` (-> means subclassing), then `B` mentions `C` in "See Also" and vice versa?
- I've got a feeling that two last checks of these 4 are redundant, but I'm not sure
https://github.com/scipy/scipy/blob/b818978f3580e05a3885006cae337f28bd2aaf7d/scipy/interpolate/fitpack2.py#L1171-L1178
- Problem with #9718 remains for now, but I'm working on it

If this issue "makes sense" to some of the members, I suggest closing #9718 in favor of this one. 



Discussion:
Thank you, @erheron, a thorough review of this and related docs would be great.  All the inconsistencies you noted should definitely be addressed.

Resolving patch:
diff --git a/scipy/interpolate/fitpack2.py b/scipy/interpolate/fitpack2.py
--- a/scipy/interpolate/fitpack2.py
+++ b/scipy/interpolate/fitpack2.py
@@ -120,12 +120,38 @@ class UnivariateSpline(object):
 
     See Also
     --------
-    InterpolatedUnivariateSpline : Subclass with smoothing forced to 0
-    LSQUnivariateSpline : Subclass in which knots are user-selected instead of
-        being set by smoothing condition
-    splrep : An older, non object-oriented wrapping of FITPACK
-    splev, sproot, splint, spalde
-    BivariateSpline : A similar class for two-dimensional spline interpolation
+    BivariateSpline :
+        a base class for bivariate splines.
+    SmoothBivariateSpline :
+        a smoothing bivariate spline through the given points
+    LSQBivariateSpline :
+        a bivariate spline using weighted least-squares fitting
+    RectSphereBivariateSpline :
+        a bivariate spline over a rectangular mesh on a sphere
+    SmoothSphereBivariateSpline :
+        a smoothing bivariate spline in spherical coordinates
+    LSQSphereBivariateSpline :
+        a bivariate spline in spherical coordinates using weighted
+        least-squares fitting
+    RectBivariateSpline :
+        a bivariate spline over a rectangular mesh
+    InterpolatedUnivariateSpline :
+        a interpolating univariate spline for a given set of data points.
+    bisplrep :
+        a function to find a bivariate B-spline representation of a surface
+    bisplev :
+        a function to evaluate a bivariate B-spline and its derivatives
+    splrep :
+        a function to find the B-spline representation of a 1-D curve
+    splev :
+        a function to evaluate a B-spline or its derivatives
+    sproot :
+        a function to find the roots of a cubic B-spline
+    splint :
+        a function to evaluate the definite integral of a B-spline between two
+        given points
+    spalde :
+        a function to evaluate all derivatives of a B-spline
 
     Notes
     -----
@@ -585,12 +611,25 @@ class InterpolatedUnivariateSpline(UnivariateSpline):
 
     See Also
     --------
-    UnivariateSpline : Superclass -- allows knots to be selected by a
-        smoothing condition
-    LSQUnivariateSpline : spline for which knots are user-selected
-    splrep : An older, non object-oriented wrapping of FITPACK
-    splev, sproot, splint, spalde
-    BivariateSpline : A similar class for two-dimensional spline interpolation
+    UnivariateSpline :
+        a smooth univariate spline to fit a given set of data points.
+    LSQUnivariateSpline :
+        a spline for which knots are user-selected
+    SmoothBivariateSpline :
+        a smoothing bivariate spline through the given points
+    LSQBivariateSpline :
+        a bivariate spline using weighted least-squares fitting
+    splrep :
+        a function to find the B-spline representation of a 1-D curve
+    splev :
+        a function to evaluate a B-spline or its derivatives
+    sproot :
+        a function to find the roots of a cubic B-spline
+    splint :
+        a function to evaluate the definite integral of a B-spline between two
+        given points
+    spalde :
+        a function to evaluate all derivatives of a B-spline
 
     Notes
     -----
@@ -695,12 +734,21 @@ class LSQUnivariateSpline(UnivariateSpline):
 
     See Also
     --------
-    UnivariateSpline : Superclass -- knots are specified by setting a
-        smoothing condition
-    InterpolatedUnivariateSpline : spline passing through all points
-    splrep : An older, non object-oriented wrapping of FITPACK
-    splev, sproot, splint, spalde
-    BivariateSpline : A similar class for two-dimensional spline interpolation
+    UnivariateSpline :
+        a smooth univariate spline to fit a given set of data points.
+    InterpolatedUnivariateSpline :
+        a interpolating univariate spline for a given set of data points.
+    splrep :
+        a function to find the B-spline representation of a 1-D curve
+    splev :
+        a function to evaluate a B-spline or its derivatives
+    sproot :
+        a function to find the roots of a cubic B-spline
+    splint :
+        a function to evaluate the definite integral of a B-spline between two
+        given points
+    spalde :
+        a function to evaluate all derivatives of a B-spline
 
     Notes
     -----
@@ -781,11 +829,14 @@ class _BivariateSplineBase(object):
 
     See Also
     --------
-    bisplrep, bisplev : an older wrapping of FITPACK
+    bisplrep :
+        a function to find a bivariate B-spline representation of a surface
+    bisplev :
+        a function to evaluate a bivariate B-spline and its derivatives
     BivariateSpline :
-        implementation of bivariate spline interpolation on a plane grid
+        a base class for bivariate splines.
     SphereBivariateSpline :
-        implementation of bivariate spline interpolation on a spherical grid
+        a bivariate spline on a spherical grid
     """
 
     def get_residual(self):
@@ -934,25 +985,29 @@ class BivariateSpline(_BivariateSplineBase):
 
     This class is meant to be subclassed, not instantiated directly.
     To construct these splines, call either `SmoothBivariateSpline` or
-    `LSQBivariateSpline`.
+    `LSQBivariateSpline` or `RectBivariateSpline`.
 
     See Also
     --------
     UnivariateSpline :
-        a similar class for univariate spline interpolation
+        a smooth univariate spline to fit a given set of data points.
     SmoothBivariateSpline :
-        to create a bivariate spline through the given points
+        a smoothing bivariate spline through the given points
     LSQBivariateSpline :
-        to create a bivariate spline using weighted least-squares fitting
+        a bivariate spline using weighted least-squares fitting
     RectSphereBivariateSpline :
-        to create a bivariate spline over a rectangular mesh on a sphere
+        a bivariate spline over a rectangular mesh on a sphere
     SmoothSphereBivariateSpline :
-        to create a smooth bivariate spline in spherical coordinates
+        a smoothing bivariate spline in spherical coordinates
     LSQSphereBivariateSpline :
-        to create a bivariate spline in spherical coordinates using
-        weighted least-squares fitting
-    bisplrep : older wrapping of FITPACK
-    bisplev : older wrapping of FITPACK
+        a bivariate spline in spherical coordinates using weighted
+        least-squares fitting
+    RectBivariateSpline :
+        a bivariate spline over a rectangular mesh.
+    bisplrep :
+        a function to find a bivariate B-spline representation of a surface
+    bisplev :
+        a function to evaluate a bivariate B-spline and its derivatives
     """
 
     @classmethod
@@ -1057,10 +1112,25 @@ class SmoothBivariateSpline(BivariateSpline):
 
     See Also
     --------
-    bisplrep : an older wrapping of FITPACK
-    bisplev : an older wrapping of FITPACK
-    UnivariateSpline : a similar class for univariate spline interpolation
-    LSQBivariateSpline : to create a BivariateSpline using weighted least-squares fitting
+    BivariateSpline :
+        a base class for bivariate splines.
+    UnivariateSpline :
+        a smooth univariate spline to fit a given set of data points.
+    LSQBivariateSpline :
+        a bivariate spline using weighted least-squares fitting
+    RectSphereBivariateSpline :
+        a bivariate spline over a rectangular mesh on a sphere
+    SmoothSphereBivariateSpline :
+        a smoothing bivariate spline in spherical coordinates
+    LSQSphereBivariateSpline :
+        a bivariate spline in spherical coordinates using weighted
+        least-squares fitting
+    RectBivariateSpline :
+        a bivariate spline over a rectangular mesh
+    bisplrep :
+        a function to find a bivariate B-spline representation of a surface
+    bisplev :
+        a function to evaluate a bivariate B-spline and its derivatives
 
     Notes
     -----
@@ -1127,10 +1197,25 @@ class LSQBivariateSpline(BivariateSpline):
 
     See Also
     --------
-    bisplrep : an older wrapping of FITPACK
-    bisplev : an older wrapping of FITPACK
-    UnivariateSpline : a similar class for univariate spline interpolation
-    SmoothBivariateSpline : create a smoothing BivariateSpline
+    BivariateSpline :
+        a base class for bivariate splines.
+    UnivariateSpline :
+        a smooth univariate spline to fit a given set of data points.
+    SmoothBivariateSpline :
+        a smoothing bivariate spline through the given points
+    RectSphereBivariateSpline :
+        a bivariate spline over a rectangular mesh on a sphere
+    SmoothSphereBivariateSpline :
+        a smoothing bivariate spline in spherical coordinates
+    LSQSphereBivariateSpline :
+        a bivariate spline in spherical coordinates using weighted
+        least-squares fitting
+    RectBivariateSpline :
+        a bivariate spline over a rectangular mesh.
+    bisplrep :
+        a function to find a bivariate B-spline representation of a surface
+    bisplev :
+        a function to evaluate a bivariate B-spline and its derivatives
 
     Notes
     -----
@@ -1190,20 +1275,35 @@ class RectBivariateSpline(BivariateSpline):
     bbox : array_like, optional
         Sequence of length 4 specifying the boundary of the rectangular
         approximation domain.  By default,
-        ``bbox=[min(x,tx),max(x,tx), min(y,ty),max(y,ty)]``.
+        ``bbox=[min(x), max(x), min(y), max(y)]``.
     kx, ky : ints, optional
         Degrees of the bivariate spline. Default is 3.
     s : float, optional
         Positive smoothing factor defined for estimation condition:
-        ``sum((w[i]*(z[i]-s(x[i], y[i])))**2, axis=0) <= s``
-        Default is ``s=0``, which is for interpolation.
+        ``sum((z[i]-f(x[i], y[i]))**2, axis=0) <= s`` where f is a spline
+        function. Default is ``s=0``, which is for interpolation.
 
     See Also
     --------
-    SmoothBivariateSpline : a smoothing bivariate spline for scattered data
-    bisplrep : an older wrapping of FITPACK
-    bisplev : an older wrapping of FITPACK
-    UnivariateSpline : a similar class for univariate spline interpolation
+    BivariateSpline :
+        a base class for bivariate splines.
+    UnivariateSpline :
+        a smooth univariate spline to fit a given set of data points.
+    SmoothBivariateSpline :
+        a smoothing bivariate spline through the given points
+    LSQBivariateSpline :
+        a bivariate spline using weighted least-squares fitting
+    RectSphereBivariateSpline :
+        a bivariate spline over a rectangular mesh on a sphere
+    SmoothSphereBivariateSpline :
+        a smoothing bivariate spline in spherical coordinates
+    LSQSphereBivariateSpline :
+        a bivariate spline in spherical coordinates using weighted
+        least-squares fitting
+    bisplrep :
+        a function to find a bivariate B-spline representation of a surface
+    bisplev :
+        a function to evaluate a bivariate B-spline and its derivatives
 
     """
 
@@ -1272,12 +1372,16 @@ class SphereBivariateSpline(_BivariateSplineBase):
 
     See Also
     --------
-    bisplrep, bisplev : an older wrapping of FITPACK
-    UnivariateSpline : a similar class for univariate spline interpolation
+    bisplrep :
+        a function to find a bivariate B-spline representation of a surface
+    bisplev :
+        a function to evaluate a bivariate B-spline and its derivatives
+    UnivariateSpline :
+        a smooth univariate spline to fit a given set of data points.
     SmoothUnivariateSpline :
-        to create a BivariateSpline through the given points
+        a smooth univariate spline through the given points
     LSQUnivariateSpline :
-        to create a BivariateSpline using weighted least-squares fitting
+        a univariate spline using weighted least-squares fitting
     """
 
     def __call__(self, theta, phi, dtheta=0, dphi=0, grid=True):
@@ -1369,6 +1473,28 @@ class SmoothSphereBivariateSpline(SphereBivariateSpline):
         linear system of equations. `eps` should have a value within the open
         interval ``(0, 1)``, the default is 1e-16.
 
+    See Also
+    --------
+    BivariateSpline :
+        a base class for bivariate splines.
+    UnivariateSpline :
+        a smooth univariate spline to fit a given set of data points.
+    SmoothBivariateSpline :
+        a smoothing bivariate spline through the given points
+    LSQBivariateSpline :
+        a bivariate spline using weighted least-squares fitting
+    RectSphereBivariateSpline :
+        a bivariate spline over a rectangular mesh on a sphere
+    LSQSphereBivariateSpline :
+        a bivariate spline in spherical coordinates using weighted
+        least-squares fitting
+    RectBivariateSpline :
+        a bivariate spline over a rectangular mesh.
+    bisplrep :
+        a function to find a bivariate B-spline representation of a surface
+    bisplev :
+        a function to evaluate a bivariate B-spline and its derivatives
+
     Notes
     -----
     For more information, see the FITPACK_ site about this function.
@@ -1459,7 +1585,7 @@ class LSQSphereBivariateSpline(SphereBivariateSpline):
     Weighted least-squares bivariate spline approximation in spherical
     coordinates.
 
-    Determines a smooth bicubic spline according to a given
+    Determines a smoothing bicubic spline according to a given
     set of knots in the `theta` and `phi` directions.
 
     .. versionadded:: 0.11.0
@@ -1481,6 +1607,27 @@ class LSQSphereBivariateSpline(SphereBivariateSpline):
         linear system of equations. `eps` should have a value within the
         open interval ``(0, 1)``, the default is 1e-16.
 
+    See Also
+    --------
+    BivariateSpline :
+        a base class for bivariate splines.
+    UnivariateSpline :
+        a smooth univariate spline to fit a given set of data points.
+    SmoothBivariateSpline :
+        a smoothing bivariate spline through the given points
+    LSQBivariateSpline :
+        a bivariate spline using weighted least-squares fitting
+    RectSphereBivariateSpline :
+        a bivariate spline over a rectangular mesh on a sphere
+    SmoothSphereBivariateSpline :
+        a smoothing bivariate spline in spherical coordinates
+    RectBivariateSpline :
+        a bivariate spline over a rectangular mesh.
+    bisplrep :
+        a function to find a bivariate B-spline representation of a surface
+    bisplev :
+        a function to evaluate a bivariate B-spline and its derivatives
+
     Notes
     -----
     For more information, see the FITPACK_ site about this function.
@@ -1653,8 +1800,25 @@ class RectSphereBivariateSpline(SphereBivariateSpline):
 
     See Also
     --------
-    RectBivariateSpline : bivariate spline approximation over a rectangular
-        mesh
+    BivariateSpline :
+        a base class for bivariate splines.
+    UnivariateSpline :
+        a smooth univariate spline to fit a given set of data points.
+    SmoothBivariateSpline :
+        a smoothing bivariate spline through the given points
+    LSQBivariateSpline :
+        a bivariate spline using weighted least-squares fitting
+    SmoothSphereBivariateSpline :
+        a smoothing bivariate spline in spherical coordinates
+    LSQSphereBivariateSpline :
+        a bivariate spline in spherical coordinates using weighted
+        least-squares fitting
+    RectBivariateSpline :
+        a bivariate spline over a rectangular mesh.
+    bisplrep :
+        a function to find a bivariate B-spline representation of a surface
+    bisplev :
+        a function to evaluate a bivariate B-spline and its derivatives
 
     Notes
     -----


Test patch: