finished #68 for smooth_finite_difference module

Author: pavelkomarov

pynumdiff/smooth_finite_difference/_smooth_finite_difference.py

@@ -26,8 +26,8 @@ def mediandiff(x, dt, params=None, options={}, window_size=5, num_iterations=1):
              - **dxdt_hat** -- estimated derivative of x
     """
     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)
+        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]
@@ -60,8 +60,8 @@ def meandiff(x, dt, params=None, options={}, window_size=5, num_iterations=1):
              - **dxdt_hat** -- estimated derivative of x
     """
     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)
+        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]
@@ -89,8 +89,8 @@ def gaussiandiff(x, dt, params=None, options={}, window_size=5, num_iterations=1
              - **dxdt_hat** -- estimated derivative of x
     """
     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)
+        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]
@@ -102,99 +102,65 @@ def gaussiandiff(x, dt, params=None, options={}, window_size=5, num_iterations=1
     return x_hat, dxdt_hat
 
 
-def friedrichsdiff(x, dt, params, options={}):
-    """
-    Perform friedrichs smoothing by convolving friedrichs 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 friedrichsdiff(x, dt, params=None, options={}, window_size=5, num_iterations=1):
+    """Perform friedrichs smoothing by convolving friedrichs kernel with x followed by first order finite difference
 
+    :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 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._friedrichs_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 butterdiff(x, dt, params, options={}):
-    """
-    Perform butterworth smoothing on x with scipy.signal.filtfilt
-    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: [n, wn], n  = order of the filter; wn = Cutoff frequency.
-                    For a discrete timeseries, the value is normalized to the range 0-1,
-                    where 1 is the Nyquist frequency.
-
-    :type params: list (int)
-
-    :param options: an empty dictionary or a dictionary with 2 key value pair
-
-                    - 'iterate': whether to run multiple iterations of the smoother. Note: iterate does nothing for median smoother.
-                    - 'padmethod': "pad" or "gust", see scipy.signal.filtfilt
-
-    :type options: dict {'iterate': (boolean), 'padmethod': string}
-
-    :return: a tuple consisting of:
-
-            - x_hat: estimated (smoothed) x
-            - dxdt_hat: estimated derivative of x
+def butterdiff(x, dt, params=None, options={}, filter_order=2, cutoff_freq=0.5, num_iterations=1):
+    """Perform butterworth smoothing on x with scipy.signal.filtfilt followed by first order finite difference
 
+    :param np.array[float] x: array of time series to differentiate
+    :param float dt: time step size
+    :param list[int] params: (**deprecated**, prefer :code:`filter_order`, :code:`cutoff_freq`,
+        and :code:`num_iterations`)
+    :param dict options: (**deprecated**, prefer :code:`num_iterations`) an empty dictionary or {'iterate': (bool)}
+    :param int filter_order: order of the filter
+    :param float cutoff_freq: cutoff frequency :math:`\\in [0, 1]`. For a discrete timeseries,
+        the value is normalized to the range 0-1, where 1 is the Nyquist frequency.
+    :param int num_iterations: how many times to apply 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:
-        n, wn, iterations = params
-    else:
-        iterations = 1
-        n, wn = 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 `filter_order`, " +
+            "`cutoff_freq`, and `num_iterations` instead.", DeprecationWarning)
+        filter_order, cutoff_freq = params[0:2]
+        if 'iterate' in options and options['iterate']:
+            num_iterations = params[2]
 
-    b, a = scipy.signal.butter(n, wn)
+    b, a = scipy.signal.butter(filter_order, cutoff_freq)
 
     x_hat = x
-    for _ in range(iterations):
-        if len(x) < 9:
-            x_hat = scipy.signal.filtfilt(b, a, x_hat, method="pad", padlen=len(x)-1)
-        else:
-            x_hat = scipy.signal.filtfilt(b, a, x_hat, method="pad")
+    padlen = len(x)-1 if len(x) < 9 else None
+    for _ in range(num_iterations):
+        x_hat = scipy.signal.filtfilt(b, a, x_hat, method="pad", padlen=padlen)
 
     x_hat, dxdt_hat = finite_difference(x_hat, dt)
 
@@ -204,48 +170,33 @@ def butterdiff(x, dt, params, options={}):
     return x_hat, dxdt_hat
 
 
-def splinediff(x, dt, params, options={}):
-    """
-    Perform spline smoothing on x with scipy.interpolate.UnivariateSpline
-    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: [k, s], k: Order of the spline. A kth order spline can be differentiated k times.
-                    s: Positive smoothing factor used to choose the number of knots.
-                    Number of knots will be increased until the smoothing condition is satisfied:
-                    sum((w[i] * (y[i]-spl(x[i])))**2, axis=0) <= s
-
-    :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 splinediff(x, dt, params=None, options={}, k=3, s=None, num_iterations=1):
+    """Perform spline smoothing on x with scipy.interpolate.UnivariateSpline followed by first order finite difference
 
+    :param np.array[float] x: array of time series to differentiate
+    :param float dt: time step size
+    :param list params: (**deprecated**, prefer :code:`order`, :code:`cutoff_freq`, and :code:`num_iterations`)
+    :param dict options: (**deprecated**, prefer :code:`num_iterations`) an empty dictionary or {'iterate': (bool)}
+    :param int k: polynomial order of the spline. A kth order spline can be differentiated k times.
+    :param float s: positive smoothing factor used to choose the number of knots. Number of knots will be increased
+        until the smoothing condition is satisfied: :math:`\\sum_t (x[t] - \\text{spline}[t])^2 \\leq s`
+    :param int num_iterations: how many times to apply 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:
-        k, s, iterations = params
-    else:
-        iterations = 1
-        k, s = 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 `k`, `s`, and " +
+            "`num_iterations` instead.", DeprecationWarning)
+        k, s = params[0:2]
+        if 'iterate' in options and options['iterate']:
+            num_iterations = params[2]
 
     t = np.arange(0, len(x)*dt, dt)
 
     x_hat = x
-    for _ in range(iterations):
+    for _ in range(num_iterations):
         spline = scipy.interpolate.UnivariateSpline(t, x_hat, k=k, s=s)
         x_hat = spline(t)