Spline

class sofia_redux.toolkit.splines.spline.Spline(*args, weights=None, limits=None, degrees=3, smoothing=None, knots=None, knot_estimate=None, eps=1e-08, fix_knots=None, tolerance=0.001, max_iteration=20, exact=False, reduce_degrees=False, solve=True)

Bases: object

Initialize a Spline object.

This is a Python implementation of the Fortran fitpack spline based routines (Diercchx 1993) but is not limited to a maximum of 2-dimensions. Fast numerical processing is achieved using the numba Python package (Lam et. al., 2015).

The actual spline fitting (representation) is performed during initialization from user supplied data values and coordinates and other parameters (see below). Spline evaluations at other coordinates may then be retrieved using the __call__() method.

Spline coefficients and knots are derived iteratively, and will be deemed acceptable once:

abs(sum(residuals^2) - smoothing) <= tolerance * smoothing

However, iterations may cease in a variety of scenarios. Exit conditions should be examined prior to evaluating the spline and can be retrieved from the exit_code attribute or exit_message property.

Parameters:

argsn-tuple (numpy.ndarray) or numpy.ndarray

The input arguments of the form (c1, …, cn, d) or d where c signifies data coordinates and d are the data values. If a single data array is passed in, the coordinates are derived from the data dimensions. For example if d is an array of shape (a, b, c), c1 will range from 0 -> a - 1 etc. If coordinates are specified, the coordinates for each dimension and the data array should be one-dimensional.

weightsnumpy.ndarray, optional

Optional weights to supply to the spline fit for each data point. Should be the same shape as the supplied data values.

limitsnumpy.ndarray (float), optional

An array of shape (n_dimensions, 2) that may be supplied to set the minimum and maximum coordinate values used during the spline fit. For example, limits[1, 0] sets the minimum knot value in the second dimensions and limits[1, 1] sets the maximum knot value in the second dimension. By default this is set to the minimum and maximum values of the coordinates in each dimension.

degreesint or numpy.ndarray (int), optional

The degree of spline to fit in each dimension. Either a scalar can be supplied pertaining to all dimensions, or an array of shape (n_dimensions,) can be used.

smoothingfloat, optional

Used to specify the smoothing factor. If set to None, the smoothing will be determined based on user settings or input data. If exact is True, smoothing will be disabled (zero). If exact is False, smoothing will be set to n - sqrt(2 * n) where n is the number of data values. If supplied, smoothing must be greater than zero. See above for further details. Note that if smoothing is zero, and the degrees are not equal over each dimension, smoothing will be set to eps due to numerical instabilities.

knotslist or tuple or numpy.ndarray, optional

A set of starting knot coordinates for each dimension. If a list or tuple is supplied it should be of length n_dimensions where element i is an array of shape (n_knots[i]) for dimension i. If an array is supplied, it should be of shape (n_dimension, max(n_knots)). Note that there must be at least 2 * (degree + 1) knots for each dimension. Unused or invalid knots may be set to NaN, at the end of each array. Knot coordinates must also be monotonically increasing in each dimension.

knot_estimatenumpy.ndarray (int), optional

The maximum number of knots required for the spline fit in each dimension and of shape (n_dimensions,). If not supplied, the knot estimate will be set to int((n / n_dimensions) ** n_dimensions^(-1)) or n_knots if knots were supplied and fixed.

epsfloat, optional

A value where 0 < eps < 1. This defines the magnitude used to identify singular values in the spline observation matrix (A). If any row of A[:, 0] < (eps * max(A[:,0])) it will be considered singular.

fix_knotsbool, optional

If True, do not attempt to modify or add knots to the spline fit. Only the initial supplied user knots will be used.

tolerancefloat, optional

A value in the range 0 < tolerance < 1 used to determine the exit criteria for the spline fit. See above for further details.

max_iterationint, optional

The maximum number of iterations to perform when solving for the spline fit.

exactbool, optional

If True, the initial knots used will coincide with the actual input coordinates and smoothing will be set to zero. No knots should be supplied by the user in this instance.

reduce_degreesbool, optional

