naginterfaces.library.fit.dim2_​spline_​grid

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

dim2_spline_grid computes a bicubic spline approximation to a set of data values, given on a rectangular grid in the $x$-$y$ plane. 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 e02dc

https://support.nag.com/numeric/nl/nagdoc_30/flhtml/e02/e02dcf.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$, $comm$[‘wrk’] or $comm$[‘iwrk’].

$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$, $comm$[‘wrk’] and $comm$[‘iwrk’] 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(\text{mx}\right)$

$x[\text{q}-1]$ must be set to $x_{\text{q}}$, the $x$ coordinate of the $\text{q}$th grid point along the $x$ axis, for $\text{q}=1,2,\dots ,m_x$.

yfloat, array-like, shape $\left(\text{my}\right)$

$y[\text{r}-1]$ must be set to $y_{\text{r}}$, the $y$ coordinate of the $\text{r}$th grid point along the $y$ axis, for $\text{r}=1,2,\dots ,m_y$.

ffloat, array-like, shape $(\text{mx}\times \text{my})$

$f[m_y\times (\text{q}-1)+\text{r}-1]$ must contain the data value $f_{\text{q},\text{r}}$, for $\text{r}=1,2,\dots ,m_y$, for $\text{q}=1,2,\dots ,m_x$.

sfloat

The smoothing factor, $S$.

If $s=0.0$, the function returns an interpolating spline.

If $s$ is smaller than machine precision, it is assumed equal to zero.

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\left[0\right]$$

and

$$lamda[nx-4]=lamda[nx-3]=lamda[nx-2]=lamda[nx-1]=x[\text{mx}-1]$$

needed for the B-spline representation.

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\left[0\right]$$

and

$$mu[ny-4]=mu[ny-3]=mu[ny-2]=mu[ny-1]=y[\text{my}-1]$$

needed for the B-spline representation.

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 sum of squared residuals, $\theta$, of the computed spline approximation. If $fp=0.0$, this is an interpolating spline. $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.

Raises

NagValueError

(errno $1$)

On entry, $\text{nxest}=⟨value⟩$, $\text{mx}=⟨value⟩$, $\text{nyest}=⟨value⟩$ and $\text{my}=⟨value⟩$.

Constraint: if $s=0.0$, $\text{nxest}\ge \text{mx}+4$ and $\text{nyest}\ge \text{my}+4$.

(errno $1$)

On entry, $s=⟨value⟩$.

Constraint: $s\ge 0.0$.

(errno $1$)

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

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

(errno $1$)

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

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

(errno $1$)

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

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

(errno $1$)

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

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

(errno $1$)

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

(errno $2$)

On entry, $q=⟨value⟩$, $x[q-2]=⟨value⟩$ and $x[q-1]=⟨value⟩$.

Constraint: $x[q-2]<x[q-1]$ for all $q$.

(errno $3$)

On entry, $r=⟨value⟩$, $y[r-2]=⟨value⟩$ and $y[r-1]=⟨value⟩$.

Constraint: $y[r-2]<y[r-1]$ for all $r$.

(errno $4$)

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 $5$)

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_grid determines a smooth bicubic spline approximation $s(x,y)$ to the set of data points $(x_{\text{q}},y_{\text{r}},f_{\text{q},\text{r}})$, for $\text{r}=1,2,\dots ,m_y$, for $\text{q}=1,2,\dots ,m_x$.

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_1,x_{m_x}]\times [y_1,y_{m_y}]$ 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_{\text{i}\text{j}}$ are determined as the solution of the following constrained minimization problem:

$$minimize\left(\eta \right)\text{,}$$

subject to the constraint

$$\theta =\sum _{q=1}^{m_x}\sum _{r=1}^{m_y}{ϵ}_{q,r}^2\le S\text{,}$$

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 (1982) for details).
	${ϵ}_{q,r}$	denotes the residual $f_{q,r}-s(x_q,y_r)$,
and	$S$	is a non-negative number 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 function will return an interpolating spline $(\theta =0)$ if $S$ is set to zero, and 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 Choice of s for advice on choice of $S$.)

The method employed is outlined in Further Comments and fully described in Dierckx (1981) and Dierckx (1982). 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 improved algorithm for curve fitting with spline functions, Report TW54, Department of Computer Science, Katholieke Univerciteit Leuven

Dierckx, P, 1982, A fast algorithm for smoothing data on a rectangular grid while using spline functions, SIAM J. Numer. Anal. (19), 1286–1304

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

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