ml4gw.transforms.spline_interpolation

Adaptation of code from https://github.com/dottormale/Qtransform

Classes

SplineInterpolate(x_in[, y_in, kx, ky, sx, ...])

Perform 1D or 2D spline interpolation based on De Boor's method.
class ml4gw.transforms.spline_interpolation.SplineInterpolate(x_in, y_in=None, kx=3, ky=3, sx=0.001, sy=0.001, x_out=None, y_out=None)

Bases: Module

Perform 1D or 2D spline interpolation based on De Boor's method. Supports batched, multi-channel inputs, so acceptable data shapes are (width), (height, width), (batch, width), (batch, height, width), (batch, channel, width), and (batch, channel, height, width).

During initialization of this Module, both the desired input and output coordinate Tensors can be specified to allow pre-computation of the B-spline basis matrices, though the only mandatory argument is the coordinates of the data along the width dimension. If no argument is given for coordinates along the height dimension, it is assumed that 1D interpolation is desired.

Unlike scipy's implementation of spline interpolation, the data to be interpolated is not passed until actually calling the object. This is useful for cases where the input and output coordinates are known in advance, but the data is not, so that the interpolator can be set up ahead of time.

WARNING: compared to scipy's spline interpolation, this method produces edge artifacts when the output coordinates are near the boundaries of the input coordinates. Therefore, it is recommended to interpolate only to coordinates that are well within the input coordinate range. Unfortunately, the specific definition of "well within" changes based on the size of the data, so some testing may be required to get good results.

Parameters:

  • x_in (Tensor) -- Coordinates of the width dimension of the data

  • y_in (Optional[Tensor]) -- Coordinates of the height dimension of the data. If not specified, it is assumed the 1D interpolation is desired, and so the default value is a Tensor of length 1

  • kx (int) -- Degree of spline interpolation along the width dimension. Default is cubic.

  • ky (int) -- Degree of spline interpolation along the height dimension. Default is cubic.

  • sx (float) -- Regularization factor to avoid singularities during matrix inversion for interpolation along the width dimension. Not to be confused with the s parameter in scipy's spline methods, which controls the number of knots.

  • sy (float) -- Regularization factor to avoid singularities during matrix inversion for interpolation along the height dimension.

  • x_out (Optional[Tensor]) -- Coordinates for the data to be interpolated to along the width dimension. If not specified during initialization, this must be specified during the object call.

  • y_out (Optional[Tensor]) -- Coordinates for the data to be interpolated to along the height dimension. If not specified during initialization, this must be specified during the object call.

bivariate_spline_fit_natural(Z)
bspline_basis_natural(x, k, t)

Compute bspline basis function using de Boor's recursive formula (See https://en.wikipedia.org/wiki/De_Boor%27s_algorithm for reference) :type x: Tensor :param x: Tensor of data point positions. :type k: int :param k: Degree of the spline. :type t: Tensor :param t: Tensor of knot positions.

Return type:

Tensor

Returns:

Tensor containing the kth-order B-spline basis functions

Parameters:

  • x (Tensor)

  • k (int)

  • t (Tensor)

compute_L_R(x, t, d, m)

Compute the L and R values for B-spline basis functions. L and R are respectively the first and second coefficient multiplying B_{i,p-1}(x) and B_{i+1,p-1}(x) in De Boor's recursive formula for Bspline basis funciton computation See https://en.wikipedia.org/wiki/De_Boor%27s_algorithm for details

Parameters:

  • x (Tensor) -- Tensor of data point positions.

  • t (Tensor) -- Tensor of knot positions.

  • d (int) -- Current degree of the basis function.

  • m (int) -- Number of intervals (n - k - 1, where n is the number of knots and k is the degree).

Returns:

Tensor containing left values for the B-spline basis functions. R: Tensor containing right values for the B-spline basis functions.

Return type:

L

evaluate_bivariate_spline(C)

Evaluate a bivariate spline on a grid of x and y points.

Parameters:

C (Tensor) -- Coefficient tensor of shape (batch_size, mx, my).

Returns:

Interpolated values at the grid points.

Return type:

Z_interp

forward(Z, x_out=None, y_out=None)

Compute the interpolated data

Parameters:

  • Z (Tensor) -- Tensor of data to be interpolated. Must be between 1 and 4 dimensions. The shape of the tensor must agree with the input coordinates given on initialization. If y_in was not specified during initialization, it is assumed that Z does not have a height dimension.

  • x_out (Optional[Tensor]) -- Coordinates to interpolate the data to along the width dimension. Overrides any value that was set during initialization.

  • y_out (Optional[Tensor]) -- Coordinates to interpolate the data to along the height dimension. Overrides any value that was set during initialization.

Return type:

Tensor

Returns:

A 4D tensor with shape (batch, channel, height, width). Depending on the input data shape, many of these dimensions may have length 1.

generate_natural_knots(x, k)

Generates a natural knot sequence for B-spline interpolation. Natural knot sequence means that 2*k knots are added to the beginning and end of datapoints as replicas of first and last datapoint respectively in order to enforce natural boundary conditions, i.e. second derivative = 0. The other n nodes are placed in correspondece of the data points.

Parameters:

  • x (Tensor) -- Tensor of data point positions.

  • k (int) -- Degree of the spline.

Return type:

Tensor

Returns:

Tensor of knot positions.

zeroth_order(x, k, t, n, m)

Compute the zeroth-order B-spline basis functions according to de Boors recursive formula. See https://en.wikipedia.org/wiki/De_Boor%27s_algorithm for reference

Parameters:

  • x (Tensor) -- Tensor of data point positions.

  • k (int) -- Degree of the spline.

  • t (Tensor) -- Tensor of knot positions.

  • n (int) -- Number of data points.

  • m (int) -- Number of intervals (n - k - 1, where n is the number of knots and k is the degree).

Returns:

Tensor containing the zeroth-order B-spline basis functions.

Return type:

b