total_variation_regularization

This module implements some common total variation regularization methods.

pynumdiff.total_variation_regularization.tvrdiff(x, dt, order, gamma, huberM=inf, solver=None, axis=0)

Generalized total variation regularized derivatives. Use convex optimization (cvxpy) to solve for a total variation regularized derivative. Other convex-solver-based methods in this module call this function.

Parameters:

x (np.array[float]) – data to differentiate. May be multidimensional; see axis.
dt (float) – step size
order (int) – 1, 2, or 3, the derivative to regularize
gamma (float) – regularization parameter
huberM (float) – Huber loss parameter, in units of scaled median absolute deviation of input data. \(M = \infty\) reduces to \(\ell_2\) loss squared on first, fidelity cost term, and \(M = 0\) reduces to \(\ell_1\) loss, which seeks sparse residuals.
solver (str) – Solver to use. Solver options include: ‘MOSEK’, ‘CVXOPT’, ‘CLARABEL’, ‘ECOS’. If not given, fall back to CVXPY’s default.
axis (int) – data dimension along which differentiation is performed

Returns:

x_hat (np.array) – estimated (smoothed) x
dxdt_hat (np.array) – estimated derivative of x

pynumdiff.total_variation_regularization.velocity(x, dt, params=None, options=None, gamma=None, solver=None)

Use convex optimization (cvxpy) to solve for the velocity total variation regularized derivative.

Deprecated, prefer tvrdiff with order 1 instead.

Parameters:

x (np.array[float]) – data to differentiate
dt (float) – step size
params – (deprecated, prefer gamma)
options (dict) – (deprecated, prefer solver) a dictionary consisting of {‘solver’: (str)}
gamma (float) – the regularization parameter
solver (str) – the solver CVXPY should use, ‘MOSEK’, ‘CVXOPT’, ‘CLARABEL’, ‘ECOS’, etc. If not given, fall back to CVXPY’s default.

Returns:

x_hat (np.array) – estimated (smoothed) x
dxdt_hat (np.array) – estimated derivative of x

pynumdiff.total_variation_regularization.acceleration(x, dt, params=None, options=None, gamma=None, solver=None)

Use convex optimization (cvxpy) to solve for the acceleration total variation regularized derivative.

Deprecated, prefer tvrdiff with order 2 instead.

Parameters:

x (np.array[float]) – data to differentiate
dt (float) – step size
params – (deprecated, prefer gamma)
options (dict) – (deprecated, prefer solver) a dictionary consisting of {‘solver’: (str)}
gamma (float) – the regularization parameter
solver (str) – the solver CVXPY should use, ‘MOSEK’, ‘CVXOPT’, ‘CLARABEL’, ‘ECOS’, etc. In testing, ‘MOSEK’ was the most robust. If not given, fall back to CVXPY’s default.

Returns:

x_hat (np.array) – estimated (smoothed) x
dxdt_hat (np.array) – estimated derivative of x

pynumdiff.total_variation_regularization.jerk(x, dt, params=None, options=None, gamma=None, solver=None)

Use convex optimization (cvxpy) to solve for the jerk total variation regularized derivative.

Deprecated, prefer tvrdiff with order 3 instead.

Parameters:

x (np.array[float]) – data to differentiate
dt (float) – step size
params – (deprecated, prefer gamma)
options (dict) – (deprecated, prefer solver) a dictionary consisting of {‘solver’: (str)}
gamma (float) – the regularization parameter
solver (str) – the solver CVXPY should use, ‘MOSEK’, ‘CVXOPT’, ‘CLARABEL’, ‘ECOS’, etc. In testing, ‘MOSEK’ was the most robust. If not given, fall back to CVXPY’s default.

Returns:

x_hat (np.array) – estimated (smoothed) x
dxdt_hat (np.array) – estimated derivative of x

pynumdiff.total_variation_regularization.iterative_velocity(x, dt, params=None, options=None, num_iterations=None, gamma=None, cg_maxiter=1000, scale='small')

Use an iterative solver to find the total variation regularized 1st derivative. See _chartrand_tvregdiff.py for details, author info, and license. Methods described in: 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

Parameters:

x (np.array[float]) – data to differentiate
dt (float) – step size
params (list) – (deprecated, prefer num_iterations and gamma)
options (dict) – (deprecated, prefer cg_maxiter and scale) a dictionary consisting of {‘cg_maxiter’: (int), ‘scale’: (str)}
num_iterations (int) – number of iterations to run the solver. More iterations results in blockier derivatives, which approach the convex result
gamma (float) – regularization parameter
cg_maxiter (int) – Max number of iterations to use in scipy.sparse.linalg.cg. Default None results in maxiter = len(x). This works well in our test examples.
scale (str) – This method has two different numerical options. From _chartrand_tvregdiff.py: 'large' or 'small' (case insensitive). Default is 'small'. 'small' has somewhat better boundary behavior, but becomes unwieldly for data larger than 1000 entries or so. 'large' has simpler numerics and is more efficient for large-scale problems. 'large' is more readily modified for higher-order derivatives, since the implicit differentiation matrix is square.

Returns:

x_hat (np.array) – estimated (smoothed) x
dxdt_hat (np.array) – estimated derivative of x

pynumdiff.total_variation_regularization.smooth_acceleration(x, dt, params=None, options=None, gamma=None, window_size=None, solver=None)

Use convex optimization (cvxpy) to solve for the acceleration total variation regularized derivative, and then apply a convolutional gaussian smoother to the resulting derivative to smooth out the peaks. The end result is similar to the jerk method, but can be more time-efficient.

Parameters:

x (np.array[float]) – data to differentiate
dt (float) – step size
params – (deprecated, prefer gamma and window_size)
options (dict) – (deprecated, prefer solver) a dictionary consisting of {‘solver’: (str)}
gamma (float) – the regularization parameter
window_size (int) – window size for gaussian kernel
solver (str) – the solver CVXPY should use, ‘MOSEK’, ‘CVXOPT’, ‘CLARABEL’, ‘ECOS’, etc. In testing, ‘MOSEK’ was the most robust. If not given, fall back to CVXPY’s default.

Returns:

x_hat (np.array) – estimated (smoothed) x
dxdt_hat (np.array) – estimated derivative of x