Update and cleanup docs

csaps/__init__.py

@@ -26,12 +26,12 @@
     MultivariateDataType,
     NdGridDataType,
 )
-from csaps._shortcut import csaps, SmoothingResult
+from csaps._shortcut import csaps, AutoSmoothingResult
 
 __all__ = [
     # Shortcut
     'csaps',
-    'SmoothingResult',
+    'AutoSmoothingResult',
 
     # Classes
     'SplinePPFormBase',

csaps/_shortcut.py

@@ -25,14 +25,15 @@
 _WeightsDataType = Optional[Union[UnivariateDataType, NdGridDataType]]
 _SmoothDataType = Optional[Union[float, Sequence[Optional[float]]]]
 
-SmoothingResult = NamedTuple('SmoothingResult', [
+AutoSmoothingResult = NamedTuple('AutoSmoothingResult', [
     ('values', _YDataType),
     ('smooth', _SmoothDataType),
 ])
+"""The result for auto smoothing for `csaps` function"""
 
 _ReturnType = Union[
     _YDataType,
-    SmoothingResult,
+    AutoSmoothingResult,
     ISmoothingSpline,
 ]
 
@@ -45,62 +46,67 @@ def csaps(xdata: _XDataType,
           axis: Optional[int] = None) -> _ReturnType:
     """Smooths the univariate/multivariate/gridded data or computes the corresponding splines
 
-    This function might be used in procedural code.
+    This function might be used as the main API for smoothing any data.
 
     Parameters
     ----------
 
     xdata : np.ndarray, array-like
-        [required] The data sites ``x1 < x2 < ... < xN``:
-            - 1-D data vector/sequence (array-like) for univariate/multivariate ydata case
-            - The sequence of 1-D data vectors for nd-gridded ydata case
+        The data sites ``x1 < x2 < ... < xN``:
+            - 1-D data vector/sequence (array-like) for univariate/multivariate ``ydata`` case
+            - The sequence of 1-D data vectors for nd-gridded ``ydata`` case
 
     ydata : np.ndarray, array-like
-        [required] The data values:
+        The data values:
             - 1-D data vector/sequence (array-like) for univariate data case
             - N-D array/array-like for multivariate data case
             - N-D array for nd-gridded data case
 
-    xidata : np.ndarray, array-like, sequence[array-like]
-        [optional] The data sites for output smoothed data:
-            - 1-D data vector/sequence (array-like) for univariate/multivariate ydata case
-            - The sequence of 1-D data vectors for nd-gridded ydata case
-        If this argument was not set, the function will return computed spline for given data
-        in `ISmoothingSpline` object.
-
-    weights : np.ndarray, array-like, sequence[array-like]
-        [optional] The weights data vectors:
-            - 1-D data vector/sequence (array-like) for univariate/multivariate ydata case
-            - The sequence of 1-D data vectors for nd-gridded ydata case
-
-    smooth : float, sequence[float]
-        [optional] The smoothing factor value(s):
-            - float value in the range ``[0, 1]`` for univariate/multivariate ydata case
-            - the sequence of float in the range ``[0, 1]`` or None for nd-gridded ydata case
+    xidata : [*Optional*] np.ndarray, array-like, Sequence[array-like]
+        The data sites for output smoothed data:
+            - 1-D data vector/sequence (array-like) for univariate/multivariate ``ydata`` case
+            - The sequence of 1-D data vectors for nd-gridded ``ydata`` case
+
+        If this argument was not set, the function will return computed spline
+        for given data in :class:`ISmoothingSpline` object.
+
+    weights : [*Optional*] np.ndarray, array-like, Sequence[array-like]
+        The weights data vectors:
+            - 1-D data vector/sequence (array-like) for univariate/multivariate ``ydata`` case
+            - The sequence of 1-D data vectors for nd-gridded ``ydata`` case
+
+    smooth : [*Optional*] float, Sequence[float]
+        The smoothing factor value(s):
+            - float value in the range ``[0, 1]`` for univariate/multivariate ``ydata`` case
+            - the sequence of float in the range ``[0, 1]`` or None for nd-gridded ``ydata`` case
+
         If this argument was not set or None or sequence with None-items, the function will return
-        named tuple `SmoothingResult` with computed smoothed data values and smoothing factor value(s).
+        named tuple :class:`AutoSmoothingResult` with computed smoothed data values and smoothing factor value(s).
+
+    axis : [*Optional*] int
+        The ``ydata`` axis. Axis along which ``ydata`` is assumed to be varying.
+        If this argument was not set the last axis will be used (``axis == -1``).
 
-    axis : int
-        [optional] The ydata axis. Axis along which "ydata" is assumed to be varying.
-        If this argument was not set the last axis will be used.
-        Currently, `axis` will be ignored for nd-gridded ydata case.
+        .. note::
+            Currently, `axis` will be ignored for nd-gridded ``ydata`` case.
 
     Returns
     -------
 
     yidata : np.ndarray
-        Smoothed data values if `xidata` and `smooth` were set.
+        Smoothed data values if ``xidata`` and ``smooth`` were set.
 
-    smoothed_data : SmoothingResult
-        The named tuple with two fileds:
+    autosmoothing_result : AutoSmoothingResult
+        The named tuple object with two fileds:
             - 'values' -- smoothed data values
             - 'smooth' -- computed smoothing factor
-        This result will be returned if `xidata` was set and `smooth` was not set.
 
-    sspobj : ISmoothingSpline
-        Smoothing spline object if `xidata` was not set:
-            - `UnivariateCubicSmoothingSpline` instance for univariate/multivariate data
-            - `NdGridCubicSmoothingSpline` instance for nd-gridded data
+        This result will be returned if ``xidata`` was set and ``smooth`` was not set.
+
+    ssp_obj : ISmoothingSpline
+        Smoothing spline object if ``xidata`` was not set:
+            - :class:`UnivariateCubicSmoothingSpline` instance for univariate/multivariate data
+            - :class:`NdGridCubicSmoothingSpline` instance for nd-gridded data
 
     Examples
     --------
@@ -159,6 +165,6 @@ def csaps(xdata: _XDataType,
         auto_smooth = any(sm is None for sm in smooth)
 
     if auto_smooth:
-        return SmoothingResult(yidata, sp.smooth)
+        return AutoSmoothingResult(yidata, sp.smooth)
     else:
         return yidata

csaps/_sspndg.py

@@ -39,9 +39,9 @@ class NdGridSplinePPForm(SplinePPFormBase[ty.Sequence[np.ndarray], ty.Tuple[int,
     Parameters
     ----------
     breaks : np.ndarray
-        Breaks values 1-d array
+        Breaks values 1-D array
     coeffs : np.ndarray
-        Spline coefficients 2-d array
+        Spline coefficients 2-D array
     """
 
     def __init__(self, breaks: ty.Sequence[np.ndarray], coeffs: np.ndarray) -> None:
@@ -94,26 +94,33 @@ def evaluate(self, xi: ty.Sequence[np.ndarray]) -> np.ndarray:
 class NdGridCubicSmoothingSpline(ISmoothingSpline[NdGridSplinePPForm, ty.Tuple[float, ...], NdGridDataType]):
     """ND-Gridded cubic smoothing spline
 
-    Class implments ND-gridded data approximation via cubic smoothing spline
-    (piecewise tensor product polynomial).
+    Class implements ND-gridded data smoothing (piecewise tensor product polynomial).
 
     Parameters
     ----------
-    xdata : list, tuple
+
+    xdata : list, tuple, Sequence[vector-like]
         X data site vectors for each dimensions. These vectors determine ND-grid.
         For example::
 
             # 2D grid
-            x = [np.linspace(0, 5, 21), np.linspace(0, 6, 25)]
+            x = [
+                np.linspace(0, 5, 21),
+                np.linspace(0, 6, 25),
+            ]
 
     ydata : np.ndarray
-        Y input data ND-array with shape equal X data vector sizes
-    weights : list, tuple
-        [Optional] Weights data vectors for all dimensions with size equal xdata sizes
-    smooth : float
-        [Optional] Smoothing parameter (or list of parameters for each dimension) in range [0, 1] where:
+        Y data ND-array with shape equal ``xdata`` vector sizes
+
+    weights : [*Optional*] list, tuple, Sequence[vector-like]
+        Weights data vector(s) for all dimensions or each dimension with
+        size(s) equal to ``xdata`` sizes
+
+    smooth : [*Optional*] float, Sequence[float]
+        The smoothing parameter (or a sequence of parameters for each dimension) in range ``[0, 1]`` where:
             - 0: The smoothing spline is the least-squares straight line fit
             - 1: The cubic spline interpolant with natural condition
+
     """
 
     def __init__(self,
@@ -132,12 +139,12 @@ def __init__(self,
 
     @property
     def smooth(self) -> ty.Tuple[float, ...]:
-        """Returns smooth factor for every axis
+        """Returns a tuple of smoothing parameters for each axis
 
         Returns
         -------
         smooth : Tuple[float, ...]
-            Smooth factor in the range [0, 1] for every axis
+            The smoothing parameter in the range ``[0, 1]`` for each axis
         """
         return self._smooth
 
@@ -147,8 +154,8 @@ def spline(self) -> NdGridSplinePPForm:
 
         Returns
         -------
-        spline : SplinePPForm
-            The spline description in 'SplinePPForm' instance
+        spline : NdGridSplinePPForm
+            The spline description in :class:`NdGridSplinePPForm` instance
         """
         return self._spline
 
@@ -197,6 +204,8 @@ def _prepare_data(cls, xdata, ydata, weights, smooth):
         return xdata, ydata, weights, smooth
 
     def __call__(self, xi: NdGridDataType) -> np.ndarray:
+        """Evaluate the spline for given data
+        """
         xi = ndgrid_prepare_data_sites(xi, 'xi')
 
         if len(xi) != self._ndim:

csaps/_sspumv.py

@@ -22,13 +22,17 @@ class SplinePPForm(SplinePPFormBase[np.ndarray, int]):
     Parameters
     ----------
     breaks : np.ndarray
-        Breaks values 1-d array
+        Breaks values 1-D array
+
     coeffs : np.ndarray
-        Spline coefficients 2-d array
+        Spline coefficients 2-D array
+
     ndim : int
         Spline dimension
+
     shape : Sequence[int]
         It determines Y data shape
+
     axis : int
         Axis along which values are assumed to be varying
     """
@@ -114,18 +118,23 @@ class UnivariateCubicSmoothingSpline(ISmoothingSpline[SplinePPForm, float, Univa
 
     Parameters
     ----------
-    xdata : np.ndarray, list
-        X input 1D data vector (data sites: x1 < x2 < ... < xN)
-    ydata : np.ndarray, list
-        Y input 1D data vector or ND-array with shape[axis] equal of X data size)
-    weights : np.ndarray, list
-        [Optional] Weights 1D vector with size equal of xdata size
-    smooth : float
-        [Optional] Smoothing parameter in range [0, 1] where:
+
+    xdata : np.ndarray, sequence, vector-like
+        X input 1-D data vector (data sites: ``x1 < x2 < ... < xN``)
+
+    ydata : np.ndarray, vector-like, sequence[vector-like]
+        Y input 1-D data vector or ND-array with shape[axis] equal of `xdata` size)
+
+    weights : [*Optional*] np.ndarray, list
+        Weights 1-D vector with size equal of ``xdata`` size
+
+    smooth : [*Optional*] float
+        Smoothing parameter in range [0, 1] where:
             - 0: The smoothing spline is the least-squares straight line fit
             - 1: The cubic spline interpolant with natural condition
+
     axis : int
-        Axis along which "ydata" is assumed to be varying.
+        Axis along which ``ydata`` is assumed to be varying.
         Meaning that for x[i] the corresponding values are np.take(ydata, i, axis=axis).
         By default is -1 (the last axis).
     """
@@ -148,7 +157,7 @@ def __init__(self,
         self._spline, self._smooth = self._make_spline(smooth)
 
     def __call__(self, xi: UnivariateDataType) -> np.ndarray:
-        """Evaluate the spline's approximation for given data
+        """Evaluate the spline for given data
         """
         xi = ty.cast(np.ndarray, np.asarray(xi, dtype=np.float64))
 
@@ -159,7 +168,7 @@ def __call__(self, xi: UnivariateDataType) -> np.ndarray:
 
     @property
     def smooth(self) -> float:
-        """Returns smooth factor
+        """Returns the smoothing parameter
 
         Returns
         -------
@@ -170,12 +179,12 @@ def smooth(self) -> float:
 
     @property
     def spline(self) -> SplinePPForm:
-        """Returns the spline description in 'SplinePPForm' instance
+        """Returns the spline description in `SplinePPForm` instance
 
         Returns
         -------
         spline : SplinePPForm
-            The spline description in 'SplinePPForm' instance
+            The spline description in :class:`SplinePPForm` instance
         """
         return self._spline
 
@@ -312,6 +321,8 @@ class MultivariateCubicSmoothingSpline(ISmoothingSpline[SplinePPForm, float, Uni
 
     For example:
 
+    .. code-block:: python
+
         # 3D data
         data = [
             # Data vectors   Dimension
@@ -337,15 +348,19 @@ class MultivariateCubicSmoothingSpline(ISmoothingSpline[SplinePPForm, float, Uni
 
     ydata : np.ndarray, array-like
         Input multivariate data vectors. N-D array.
-    tdata : np.ndarray, list
-        [Optional] Parametric vector of data sites with condition: `t1 < t2 < ... < tN`.
+
+    tdata : [*Optional*] np.ndarray, list
+        Parametric vector of data sites with condition: `t1 < t2 < ... < tN`.
         If it is not set will be computed automatically.
-    weights : np.ndarray, list
-        [Optional] Weights 1D vector with size equal of N
-    smooth : float
-        [Optional] Smoothing parameter in range [0, 1] where:
+
+    weights : [*Optional*] np.ndarray, list
+        Weights 1D vector with size equal of N
+
+    smooth : [*Optional*] float
+        Smoothing parameter in range [0, 1] where:
             - 0: The smoothing spline is the least-squares straight line fit
             - 1: The cubic spline interpolant with natural condition
+
     axis : int
         Axis along which "ydata" is assumed to be varying.
         Meaning that for x[i] the corresponding values are np.take(ydata, i, axis=axis).
@@ -391,7 +406,7 @@ def __call__(self, ti: UnivariateDataType):
 
     @property
     def smooth(self) -> float:
-        """Returns smooth factor
+        """Returns the smoothing parameter
 
         Returns
         -------
@@ -402,12 +417,12 @@ def smooth(self) -> float:
 
     @property
     def spline(self) -> SplinePPForm:
-        """Returns the spline description in 'SplinePPForm' instance
+        """Returns the spline description in `SplinePPForm` instance
 
         Returns
         -------
         spline : SplinePPForm
-            The spline description in 'SplinePPForm' instance
+            The spline description in :class:`SplinePPForm` instance
         """
         return self._univariate_spline.spline