naginterfaces.library.fit.dim2_​spline_​sctr

naginterfaces.library.fit.dim2_spline_sctr(start, x, y, f, w, s, nx, lamda, ny, mu, comm)

dim2_spline_sctr computes a bicubic spline approximation to a set of scattered data. The knots of the spline are located automatically, but a single argument must be specified to control the trade-off between closeness of fit and smoothness of fit.

For full information please refer to the NAG Library document for e02dd

https://support.nag.com/numeric/nl/nagdoc_30/flhtml/e02/e02ddf.html

Parameters

startstr, length 1

Determines whether calculations are to be performed afresh (Cold Start) or whether knots found in previous calls are to be used as an initial estimate of knot placement (Warm Start).

$start=\text{'C'}$

The function will build up the knot set starting with no interior knots. No values need be assigned to the arguments $nx$, $ny$, $lamda$, $mu$ or $comm$[‘wrk’].

$start=\text{'W'}$

The function will restart the knot-placing strategy using the knots found in a previous call of the function. In this case, the arguments $nx$, $ny$, $lamda$, $mu$ and $comm$[‘wrk’] must be unchanged from that previous call. This warm start can save much time in determining a satisfactory set of knots for the given value of $s$. This is particularly useful when different smoothing factors are used for the same dataset.

xfloat, array-like, shape $\left(m\right)$

$x[\text{r}-1]$, $y[\text{r}-1]$, $f[\text{r}-1]$ must be set to the coordinates of $(x_{\text{r}},y_{\text{r}},f_{\text{r}})$, the $\text{r}$th data point, for $\text{r}=1,2,\dots ,m$. The order of the data points is immaterial.

yfloat, array-like, shape $\left(m\right)$

$x[\text{r}-1]$, $y[\text{r}-1]$, $f[\text{r}-1]$ must be set to the coordinates of $(x_{\text{r}},y_{\text{r}},f_{\text{r}})$, the $\text{r}$th data point, for $\text{r}=1,2,\dots ,m$. The order of the data points is immaterial.

ffloat, array-like, shape $\left(m\right)$

$x[\text{r}-1]$, $y[\text{r}-1]$, $f[\text{r}-1]$ must be set to the coordinates of $(x_{\text{r}},y_{\text{r}},f_{\text{r}})$, the $\text{r}$th data point, for $\text{r}=1,2,\dots ,m$. The order of the data points is immaterial.

wfloat, array-like, shape $\left(m\right)$

$w[\text{r}-1]$ must be set to ${\text{w}}_{\text{r}}$, the $\text{r}$th value in the set of weights, for $\text{r}=1,2,\dots ,m$. Zero weights are permitted and the corresponding points are ignored, except when determining $x_{min}$, $x_{max}$, $y_{min}$ and $y_{max}$ (see Further Comments). For advice on the choice of weights, see the E02 Introduction.

sfloat

The smoothing factor, $s$.

For advice on the choice of $s$, see Notes and Further Comments.

nxint

If the warm start option is used, the value of $nx$ must be left unchanged from the previous call.

lamdafloat, array-like, shape $\left(\text{nxest}\right)$

If the warm start option is used, the values $lamda\left[0\right],lamda\left[1\right],\dots ,lamda[nx-1]$ must be left unchanged from the previous call.

nyint

If the warm start option is used, the value of $ny$ must be left unchanged from the previous call.

mufloat, array-like, shape $\left(\text{nyest}\right)$

If the warm start option is used, the values $mu\left[0\right],mu\left[1\right],\dots ,mu[ny-1]$ must be left unchanged from the previous call.

commdict, communication object, modified in place

Communication structure.

On initial entry: need not be set.

Returns

nxint

The total number of knots, $n_x$, of the computed spline with respect to the $x$ variable.

lamdafloat, ndarray, shape $\left(\text{nxest}\right)$

Contains the complete set of knots ${\lambda }_i$ associated with the $x$ variable, i.e., the interior knots $lamda\left[4\right],lamda\left[5\right],\dots ,lamda[nx-5]$ as well as the additional knots

$$lamda\left[0\right]=lamda\left[1\right]=lamda\left[2\right]=lamda\left[3\right]=x_{min}$$

and