Only relevant if exact is True. If set to True, the maximum allowable degree in each dimension will be limited to (len(unique(x)) // 2) - 1 where x are the coordinate values in any dimension.

solvebool, optional

If True, solve for the knots and spline coefficients. Otherwise, leave for later processing.

References

Dierckx, P. Curve and Surface Fitting with Splines (Oxford Univ. Press,

1993).

Lam, S. K., Pitrou, A., & Seibert, S. (2015). Numba: A llvm-based

python jit compiler. In Proceedings of the Second Workshop on the LLVM Compiler Infrastructure in HPC (pp. 1–6).

Attributes Summary

exit_message	Returns an exit message for the spline fit.
knot_size	Return the number of knots in each dimension.
size	Return the number of values used for the spline fit.

Methods Summary

__call__(*args)	Evaluate the spline at given coordinates.
check_array_inputs()	Remove zero weights and invalid data points.
create_mapping_indices()	Mapping indices allow 1-D representation of N-D data.
determine_smoothing_spline([smoothing])	Smooth the interpolating spline to the required level.
final_reorder()	Re-order the dimensions of various arrays to match those of the inputs.
fit_knots()	Derive fits at the current knot locations.
initialize_iteration()	Initialize the iteration for the number of current panels.
iterate()	Iteratively determine the spline fit.
knot_indices_to_panel_indices(knot_indices)	Convert knot indices to flat panel indices.
next_iteration()	Perform a single iteration of the spline fit.
order_points()	Sort the data points according to which panel they belong to.
panel_indices_to_knot_indices(panel_indices)	Convert panel indices to dimensional knot indices.
parse_inputs(*args[, weights, limits, ...])	Parse and apply user inputs to the spline fit.
reorder_dimensions(order)	Re-order the dimensions in various attributes.

Attributes Documentation

exit_message

Returns an exit message for the spline fit. Error codes in the range -2 -> 0 generally indicate a successful fit.

Returns:

messagestr

knot_size

Return the number of knots in each dimension.

Returns:

n_knotsnumpy.ndarray (int)

An array of shape (n_dimensions,).

size

Return the number of values used for the spline fit.

Returns:

nint

Methods Documentation

__call__(*args)

Evaluate the spline at given coordinates.

Parameters:

argstuple (numpy.ndarray) or numpy.ndarray (float)

The coordinate arguments. If supplied as a tuple, should be of length n_dimensions where each element of the tuple defines grid coordinates along the (x, y, z,…) dimensions. Arbitrary coordinates may be supplied as an array of shape (n_dimensions, n) where n is the number of coordinates. A singular coordinate may also be supplied as an array of shape (n_dimensions,).

Returns:

fitfloat or numpy.ndarray (float)

An (x[n], x[n-1], …, x[0]) shaped array of values if args was provided in tuple form, or an array of shape (n,) if a 2-dimensional array of arbitrary coordinates were provided. If a single coordinate was provided, the resulting output will be a float.

check_array_inputs()

Remove zero weights and invalid data points.

Invalid data points are those that contain NaN values, weights, or coordinates, or zero weights.

Returns:

None

create_mapping_indices()

Mapping indices allow 1-D representation of N-D data.

Returns:

None

determine_smoothing_spline(smoothing=None)

Smooth the interpolating spline to the required level.

Parameters:

smoothingfloat, optional

Used to specify the an alternate smoothing factor. Note that this should be very close to the original smoothing factor in order to succeed.

Returns:

None

final_reorder()

Re-order the dimensions of various arrays to match those of the inputs.

The dimensions of the various data structures may have changed during the course of processing to reduce the bandwidth of the observation matrix. This step correctly reorders all dimensions such that they match those initially provided by the user.

Returns:

None

fit_knots()

Derive fits at the current knot locations.

In addition to finding the value of the function at each knot, the knot weights and weight normalized coordinates are also determined. These a subsequently used to decide where a new knot should be placed.

Returns:

None

initialize_iteration()

Initialize the iteration for the number of current panels.

Creates array maps that represents N-dimensional data flattened to a single dimension for fast access and the ability to pass these structures to numba JIT compiled functions.

Returns:

None

iterate()

Iteratively determine the spline fit.

Calculates the splines and coefficients for the provided data. If this cannot be accomplished before reaching the maximum number of iterations, a smoothing spline will be calculated instead.

Returns:

None

knot_indices_to_panel_indices(knot_indices)

Convert knot indices to flat panel indices.

Parameters:

knot_indicesnumpy.ndarray (int)

An array of shape (n_dimensions, n_knots).

Returns:

panel_indicesnumpy.ndarray (int)

The flat 1-D panel indices for the knots.

next_iteration()

Perform a single iteration of the spline fit.

During each iteration, the observation matrix is built and solved. An exit code will be generated in cases where no further modifications to the solution are appropriate. Additional knots will also be added if required and possible.

Returns:

continue_iterationsbool

If False no further iterations should occur due to an acceptable solution being reached or due to a given limitation. If True, subsequent iterations are deemed appropriate.

order_points()

Sort the data points according to which panel they belong to.

This is based on the fporde Fortran fitpack routine.

Returns:

None

panel_indices_to_knot_indices(panel_indices)

Convert panel indices to dimensional knot indices.

Parameters:

panel_indicesnumpy.ndarray (int)

An array of shape (n_knots,).

Returns:

panel_indicesnumpy.ndarray (int)

knot.

parse_inputs(*args, weights=None, limits=None, degrees=3, smoothing=None, knots=None, fix_knots=None, knot_estimate=None, exact=False, reduce_degrees=False, eps=1e-08, tolerance=0.001, max_iteration=20)

Parse and apply user inputs to the spline fit.

Parameters:

argsn-tuple (numpy.ndarray) or numpy.ndarray

The input arguments of the form (c1, …, cn, d) or d where c signifies data coordinates and d are the data values. If a single data array is passed in, the coordinates are derived from the data dimensions. For example if d is an array of shape (a, b, c), c1 will range from 0 -> a - 1 etc. If coordinates are specified, the coordinates for each dimension and the data array should be one-dimensional.

weightsnumpy.ndarray, optional

Optional weights to supply to the spline fit for each data point. Should be the same shape as the supplied data values.

limitsnumpy.ndarray (float), optional

An array of shape (n_dimensions, 2) that may be supplied to set the minimum and maximum coordinate values used during the spline fit. For example, limits[1, 0] sets the minimum knot value in the second dimensions and limits[1, 1] sets the maximum knot value in the second dimension. By default this is set to the minimum and maximum values of the coordinates in each dimension.

degreesint or numpy.ndarray (int), optional

The degree of spline to fit in each dimension. Either a scalar can be supplied pertaining to all dimensions, or an array of shape (n_dimensions,) can be used.

smoothingfloat, optional

Used to specify the smoothing factor. If set to None, the smoothing will be determined based on user settings or input data. If exact is True, smoothing will be disabled (zero). If exact is False, smoothing will be set to n - sqrt(2 * n) where n is the number of data values. If supplied, smoothing must be greater than zero. See __init__() for further details. Note that if smoothing is zero, and the degrees are not equal over each dimension, smoothing will be set to eps due to numerical instabilities.

knotslist or tuple or numpy.ndarray, optional

A set of starting knot coordinates for each dimension. If a list or tuple is supplied it should be of length n_dimensions where element i is an array of shape (n_knots[i]) for dimension i. If an array is supplied, it should be of shape (n_dimension, max(n_knots)). Note that there must be at least 2 * (degree + 1) knots for each dimension. Unused or invalid knots may be set to NaN, at the end of each array. Knot coordinates must also be monotonically increasing in each dimension.

fix_knotsbool, optional

If True, do not attempt to modify or add knots to the spline fit. Only the initial supplied user knots will be used.

knot_estimatenumpy.ndarray (int), optional

The maximum number of knots required for the spline fit in each dimension and of shape (n_dimensions,). If not supplied, the knot estimate will be set to int((n / n_dimensions) ** n_dimensions^(-1)) or n_knots if knots were supplied and fixed.

exactbool, optional

If True, the initial knots used will coincide with the actual input coordinates and smoothing will be set to zero. No knots should be supplied by the user in this instance.

reduce_degreesbool, optional

Only relevant if exact is True. If set to True, the maximum allowable degree in each dimension will be limited to (len(unique(x)) // 2) - 1 where x are the coordinate values in any dimension.

epsfloat, optional

A value where 0 < eps < 1. This defines the magnitude used to identify singular values in the spline observation matrix (A). If any row of A[:, 0] < (eps * max(A[:,0])) it will be considered singular.

tolerancefloat, optional

A value in the range 0 < tolerance < 1 used to determine the exit criteria for the spline fit. See __init__() further details.

max_iterationint, optional

The maximum number of iterations to perform when solving for the spline fit.

Returns:

None

reorder_dimensions(order)

Re-order the dimensions in various attributes.

Occasionally it is beneficial to re-order the dimensions of the data structures such that a minimal bandwidth for the observation matrix is achievable. This reduces the amount of processing time required to reach a solution.

Parameters:

ordernumpy.ndarray (int)

An array of shape (n_dimensions,) indicating the new order of the dimensions. E.g., to re-order dimensions [1, 2, 3] to [3, 1, 2], order should be [1, 2, 0].

Returns:

None