scijit.interpolate.splprep

scijit.interpolate.splprep(x, w=None, u=None, ub=None, ue=None, k=3, task=0, s=None, t=None, full_output=0, nest=None, per=0, quiet=1, idim=-1, c_list=1)

Compute the B-spline representation of an N-D parametric curve.

Parameters:
xsequence of 1-D array_like, or (idim, m) array_like, or 1-D array_like

The curve’s sample points. Three spellings, all measured on numba 0.66: a tuple or list of idim arrays of length m; an (idim, m) array; or a FLAT INTERLEAVED array of length idim*m, in which case idim must be given. A bare 1-D array without idim raises.

w1-D array_like of float, optional

Positive weights, one per POINT, length m. None (the default) means unit weights. Unlike splrep, supplying w does not change the default s.

u1-D array_like of float, optional

Parameter values for the data points, strictly increasing, length m. None (the default) has FITPACK compute the cumulative chord length normalised to [ub, ue]. When given it is returned unchanged, and any range is accepted.

ub, uefloat, optional

Bounds on the parameter. INERT unless u is given, in which case None means u[0] and u[-1].

kint, optional

Spline degree, 1 <= k <= 5. Default 3.

taskint, optional

0 (default) finds the smoothing curve. -1 finds the weighted least-squares curve on the knots given in t, which must then be the FULL knot vector with at least 2*k+2 entries. 1 is not supported; see Deviations.

sfloat, optional

Smoothing factor: the fit satisfies sum(w[i]*dist(x[i], s(u[i])))**2 <= s. None (the default) means m - sqrt(2*m) whether or not w is given. s = 0 gives the interpolating curve.

t1-D array_like of float, optional

The FULL knot vector for task=-1, boundary repetitions included. This differs from splrep, whose t is the INTERIOR knots and implies task=-1; here t alone does nothing and task must be set to -1.

full_outputint, optional

Non-zero returns the 4-tuple described below. Must be a compile-time constant inside @njit, since it selects the return type.

nestint, optional

Over-estimate of the knot count. None (the default) resolves through the rule m + 2*k, replaced by m + k + 1 (or m + 2*k when per) whenever task >= 0 and s == 0, then floored at 2*k + 3. It is INERT on an interpolating fit and BINDS on a smoothing one, where too small a value returns ier = 1 with fewer knots. A float raises TypeError wherever the value is used.

perint, optional

Non-zero fits a closed curve through clocur. The last point is set equal to the first, on this function’s own copy rather than on the caller’s array.

quietbool, optional

Zero also warns on a SUCCESSFUL fit, reporting k, the knot count, m, fp and s, and warns once per dimension that per closes. Default 1, which suppresses both. The ier in {1, 2, 3} warning is issued either way.

idimint, optional

Number of coordinates per point, needed only for the flat interleaved x. -1, the default, means “read it from x”. See Notes.

c_listint, optional

Selects the layout of tck[1]. 1, the default, gives a list of idim arrays of length n-k-1. 0 gives FITPACK’s one flat stride-len(t) array instead. Must be a compile-time constant inside @njit, since it selects the return type. See Notes.

Returns:
tcktuple of (t, c, k)

t is the knot vector in the parameter and k the degree. With c_list=1, the default, c is a list of idim arrays of length n-k-1, one per curve dimension. With c_list=0, c is one flat array in FITPACK’s STRIDE-len(t) curve layout: dimension j occupies c[j*n : j*n + n-k-1], where n = len(t). splev, splder_ev, splint, sproot, spalde and scijit.interpolate.evaluators.curev read either layout.

u1-D float64 ndarray, length m

The parameter values: FITPACK’s when u was not given, and the supplied array when it was.

fpfloat

Weighted sum of squared residuals. Returned only when full_output is non-zero.

ierint

FITPACK status: -1 interpolating curve, -2 least-squares polynomial, 0 smoothing achieved, 1/2/3 failure, 10 invalid input. Returned only when full_output is non-zero. It is the value FITPACK set, including on the failure paths that raise when full_output is zero.

msgstr

The exit message for the FITPACK status code ier. Returned only when full_output is non-zero.

Raises:
TypeError

idim outside 1..10, k outside 1..5, task outside -1..1, task == 1, task == -1 without t or with fewer than 2*k+2 knots, m <= k, a length mismatch between x, w and u, or a FITPACK failure with ier outside {1, 2, 3, 10}.

ValueError

ier == 10, FITPACK’s invalid-input code, when full_output is zero – a non-increasing u, a negative weight, duplicate consecutive points. Also raised for an x that is neither a sequence of arrays, an (idim, m) array, nor a flat array with idim given, and for a ragged sequence.

Warns:
RuntimeWarning

ier in {1, 2, 3} with full_output=0: the fit is returned and the matching _iermess text is warned. The warning is issued through a numba.objmode block, which runs its body in the interpreter, so warnings.catch_warnings and -W see it from compiled and uncompiled callers alike.

See also

scipy.interpolate.splprep

The scipy routine this mirrors.

Notes

  • full_output and c_list must both be compile-time constants inside @njit: each selects part of the return type, and numba compiles one return type per specialization. A bool, an int, a string and the default are read while the call compiles; a float, a container and a runtime variable are not, and raise TypingError naming the argument. From Python every object is read by its truthiness. The two flags are independent, so there are four compiled bodies.

  • tck is a tuple. scipy’s is a list, [t, list(c), k], so tck[1] = ... and tck + [extra] work there and not here.

  • idim and c_list are extra trailing arguments with no scipy counterpart. idim is needed only for the flat interleaved x and accepts a runtime value; c_list selects the coefficient layout. A scipy-shaped call passes neither.

  • task=1 raises. scipy keeps the previous fit in a function-local _parcur_cache, so its own task=1 raises UnboundLocalError on every call, including immediately after a task=0 call. There is no behaviour to reproduce.

A SMOOTHING FIT MAY WARN THAT IT IS RANK DEFICIENT. With a small s on noisy data, FITPACK’s knot search can place knots so that one B-spline coefficient is not determined by the data at all. The curve still passes through the data as asked, and fp reports success, but between the data points it carries an arbitrary component. A UserWarning naming the number of undetermined coefficients is issued when this happens, and a larger s is the fix. scipy issues no warning for it.

prange-safe: yes.

Examples

>>> import numpy as np
>>> from numba import njit
>>> from scijit.interpolate import splprep
>>> t = np.linspace(0, 2 * np.pi, 30)
>>> pts = np.vstack((np.cos(t), np.sin(t)))
>>> @njit
... def fit(pts):
...     (t, c, k), u = splprep(pts, s=0.0)
...     return len(t), len(c), len(c[0]), len(u)
>>> fit(pts)
(34, 2, 30, 30)
>>> @njit
... def fit_flat(pts):
...     (t, c, k), u = splprep(pts, s=0.0, c_list=0)
...     return len(c)
>>> fit_flat(pts)
68