$$lamda[nx-4]=lamda[nx-3]=lamda[nx-2]=lamda[nx-1]=x_{max}$$

needed for the B-spline representation (where $x_{min}$ and $x_{max}$ are as described in Notes).

nyint

The total number of knots, $n_y$, of the computed spline with respect to the $y$ variable.

mufloat, ndarray, shape $\left(\text{nyest}\right)$

Contains the complete set of knots ${\mu }_i$ associated with the $y$ variable, i.e., the interior knots $mu\left[4\right],mu\left[5\right],\dots ,mu[ny-5]$ as well as the additional knots

$$mu\left[0\right]=mu\left[1\right]=mu\left[2\right]=mu\left[3\right]=y_{min}$$

and

$$mu[ny-4]=mu[ny-3]=mu[ny-2]=mu[ny-1]=y_{max}$$

needed for the B-spline representation (where $y_{min}$ and $y_{max}$ are as described in Notes).

cfloat, ndarray, shape $((\text{nxest}-4)\times (\text{nyest}-4))$

The coefficients of the spline approximation. $c[(n_y-4)\times (i-1)+j-1]$ is the coefficient $c_{ij}$ defined in Notes.

fpfloat

The weighted sum of squared residuals, $\theta$, of the computed spline approximation. $fp$ should equal $s$ within a relative tolerance of $0.001$ unless $nx=ny=8$, when the spline has no interior knots and so is simply a bicubic polynomial. For knots to be inserted, $s$ must be set to a value below the value of $fp$ produced in this case.

rankint

Gives the rank of the system of equations used to compute the final spline (as determined by a suitable machine-dependent threshold). When $rank=(nx-4)\times (ny-4)$, the solution is unique; otherwise the system is rank-deficient and the minimum-norm solution is computed. The latter case may be caused by too small a value of $s$.

Raises

NagValueError

(errno $1$)

On entry, $\text{nyest}=⟨value⟩$.

Constraint: $\text{nyest}\ge ⟨value⟩$.

(errno $1$)

On entry, $\text{nxest}=⟨value⟩$.

Constraint: $\text{nxest}\ge ⟨value⟩$.

(errno $1$)

On entry, $start\ne \text{'W'}$ or $\text{'C'}$: $start=⟨value⟩$.

(errno $1$)

On entry, $s=⟨value⟩$.

Constraint: $s>0.0$.

(errno $1$)

On entry, $MM<16$, where $MM$ is the number of points with nonzero weight: $MM=⟨value⟩$.

(errno $2$)

On entry, all the values in array $y$ are equal.

(errno $2$)

On entry, all the values in array $x$ are equal.

(errno $3$)

The number of knots needed in one direction is greater than $\text{nxest}$ or $\text{nyest}$: $\text{nxest}$, $\text{nyest}=⟨value⟩,⟨value⟩$. Possibly $s$ is too small: $s=⟨value⟩$.

(errno $4$)

No more knots added; the number of $B$-spline coefficients already exceeds $\text{m}$. Either $\text{m}$ or $s$ is probably too small: $m=⟨value⟩$ and $s=⟨value⟩$.

(errno $5$)

No more knots added; the additional knot would coincide with an old one. Possibly an inaccurate data point has too large a weight, or $s$ is too small: $s=⟨value⟩$.

(errno $6$)

The iterative process has failed to converge. Possibly $s$ is too small: $s=⟨value⟩$.

Notes

In the NAG Library the traditional C interface for this routine uses a different algorithmic base. Please contact NAG if you have any questions about compatibility.

dim2_spline_sctr determines a smooth bicubic spline approximation $s(x,y)$ to the set of data points $(x_{\text{r}},y_{\text{r}},f_{\text{r}})$ with weights ${\text{w}}_{\text{r}}$, for $\text{r}=1,2,\dots ,m$.

The approximation domain is considered to be the rectangle $[x_{min},x_{max}]\times [y_{min},y_{max}]$, where $x_{min}\left(y_{min}\right)$ and $x_{max}\left(y_{max}\right)$ denote the lowest and highest data values of $x\left(y\right)$.

The spline is given in the B-spline representation

