Adaptive Regression Splines#

Sparse piecewise-linear regression and total-variation denoising for 1-D data. DenoisingPlan reuses the factorization for fixed sample locations and can solve an explicit lambda path with warm-start state confined to that call. Convergence diagnostics remain opt-in, and path solving is not advertised as an unconditional speedup.

class splineops.adaptive_regression_splines.denoising.DenoisingDiagnostics(iterations: int, converged: bool, primal_residual: float, dual_residual: float)#

Bases: object

Convergence information for denoise_y().

Closed-form branches (zero regularization and the linear-regression limit) report zero iterations and residuals because ADMM is not entered.

converged: bool#
dual_residual: float#
iterations: int#
primal_residual: float#
class splineops.adaptive_regression_splines.denoising.DenoisingPlan(x: ndarray, rho: float = 1.0)#

Bases: object

Reusable factorization for TV denoising on fixed sample locations.

The expensive sparse factorization depends on x and rho, but not on the observations or regularization strength. A plan is therefore most useful for denoising many signals sampled at the same locations, or for a regularization-parameter sweep.

Parameters:

  • x (ndarray) – Strictly increasing one-dimensional sample locations.

  • rho (float, optional) – Positive ADMM penalty parameter.

property configuration: dict[str, object]#

Copy of the fixed factorization contract.

property retained_array_bytes: int#

Known bytes retained by sample and sparse-matrix arrays.

The sparse solver owns additional implementation-dependent factor storage that SciPy does not expose through a stable byte-count API.

solve(y: ndarray, lamb: float, *, max_iter: int = 10000, relative_tol: float = 1e-07, return_diagnostics: bool = False) → ndarray | tuple[ndarray, DenoisingDiagnostics]#

Denoise one signal while reusing this plan’s factorization.

solve_path(y: ndarray, lambdas: Iterable[float], *, max_iter: int = 10000, relative_tol: float = 1e-07, return_diagnostics: bool = False) → ndarray | tuple[ndarray, tuple[DenoisingDiagnostics, ...]]#

Solve an explicit regularization path with controlled warm starts.

Solutions are returned in the caller’s lambda order. ADMM state is carried only within this method call, so the plan remains free of hidden mutable warm-start state and independent calls are repeatable.

splineops.adaptive_regression_splines.denoising.denoise_y(x: ndarray, y: ndarray, lamb: float, rho: float = 1.0, max_iter: int = 10000, relative_tol: float = 1e-07, return_diagnostics: bool = False) → ndarray | tuple[ndarray, DenoisingDiagnostics]#

Performs total variation denoising on the y-coordinates using ADMM.

This function solves a convex optimization problem to smooth noisy data while preserving sharp transitions. The method is based on the Alternating Direction Method of Multipliers (ADMM), a powerful approach for distributed optimization.

The optimization problem solved is:

minimize || y - y_lambda ||_2^2 + λ || Dy ||_1

where D is a discrete difference operator, enforcing piecewise smoothness.

Parameters:

  • x (ndarray) – Array of x-coordinates of data points.

  • y (ndarray) – Array of y-coordinates (possibly noisy).

  • lamb (float) – Regularization parameter controlling the trade-off between data fidelity and smoothness.

  • rho (float, optional) – ADMM penalty parameter (default is 1.0).

  • max_iter (int, optional) – Maximum number of ADMM iterations (default is 1e4).

  • relative_tol (float, optional) – Tolerance for stopping criterion (default is 1e-7).

  • return_diagnostics (bool, optional) – If true, return (y_denoised, diagnostics). This opt-in form keeps the historical array-only return value as the default.

Returns:

y_lambda – Array of denoised y-coordinates, optionally paired with convergence diagnostics.

Return type:

ndarray or tuple

splineops.adaptive_regression_splines.sparsification.linear_spline(t: ndarray, knots: ndarray, amplitudes: ndarray, polynomial: ndarray) → ndarray#

Evaluates a parametrized linear spline at specified location(s) t.

The spline is represented as:

s(t) = at + b + sum_{k=0}^{K} a_k (t - τ_k)_+

where a and b are the parameters of the linear component, and a_k and τ_k are the amplitudes and locations of the knots, respectively.

Parameters:

  • t (float or ndarray) – The location(s) where the spline should be evaluated.

  • knots (ndarray) – Knot locations of the spline.

  • amplitudes (ndarray) – Amplitudes of the knots.

  • polynomial (ndarray) – Coefficients (b, a) of the linear component.

Returns:

values – The evaluated spline values at t.

Return type:

float or ndarray

splineops.adaptive_regression_splines.sparsification.sparsest_interpolant(x: ndarray, y: ndarray, sparsity_tol: float = 1e-05) → Tuple[ndarray, ndarray, ndarray]#

Computes the sparsest piecewise-linear spline that interpolates the given data points.

This function implements a method for finding the sparsest linear spline, based on total variation regularization on the second derivative. This approach promotes solutions with the fewest number of knots while maintaining fidelity to the data.

The optimal spline can be evaluated using the linear_spline() function with the outputs of this function.

Parameters:

  • x (ndarray) – Array of x-coordinates of data points.

  • y (ndarray) – Array of y-coordinates of data points.

  • sparsity_tol (float, optional) – Threshold for eliminating knots with small amplitude (default is 1e-5).

Returns:

  • knots (ndarray) – Array of knot locations for the optimal sparse spline.

  • amplitudes (ndarray) – Corresponding amplitudes of the knots.

  • polynomial (ndarray) – Coefficients (b, a) of the linear component p(t) = at + b.