halfway through the docstrings, and then gotta add them to the new unittest structure. Should be easy.

Author: pavelkomarov

pynumdiff/smooth_finite_difference/_smooth_finite_difference.py

@@ -1,5 +1,6 @@
 import numpy as np
 import scipy.signal
+from warnings import warn
 
 # included code
 from pynumdiff.finite_difference import first_order as finite_difference
@@ -9,140 +10,93 @@
 ################################
 # Smoothing finite differences #
 ################################
-def mediandiff(x, dt, params, options={}):
-    """
-    Perform median smoothing using scipy.signal.medfilt
-    followed by first order finite difference
-
-    :param x: array of time series to differentiate
-    :type x: np.array (float)
-
-    :param dt: time step size
-    :type dt: float
-
-    :param params: filter window size
-    :type params: list (int) or int
-
-    :param options: an empty dictionary or a dictionary with 1 key value pair
-
-                    - 'iterate': whether to run multiple iterations of the smoother. Note: iterate does nothing for median smoother.
-
-    :type options: dict {'iterate': (boolean)}
+def mediandiff(x, dt, params=None, options={}, window_size=5, num_iterations=1):
+    """Perform median smoothing using scipy.signal.medfilt followed by first order finite difference
 
-    :return: a tuple consisting of:
-
-            - x_hat: estimated (smoothed) x
-            - dxdt_hat: estimated derivative of x
+    :param np.array[float] x: array of time series to differentiate
+    :param float dt: time step size
+    :param list[int] params: (**deprecated**, prefer :code:`window_size` and :code:`num_iterations`)
+    :param dict options: (**deprecated**, prefer :code:`num_iterations`) an empty dictionary or {'iterate': (bool)}
+    :param int window_size: filter window size
+    :param int num_iterations: how many times to apply median smoothing
 
 
-    :rtype: tuple -> (np.array, np.array)
+    :return: tuple[np.array, np.array] of\n
+             - **x_hat** -- estimated (smoothed) x
+             - **dxdt_hat** -- estimated derivative of x
     """
-
-    if 'iterate' in options.keys() and options['iterate'] is True:
-        window_size, iterations = params
-    else:
-        iterations = 1
-        if isinstance(params, list):
-            window_size = params[0]
-        else:
-            window_size = params
+    if params != None: # Warning to support old interface for a while. Remove these lines along with params in a future release.
+        warn("""`params` and `options` parameters will be removed in a future version. Use `window_size`
+            and `num_iterations` instead.""", DeprecationWarning)
+        window_size = params[0] if isinstance(params, list) else params
+        if 'iterate' in options and options['iterate']:
+            num_iterations = params[1]
 
     if not window_size % 2:
-        window_size += 1 # assert window_size % 2 == 1  # is odd
+        window_size += 1 # make sure window_size is odd
 
     x_hat = x
-    for _ in range(iterations):
+    for _ in range(num_iterations):
         x_hat = scipy.signal.medfilt(x_hat, window_size)
     x_hat, dxdt_hat = finite_difference(x_hat, dt)
 
     return x_hat, dxdt_hat
 
 
-def meandiff(x, dt, params, options={}):
-    """
-    Perform mean smoothing by convolving mean kernel with x
-    followed by first order finite difference
+def meandiff(x, dt, params=None, options={}, window_size=5, num_iterations=1):
+    """Perform mean smoothing by convolving mean kernel with x followed by first order finite difference
 
     :param np.ndarray[float] x: array of time series to differentiate
     :param float dt: time step size
 
-    :param params: [filter_window_size] or if 'iterate' in options:
-                    [filter_window_size, num_iterations]
-
-    :type params: list (int)
-
-    :param options: an empty dictionary or a dictionary with 1 key value pair
-
-                    - 'iterate': whether to run multiple iterations of the smoother. Note: iterate does nothing for median smoother.
-
-    :type options: dict {'iterate': (boolean)}
-
-    :return: a tuple consisting of:
-
-            - x_hat: estimated (smoothed) x
-            - dxdt_hat: estimated derivative of x
-
+    :param list[int] params: (**deprecated**, prefer :code:`window_size` and :code:`num_iterations`)
+        :code:`[window_size]` or, :code:`if 'iterate' in options`, :code:`[window_size, num_iterations]`
+    :param dict options: (**deprecated**, prefer :code:`num_iterations`) an empty dictionary or {'iterate': (bool)}
+    :param int window_size: filter window size
+    :param int num_iterations: how many times to apply mean smoothing
 
-    :rtype: tuple -> (np.array, np.array)
+    :return: tuple[np.array, np.array] of\n
+             - **x_hat** -- estimated (smoothed) x
+             - **dxdt_hat** -- estimated derivative of x
     """
