diff --git a/pynumdiff/finite_difference/_finite_difference.py b/pynumdiff/finite_difference/_finite_difference.py index 3397e14..bfc44c1 100644 --- a/pynumdiff/finite_difference/_finite_difference.py +++ b/pynumdiff/finite_difference/_finite_difference.py @@ -6,8 +6,8 @@ def first_order(x, dt, params=None, options={}, num_iterations=None): """First-order centered difference method - :param np.array[float] x: array of time series to differentiate - :param float dt: time step size + :param np.array[float] x: data to differentiate + :param float dt: step size :param list[float] or float params: (**deprecated**, prefer :code:`num_iterations`) :param dict options: (**deprecated**, prefer :code:`num_iterations`) a dictionary consisting of {'iterate': (bool)} :param int num_iterations: If performing iterated FD to smooth the estimates, give the number of iterations. @@ -34,8 +34,8 @@ def first_order(x, dt, params=None, options={}, num_iterations=None): def second_order(x, dt): """Second-order centered difference method - :param np.array[float] x: array of time series to differentiate - :param float dt: time step size + :param np.array[float] x: data to differentiate + :param float dt: step size :return: tuple[np.array, np.array] of\n - **x_hat** -- estimated (smoothed) x @@ -60,8 +60,8 @@ def _x_hat_using_finite_difference(x, dt): def _iterate_first_order(x, dt, num_iterations): """Iterative first order centered finite difference. - :param np.array[float] x: array of time series to differentiate - :param float dt: time step size + :param np.array[float] x: data to differentiate + :param float dt: step size :param int num_iterations: number of iterations :return: tuple[np.array, np.array] of\n diff --git a/pynumdiff/kalman_smooth/_kalman_smooth.py b/pynumdiff/kalman_smooth/_kalman_smooth.py index c27e618..225ca55 100644 --- a/pynumdiff/kalman_smooth/_kalman_smooth.py +++ b/pynumdiff/kalman_smooth/_kalman_smooth.py @@ -109,7 +109,7 @@ def constant_velocity(x, dt, params=None, options=None, r=None, q=None, forwardb """Run a forward-backward constant velocity RTS Kalman smoother to estimate the derivative. :param np.array[float] x: data series to differentiate - :param float dt: time step size + :param float dt: step size :param list[float] params: (**deprecated**, prefer :code:`r` and :code:`q`) :param options: (**deprecated**, prefer :code:`forwardbackward`) a dictionary consisting of {'forwardbackward': (bool)} @@ -144,7 +144,7 @@ def constant_acceleration(x, dt, params=None, options=None, r=None, q=None, forw """Run a forward-backward constant acceleration RTS Kalman smoother to estimate the derivative. :param np.array[float] x: data series to differentiate - :param float dt: time step size + :param float dt: step size :param list[float] params: (**deprecated**, prefer :code:`r` and :code:`q`) :param options: (**deprecated**, prefer :code:`forwardbackward`) a dictionary consisting of {'forwardbackward': (bool)} @@ -183,7 +183,7 @@ def constant_jerk(x, dt, params=None, options=None, r=None, q=None, forwardbackw """Run a forward-backward constant jerk RTS Kalman smoother to estimate the derivative. :param np.array[float] x: data series to differentiate - :param float dt: time step size + :param float dt: step size :param list[float] params: (**deprecated**, prefer :code:`r` and :code:`q`) :param options: (**deprecated**, prefer :code:`forwardbackward`) a dictionary consisting of {'forwardbackward': (bool)} diff --git a/pynumdiff/linear_model/_linear_model.py b/pynumdiff/linear_model/_linear_model.py index 8262615..61ae6f1 100644 --- a/pynumdiff/linear_model/_linear_model.py +++ b/pynumdiff/linear_model/_linear_model.py @@ -19,7 +19,7 @@ def _slide_function(func, x, dt, args, window_size, step_size, kernel_name): """Slide a smoothing derivative function across a timeseries with specified window size. :param callable func: name of the function to slide - :param np.array[float] x: time series to differentiate + :param np.array[float] x: data to differentiate :param float dt: time step :param dict args: see func for requirements :param int window_size: size of the sliding window @@ -97,8 +97,8 @@ def _slide_function(func, x, dt, args, window_size, step_size, kernel_name): def savgoldiff(x, dt, params=None, options=None, polynomial_order=None, window_size=None, smoothing_win=None): """Use the Savitzky-Golay to smooth the data and calculate the first derivative. It wses scipy.signal.savgol_filter. The Savitzky-Golay is very similar to the sliding polynomial fit, but slightly noisier, and much faster - :param np.array[float] x: array of time series to differentiate - :param float dt: time step size + :param np.array[float] x: data to differentiate + :param float dt: step size :param list params: (**deprecated**, prefer :code:`polynomial_order`, :code:`window_size`, and :code:`smoothing_win`) :param dict options: (**deprecated**) :param int polynomial_order: order of the polynomial @@ -146,7 +146,7 @@ def savgoldiff(x, dt, params=None, options=None, polynomial_order=None, window_s def _polydiff(x, dt, polynomial_order, weights=None): """Fit polynomials to the timeseries, and differentiate the polynomials. - :param np.array[float] x: time series to differentiate + :param np.array[float] x: data to differentiate :param float dt: time step :param int polynomial_order: order of the polynomial :param np.array[float] weights: weights applied to each point in calculating the polynomial fit. @@ -172,10 +172,10 @@ def _polydiff(x, dt, polynomial_order, weights=None): def polydiff(x, dt, params=None, options=None, polynomial_order=None, window_size=None, sliding=True, step_size=1, kernel='friedrichs'): - """Fit polynomials to the time series, and differentiate the polynomials. + """Fit polynomials to the data, and differentiate the polynomials. - :param np.array[float] x: array of time series to differentiate - :param float dt: time step size + :param np.array[float] x: data to differentiate + :param float dt: step size :param list[int] params: (**deprecated**, prefer :code:`polynomial_order` and :code:`window_size`) :param dict options: (**deprecated**, prefer :code:`sliding`, :code:`step_size`, and :code:`kernel`) a dictionary consisting of {'sliding': (bool), 'step_size': (int), 'kernel_name': (str)} @@ -219,7 +219,7 @@ def polydiff(x, dt, params=None, options=None, polynomial_order=None, window_siz # """ # Fit the timeseries with chebyshev polynomials, and differentiate this model. -# :param x: (np.array of floats, 1xN) time series to differentiate +# :param x: (np.array of floats, 1xN) data to differentiate # :param dt: (float) time step # :param params: (list) [N] : (int) order of the polynomial # :param options: @@ -253,10 +253,10 @@ def polydiff(x, dt, params=None, options=None, polynomial_order=None, window_siz # """ # Slide a smoothing derivative function across a times eries with specified window size. -# :param x: array of time series to differentiate +# :param x: data to differentiate # :type x: np.array (float) -# :param dt: time step size +# :param dt: step size # :type dt: float # :param params: a list of 2 elements: @@ -356,7 +356,7 @@ def __integrate_dxdt_hat_matrix__(dxdt_hat, dt): def _lineardiff(x, dt, N, gamma, solver=None, weights=None): """Estimate the parameters for a system xdot = Ax, and use that to calculate the derivative - :param np.array[float] x: time series to differentiate + :param np.array[float] x: data to differentiate :param float dt: time step :param int > 1 N: order (e.g. 2: velocity; 3: acceleration) :param float gamma: regularization term @@ -404,10 +404,10 @@ def _lineardiff(x, dt, N, gamma, solver=None, weights=None): def lineardiff(x, dt, params=None, options=None, order=None, gamma=None, window_size=None, sliding=True, step_size=10, kernel='friedrichs', solver=None): - """Slide a smoothing derivative function across a time series with specified window size. + """Slide a smoothing derivative function across data, with specified window size. - :param np.array[float] x: array of time series to differentiate - :param float dt: time step size + :param np.array[float] x: data to differentiate + :param float dt: step size :param list[int, float, int] params: (**deprecated**, prefer :code:`order`, :code:`gamma`, and :code:`window_size`) :param dict options: (**deprecated**, prefer :code:`sliding`, :code:`step_size`, :code:`kernel`, and :code:`solver` a dictionary consisting of {'sliding': (bool), 'step_size': (int), 'kernel_name': (str), 'solver': (str)} @@ -466,14 +466,14 @@ def lineardiff(x, dt, params=None, options=None, order=None, gamma=None, window_ def spectraldiff(x, dt, params=None, options=None, high_freq_cutoff=None, even_extension=True, pad_to_zero_dxdt=True): """Take a derivative in the fourier domain, with high frequency attentuation. - :param np.array[float] x: array of time series to differentiate - :param float dt: time step size + :param np.array[float] x: data to differentiate + :param float dt: step size :param list[float] or float params: (**deprecated**, prefer :code:`high_freq_cutoff`) :param dict options: (**deprecated**, prefer :code:`even_extension` and :code:`pad_to_zero_dxdt`) a dictionary consisting of {'even_extension': (bool), 'pad_to_zero_dxdt': (bool)} :param float high_freq_cutoff: The high frequency cutoff. Frequencies below this threshold will be kept, and above will be zeroed. - :param bool even_extension: if True, extend the time series with an even extension so signal starts and ends at the same value. - :param bool pad_to_zero_dxdt: if True, extend the time series with extensions that smoothly force the derivative to zero. This + :param bool even_extension: if True, extend the data with an even extension so signal starts and ends at the same value. + :param bool pad_to_zero_dxdt: if True, extend the data with extensions that smoothly force the derivative to zero. This allows the spectral derivative to fit data which does not start and end with derivatives equal to zero. :return: tuple[np.array, np.array] of\n diff --git a/pynumdiff/smooth_finite_difference/_smooth_finite_difference.py b/pynumdiff/smooth_finite_difference/_smooth_finite_difference.py index f66c924..88fecd7 100644 --- a/pynumdiff/smooth_finite_difference/_smooth_finite_difference.py +++ b/pynumdiff/smooth_finite_difference/_smooth_finite_difference.py @@ -13,8 +13,8 @@ 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 - :param np.array[float] x: array of time series to differentiate - :param float dt: time step size + :param np.array[float] x: data to differentiate + :param float dt: 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 @@ -46,8 +46,8 @@ def mediandiff(x, dt, params=None, options={}, window_size=5, num_iterations=1): 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 np.ndarray[float] x: data to differentiate + :param float dt: 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]` @@ -76,8 +76,8 @@ def meandiff(x, dt, params=None, options={}, window_size=5, num_iterations=1): 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 - :param np.array[float] x: array of time series to differentiate - :param float dt: time step size + :param np.array[float] x: data to differentiate + :param float dt: 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)} @@ -105,8 +105,8 @@ def gaussiandiff(x, dt, params=None, options={}, window_size=5, num_iterations=1 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 np.array[float] x: data to differentiate + :param float dt: 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)} @@ -134,14 +134,14 @@ def friedrichsdiff(x, dt, params=None, options={}, window_size=5, num_iterations 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 np.array[float] x: data to differentiate + :param float dt: 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 float cutoff_freq: cutoff frequency :math:`\\in [0, 1]`. For a discrete vector, 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 :return: tuple[np.array, np.array] of\n @@ -173,8 +173,8 @@ def butterdiff(x, dt, params=None, options={}, filter_order=2, cutoff_freq=0.5, def splinediff(x, dt, params=None, options={}, order=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 np.array[float] x: data to differentiate + :param float dt: 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 order: polynomial order of the spline. A kth order spline can be differentiated k times. diff --git a/pynumdiff/total_variation_regularization/_total_variation_regularization.py b/pynumdiff/total_variation_regularization/_total_variation_regularization.py index bc380c0..0ac9998 100644 --- a/pynumdiff/total_variation_regularization/_total_variation_regularization.py +++ b/pynumdiff/total_variation_regularization/_total_variation_regularization.py @@ -14,8 +14,8 @@ def iterative_velocity(x, dt, params, options=None, num_iterations=None, gamma=N Rick Chartrand, "Numerical differentiation of noisy, nonsmooth data," ISRN Applied Mathematics, Vol. 2011, Article ID 164564, 2011. Original code at https://sites.google.com/site/dnartrahckcir/home/tvdiff-code - :param np.array[float] x: array of time series to differentiate - :param float dt: time step size + :param np.array[float] x: data to differentiate + :param float dt: step size :param list params: (**deprecated**, prefer :code:`num_iterations` and :code:`gamma`) :param dict options: (**deprecated**, prefer :code:`cg_maxiter` and :code:`scale`) a dictionary consisting of {'cg_maxiter': (int), 'scale': (str)} @@ -59,7 +59,7 @@ def _total_variation_regularized_derivative(x, dt, order, gamma, solver=None): total variation regularized derivative. :param np.array[float] x: data to differentiate - :param float dt: time step + :param float dt: step size :param int order: 1, 2, or 3, the derivative to regularize :param float gamma: regularization parameter :param str solver: Solver to use. Solver options include: 'MOSEK', 'CVXOPT', 'CLARABEL', 'ECOS'. @@ -112,7 +112,7 @@ def velocity(x, dt, params, options=None, gamma=None, solver=None): """Use convex optimization (cvxpy) to solve for the velocity total variation regularized derivative. :param np.array[float] x: data to differentiate - :param float dt: time step size + :param float dt: step size :param params: (**deprecated**, prefer :code:`gamma`) :param dict options: (**deprecated**, prefer :code:`solver`) a dictionary consisting of {'solver': (str)} :param float gamma: the regularization parameter @@ -139,7 +139,7 @@ def acceleration(x, dt, params, options=None, gamma=None, solver=None): """Use convex optimization (cvxpy) to solve for the acceleration total variation regularized derivative. :param np.array[float] x: data to differentiate - :param float dt: time step size + :param float dt: step size :param params: (**deprecated**, prefer :code:`gamma`) :param dict options: (**deprecated**, prefer :code:`solver`) a dictionary consisting of {'solver': (str)} :param float gamma: the regularization parameter @@ -166,7 +166,7 @@ def jerk(x, dt, params, options=None, gamma=None, solver=None): """Use convex optimization (cvxpy) to solve for the jerk total variation regularized derivative. :param np.array[float] x: data to differentiate - :param float dt: time step size + :param float dt: step size :param params: (**deprecated**, prefer :code:`gamma`) :param dict options: (**deprecated**, prefer :code:`solver`) a dictionary consisting of {'solver': (str)} :param float gamma: the regularization parameter @@ -195,7 +195,7 @@ def smooth_acceleration(x, dt, params, options=None, gamma=None, window_size=Non The end result is similar to the jerk method, but can be more time-efficient. :param np.array[float] x: data to differentiate - :param float dt: time step size + :param float dt: step size :param params: (**deprecated**, prefer :code:`gamma` and :code:`window_size`) :param dict options: (**deprecated**, prefer :code:`solver`) a dictionary consisting of {'solver': (str)} :param float gamma: the regularization parameter @@ -232,7 +232,7 @@ def jerk_sliding(x, dt, params, options=None, gamma=None, solver=None): """Use convex optimization (cvxpy) to solve for the jerk total variation regularized derivative. :param np.array[float] x: data to differentiate - :param float dt: time step size + :param float dt: step size :param params: (**deprecated**, prefer :code:`gamma`) :param dict options: (**deprecated**, prefer :code:`solver`) a dictionary consisting of {'solver': (str)} :param float gamma: the regularization parameter diff --git a/pynumdiff/utils/evaluate.py b/pynumdiff/utils/evaluate.py index 9ee3ee8..cc9f0a0 100644 --- a/pynumdiff/utils/evaluate.py +++ b/pynumdiff/utils/evaluate.py @@ -20,7 +20,7 @@ def plot(x, dt, x_hat, dxdt_hat, x_truth, dxdt_truth, xlim=None, ax_x=None, ax_d :param x: array of noisy time series :type x: np.array (float) - :param dt: a float number representing the time step size + :param dt: a float number representing the step size :type dt: float :param x_hat: array of smoothed estimation of x diff --git a/pynumdiff/utils/simulate.py b/pynumdiff/utils/simulate.py index 5a389d8..03b849d 100644 --- a/pynumdiff/utils/simulate.py +++ b/pynumdiff/utils/simulate.py @@ -54,7 +54,7 @@ def sine(timeseries_length=4, noise_type='normal', noise_parameters=(0, 0.5), ra :param random_seed: an integer seed used to initialize the random number generator :type random_seed: int, optional - :param dt: a float number representing the time step size + :param dt: a float number representing the step size :type dt: float, optional :param simdt: a float number representing the the real simulation step size we use to generate the time series, @@ -116,7 +116,7 @@ def triangle(timeseries_length=4, noise_type='normal', noise_parameters=(0, 0.5) :param random_seed: an integer seed used to initialize the random number generator :type random_seed: int, optional - :param dt: a float number representing the time step size + :param dt: a float number representing the step size :type dt: float, optional :param simdt: a float number representing the the real simulation step size we use to generate the time series, @@ -191,7 +191,7 @@ def pop_dyn(timeseries_length=4, noise_type='normal', noise_parameters=(0, 0.5), :param random_seed: an integer seed used to initialize the random number generator :type random_seed: int, optional - :param dt: a float number representing the time step size + :param dt: a float number representing the step size :type dt: float, optional :param simdt: a float number representing the the real simulation step size we use to generate the time series, @@ -252,7 +252,7 @@ def linear_autonomous(timeseries_length=4, noise_type='normal', noise_parameters :param random_seed: an integer seed used to initialize the random number generator :type random_seed: int, optional - :param dt: a float number representing the time step size + :param dt: a float number representing the step size :type dt: float, optional :param simdt: a float number representing the the real simulation step size we use to generate the time series, @@ -306,7 +306,7 @@ def pi_control(timeseries_length=4, noise_type='normal', noise_parameters=(0, 0. :param random_seed: an integer seed used to initialize the random number generator :type random_seed: int, optional - :param dt: a float number representing the time step size + :param dt: a float number representing the step size :type dt: float, optional :param simdt: a float number representing the the real simulation step size we use to generate the time series, @@ -362,7 +362,7 @@ def lorenz_x(timeseries_length=4, noise_type='normal', noise_parameters=(0, 0.5) :param random_seed: an integer seed used to initialize the random number generator :type random_seed: int, optional - :param dt: a float number representing the time step size + :param dt: a float number representing the step size :type dt: float, optional :param simdt: a float number representing the the real simulation step size we use to generate the time series, @@ -407,7 +407,7 @@ def lorenz_xyz(timeseries_length=4, noise_type='normal', noise_parameters=(0, 0. :param random_seed: an integer seed used to initialize the random number generator :type random_seed: int, optional - :param dt: a float number representing the time step size + :param dt: a float number representing the step size :type dt: float, optional :param simdt: a float number representing the the real simulation step size we use to generate the time series, @@ -498,7 +498,7 @@ def rk4_lorenz_xyz(timeseries_length=4, noise_type='normal', noise_parameters=(0 :param random_seed: an integer seed used to initialize the random number generator :type random_seed: int, optional - :param dt: a float number representing the time step size + :param dt: a float number representing the step size :type dt: float, optional :param normalize: whether to roughly normalize the time series