$$s(x,y)=\sum _{i=1}^{n_x-4}\sum _{j=1}^{n_y-4}{c}_{ij}{M}_i\left(x\right)N_j\left(y\right)\text{,}$$

where $M_i\left(x\right)$ and $N_j\left(y\right)$ denote normalized cubic B-splines, the former defined on the knots ${\lambda }_i$ to ${\lambda }_{i+4}$ and the latter on the knots ${\mu }_j$ to ${\mu }_{j+4}$. For further details, see Hayes and Halliday (1974) for bicubic splines and de Boor (1972) for normalized B-splines.

The total numbers $n_x$ and $n_y$ of these knots and their values ${\lambda }_1,\dots ,{\lambda }_{n_x}$ and ${\mu }_1,\dots ,{\mu }_{n_y}$ are chosen automatically by the function. The knots ${\lambda }_5,\dots ,{\lambda }_{n_x-4}$ and ${\mu }_5,\dots ,{\mu }_{n_y-4}$ are the interior knots; they divide the approximation domain $[x_{min},x_{max}]\times [y_{min},y_{max}]$ into $(n_x-7)\times (n_y-7)$ subpanels $[{\lambda }_{\text{i}},{\lambda }_{\text{i}+1}]\times [{\mu }_{\text{j}},{\mu }_{\text{j}+1}]$, for $\text{j}=4,5,\dots ,n_y-4$, for $\text{i}=4,5,\dots ,n_x-4$. Then, much as in the curve case (see dim1_spline_auto()), the coefficients $c_{ij}$ are determined as the solution of the following constrained minimization problem:

minimize

$$\eta \text{,}$$

subject to the constraint

$$\theta =\sum _{r=1}^m{ϵ}_r^2\le S$$

where	$\eta$	is a measure of the (lack of) smoothness of $s(x,y)$. Its value depends on the discontinuity jumps in $s(x,y)$ across the boundaries of the subpanels. It is zero only when there are no discontinuities and is positive otherwise, increasing with the size of the jumps (see Dierckx (1981b) for details).
	${ϵ}_r$	denotes the weighted residual ${\text{w}}_r(f_r-s(x_r,y_r))$,
and	$s$	is a non-negative number to be specified by you.

By means of the argument $s$, ‘the smoothing factor’, you will then control the balance between smoothness and closeness of fit, as measured by the sum of squares of residuals in (3). If $s$ is too large, the spline will be too smooth and signal will be lost (underfit); if $s$ is too small, the spline will pick up too much noise (overfit). In the extreme cases the method would return an interpolating spline $(\theta =0)$ if $s$ were set to zero, and returns the least squares bicubic polynomial $(\eta =0)$ if $s$ is set very large. Experimenting with $s$-values between these two extremes should result in a good compromise. (See Further Comments for advice on choice of $s$.) Note however, that this function, unlike dim1_spline_auto() and dim2_spline_grid(), does not allow $s$ to be set exactly to zero: to compute an interpolant to scattered data, interp.dim2_scat or interp.dim2_scat_shep should be used.

The method employed is outlined in Further Comments and fully described in Dierckx (1981a) and Dierckx (1981b). It involves an adaptive strategy for locating the knots of the bicubic spline (depending on the function underlying the data and on the value of $s$), and an iterative method for solving the constrained minimization problem once the knots have been determined.

Values and derivatives of the computed spline can subsequently be computed by calling dim2_spline_evalv(), dim2_spline_evalm() or dim2_spline_derivm() as described in Further Comments.

References

de Boor, C, 1972, On calculating with B-splines, J. Approx. Theory (6), 50–62

Dierckx, P, 1981, An algorithm for surface fitting with spline functions, IMA J. Numer. Anal. (1), 267–283

Dierckx, P, 1981, An improved algorithm for curve fitting with spline functions, Report TW54, Department of Computer Science, Katholieke Univerciteit Leuven

Hayes, J G and Halliday, J, 1974, The least squares fitting of cubic spline surfaces to general data sets, J. Inst. Math. Appl. (14), 89–103

Peters, G and Wilkinson, J H, 1970, The least squares problem and pseudo-inverses, Comput. J. (13), 309–316

Reinsch, C H, 1967, Smoothing by spline functions, Numer. Math. (10), 177–183