Smoothing Splines#

Fractional and recursive smoothing-spline tools. SmoothingSplinePlan retains a real-FFT half-spectrum response for repeated arrays of one spatial shape. Explicit axes allow the remaining dimensions to serve as batch or channel axes in one batched FFT execution. Its periodic transfer function is checked against an independent dense-DFT fixture derived from the published fractional-spline estimator.

class splineops.smoothing_splines.smoothing_spline.SmoothingSplinePlan(shape: tuple[int, ...], lamb: float, gamma: float)#

Bases: object

Reusable real-FFT smoothing filter for a fixed array shape.

Constructing the frequency response is independent of the input samples. Keeping it in a plan avoids rebuilding frequency grids and the filter when smoothing multiple arrays with the same shape and parameters. The plan stores only the non-redundant real-FFT half spectrum.

Parameters:

  • shape (tuple of int) – Shape of every array that will be passed to apply().

  • lamb (float) – Non-negative regularization parameter.

  • gamma (float) – Positive order of the spline operator.

apply(data: NDArray, *, axes: Sequence[int] | None = None, out: NDArray | None = None) → NDArray#

Smooth selected axes and optionally copy the result into out.

Every unselected dimension is an independent batch or channel dimension. When data contains only the plan’s spatial dimensions, axes may be omitted.

property configuration: dict[str, object]#

Copy of the fixed spatial and frequency-response contract.

property retained_bytes: int#

Number of bytes retained for repeated execution.

splineops.smoothing_splines.smoothing_spline.periodize(x: NDArray, m: int) → NDArray#

Periodize the input array by concatenating m copies of it.

Parameters:

  • x (ndarray) – Input array to be periodized.

  • m (int) – Number of times to concatenate the array.

Returns:

xp – The periodized array, which has its size multiplied by m along the concatenation axis.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from splineops.smoothing_splines.smoothing_spline import periodize
>>> x = np.array([1, 2, 3])
>>> periodize(x, 2)
array([1, 2, 3, 1, 2, 3])
splineops.smoothing_splines.smoothing_spline.recursive_smoothing_spline(signal: NDArray, lamb: float = 1.0) → NDArray#

Apply a recursive first-order smoothing spline filter (piecewise-linear).

This implements the symmetric all-pole factorization (causal + anticausal) for the first-order smoothing spline filter.

Notes

  • This is NOT the cubic smoother (which requires a higher-order recursion).

  • Includes DC normalization so constant signals remain constant.

Parameters:

  • signal (ndarray) – 1D array of data points to smooth.

  • lamb (float, optional) – Smoothing parameter (>= 0). Default is 1.0.

Returns:

smoothed_signal – Smoothed data, same length as signal.

Return type:

ndarray

splineops.smoothing_splines.smoothing_spline.smoothing_spline(y: NDArray, lamb: float, m: int, gamma: float) → Tuple[NDArray, NDArray]#

Compute the fractional smoothing spline at m-times upsampling of the input.

This function returns samples of the smoothing spline for a given input sequence, sampled at m times the rate of the input. The input is assumed to be sampled at integer locations 0..N-1.

Parameters:

  • y (ndarray) – Input signal of length N.

  • lamb (float) – Regularization parameter.

  • m (int) – Upsampling factor (integer).

  • gamma (float) – Order of the spline operator. Typically gamma = H + 0.5.

Returns:

  • t (ndarray) – The upsampled time vector, of length approximately N * m.

  • ys (ndarray) – The smoothing spline samples, of length approximately N * m.

Examples

>>> import numpy as np
>>> from splineops.smoothing_splines.smoothing_spline import smoothing_spline
>>> y = np.array([1., 2., 3.])
>>> t, ys = smoothing_spline(y, lamb=0.1, m=2, gamma=1.5)
>>> t.shape, ys.shape
((6,), (6,))
splineops.smoothing_splines.smoothing_spline.smoothing_spline_nd(data: NDArray, lamb: float, gamma: float, *, axes: Sequence[int] | None = None, out: NDArray | None = None) → NDArray#

Apply multi-dimensional fractional smoothing spline to the input data.

Parameters:

  • data (ndarray) – Multi-dimensional input data (e.g., image or volume).

  • lamb (float) – Regularization parameter.

  • gamma (float) – Order of the spline operator (gamma = H + 0.5).

  • axes (sequence of int, optional) – Spatial dimensions to smooth. Required when batch or channel dimensions are present; every unselected slice is independent.

  • out (ndarray, optional) – Exact-shape and exact-result-dtype destination.

Returns:

data_smooth – Smoothed data of the same shape as data.

Return type:

ndarray

Examples

>>> import numpy as np
>>> from splineops.smoothing_splines.smoothing_spline import smoothing_spline_nd
>>> x = np.random.rand(4, 4)
>>> x_smooth = smoothing_spline_nd(x, lamb=0.5, gamma=1.0)
>>> x_smooth.shape
(4, 4)