-
-    if 'iterate' in options.keys() and options['iterate'] is True:
-        window_size, iterations = params
-    else:
-        iterations = 1
-        if isinstance(params, list):
-            window_size = params[0]
-        else:
-            window_size = params
+    if params != None: # Warning to support old interface for a while. Remove these lines along with params in a future release.
+        warn("""`params` and `options` parameters will be removed in a future version. Use `window_size`
+            and `num_iterations` instead.""", DeprecationWarning)
+        window_size = params[0] if isinstance(params, list) else params
+        if 'iterate' in options and options['iterate']:
+            num_iterations = params[1]
 
     kernel = utility._mean_kernel(window_size)
-    x_hat = utility.convolutional_smoother(x, kernel, iterations)
+    x_hat = utility.convolutional_smoother(x, kernel, num_iterations)
     x_hat, dxdt_hat = finite_difference(x_hat, dt)
 
     return x_hat, dxdt_hat
 
 
-def gaussiandiff(x, dt, params, options={}):
-    """
-    Perform gaussian smoothing by convolving gaussian kernel with x
-    followed by first order finite difference
-
-    :param x: array of time series to differentiate
-    :type x: np.array (float)
-
-    :param dt: time step size
-    :type dt: float
-
-    :param params: [filter_window_size] or if 'iterate' in options:
-                    [filter_window_size, num_iterations]
-
-    :type params: list (int)
-
-    :param options: an empty dictionary or a dictionary with 1 key value pair
-
-                    - 'iterate': whether to run multiple iterations of the smoother. Note: iterate does nothing for median smoother.
-
-    :type options: dict {'iterate': (boolean)}
-
-    :return: a tuple consisting of:
-
-            - x_hat: estimated (smoothed) x
-            - dxdt_hat: estimated derivative of x
-
+def gaussiandiff(x, dt, params=None, options={}, window_size=5, num_iterations=1):
+    """Perform gaussian smoothing by convolving gaussian kernel with x followed by first order finite difference
 
-    :rtype: tuple -> (np.array, np.array)
+    :param np.array[float] x: array of time series to differentiate
+    :param float dt: time step size
+    :param list[int] params: (**deprecated**, prefer :code:`window_size` and :code:`num_iterations`)
+        :code:`[window_size]` or, :code:`if 'iterate' in options`, :code:`[window_size, num_iterations]`
+    :param dict options: (**deprecated**, prefer :code:`num_iterations`) an empty dictionary or {'iterate': (bool)}
+    :param int window_size: filter window size
+    :param int num_iterations: how many times to apply gaussian smoothing
+
+    :return: tuple[np.array, np.array] of\n
+             - **x_hat** -- estimated (smoothed) x
+             - **dxdt_hat** -- estimated derivative of x
     """
-    if 'iterate' in options.keys() and options['iterate'] is True:
-        window_size, iterations = params
-    else:
-        iterations = 1
-        if isinstance(params, list):
-            window_size = params[0]
-        else:
-            window_size = params
+    if params != None: # Warning to support old interface for a while. Remove these lines along with params in a future release.
+        warn("""`params` and `options` parameters will be removed in a future version. Use `window_size`
+            and `num_iterations` instead.""", DeprecationWarning)
+        window_size = params[0] if isinstance(params, list) else params
+        if 'iterate' in options and options['iterate']:
+            num_iterations = params[1]
 
     kernel = utility._gaussian_kernel(window_size)
-    x_hat = utility.convolutional_smoother(x, kernel, iterations)
+    x_hat = utility.convolutional_smoother(x, kernel, num_iterations)
     x_hat, dxdt_hat = finite_difference(x_hat, dt)
 
     return x_hat, dxdt_hat