NAG Library Function Document

nag_2d_spline_fit_scat (e02ddc)

1  Purpose

2  Specification

3  Description

4  References

5  Arguments

1:     start – Nag_StartInput

On entry: start must be set to $\mathbf{start}=\mathrm{Nag\_Cold}$ or $\mathrm{Nag\_Warm}$.

$\mathbf{start}=\mathrm{Nag\_Cold}$ (cold start)

The function will build up the knot set starting with no interior knots. No values need be assigned to $\mathbf{spline}\mathbf{\to }\mathbf{nx}$ and $\mathbf{spline}\mathbf{\to }\mathbf{ny}$ and memory will be internally allocated to $\mathbf{spline}\mathbf{\to }\mathbf{lamda}$, $\mathbf{spline}\mathbf{\to }\mathbf{mu}$ and $\mathbf{spline}\mathbf{\to }\mathbf{c}$.

$\mathbf{start}=\mathrm{Nag\_Warm}$ (warm start)

The function will restart the knot-placing strategy using the knots found in a previous call of the function. In this case, all arguments except s must be unchanged from that previous call. This warm start can save much time in searching for a satisfactory value of $S$.

Constraint: $\mathbf{start}=\mathrm{Nag\_Cold}$ or $\mathrm{Nag\_Warm}$.

2:     m – IntegerInput

On entry: $m$, the number of data points.

The number of data points with nonzero weight (see weights) must be at least 16.

3:     x[m] – const doubleInput

4:     y[m] – const doubleInput

5:     f[m] – const doubleInput

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

6:     weights[m] – const doubleInput

On entry: $\mathbf{weights}\left[\mathit{r}-1\right]$ must be set to $w_{\mathit{r}}$, the $\mathit{r}$th value in the set of weights, for $\mathit{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 Section 9.4). For advice on the choice of weights, see the e02 Chapter Introduction.

Constraint: the number of data points with nonzero weight must be at least 16.

7:     s – doubleInput

On entry: the smoothing factor, $S$. For advice on the choice of $S$, see Section 3 and Section 9.2.

Constraint: $\mathbf{s}>0.0$.

8:     nxest – IntegerInput

9:     nyest – IntegerInput

On entry: an upper bound for the number of knots $n_x$ and $n_y$ required in the $x$ and $y$ directions respectively. In most practical situations, $\mathbf{nxest}=\mathbf{nyest}=5+\sqrt{m}$ is sufficient. See also Section 9.3.

Constraint: $\mathbf{nxest}\ge 8$ and $\mathbf{nyest}\ge 8$.

10:   fp – double *Output

On exit: the weighted sum of squared residuals, $\theta$, of the computed spline approximation. fp should equal $S$ within a relative tolerance of 0.001 unless $\mathbf{spline}\mathbf{\to }\mathbf{nx}=\mathbf{spline}\mathbf{\to }\mathbf{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.

11:   rank – Integer *Output

On exit: rank gives the rank of the system of equations used to compute the final spline (as determined by a suitable machine-dependent threshold). When $\mathbf{rank}=\left(\mathbf{spline}\mathbf{\to }\mathbf{nx}-4\right)\times \left(\mathbf{spline}\mathbf{\to }\mathbf{ny}-4\right)$, 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$.

12:   warmstartinf – double *Output

On exit: if the warm start option is used, its value must be left unchanged from the previous call.

13:   spline – Nag_2dSpline *

Pointer to structure of type Nag_2dSpline with the following members:

nx – IntegerInput/Output

On entry: if the warm start option is used, the value of $\mathbf{nx}$ must be left unchanged from the previous call.

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

lamda – double *Input/Output

On entry: a pointer to which if $\mathbf{start}=\mathrm{Nag\_Cold}$, memory of size nxest is internally allocated. If the warm start option is used, the values $\mathbf{lamda}\left[0\right],\mathbf{lamda}\left[1\right],\dots ,\mathbf{lamda}\left[\mathbf{nx}-1\right]$ must be left unchanged from the previous call.

On exit: $\mathbf{lamda}$ contains the complete set of knots ${\lambda }_i$ associated with the $x$ variable, i.e., the interior knots $\mathbf{lamda}\left[4\right],\mathbf{lamda}\left[5\right],\dots ,\mathbf{lamda}\left[\mathbf{nx}-5\right]$ as well as the additional knots $\mathbf{lamda}\left[0\right]=\mathbf{lamda}\left[1\right]=\mathbf{lamda}\left[2\right]=\mathbf{lamda}\left[3\right]=x_{\min }$ and $\mathbf{lamda}\left[\mathbf{nx}-4\right]=\mathbf{lamda}\left[\mathbf{nx}-3\right]=\mathbf{lamda}\left[\mathbf{nx}-2\right]=\mathbf{lamda}\left[\mathbf{nx}-1\right]=x_{\max }$ needed for the B-spline representation (where $x_{\min }$ and $x_{\max }$ are as described in Section 3).

ny – IntegerInput/Output

On entry: if the warm start option is used, the value of $\mathbf{ny}$ must be left unchanged from the previous call.

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

mu – double *Input/Output

On entry: a pointer to which if $\mathbf{start}=\mathrm{Nag\_Cold}$, memory of size nyest is internally allocated. If the warm start option is used, the values $\mathbf{mu}\left[0\right],\mathbf{mu}\left[1\right],\dots ,\mathbf{mu}\left[\mathbf{ny}-1\right]$ must be left unchanged from the previous call.

On exit: $\mathbf{mu}$ contains the complete set of knots ${\mu }_i$ associated with the $y$ variable, i.e., the interior knots $\mathbf{mu}\left[4\right]$, $\mathbf{mu}\left[5\right]$, $\dots$, $\mathbf{mu}\left[\mathbf{ny}-5\right]$ as well as the additional knots $\mathbf{mu}\left[0\right]=\mathbf{mu}\left[1\right]=\mathbf{mu}\left[2\right]=\mathbf{mu}\left[3\right]=y_{\min }$ and $\mathbf{mu}\left[\mathbf{ny}-4\right]=\mathbf{mu}\left[\mathbf{ny}-3\right]=\mathbf{mu}\left[\mathbf{ny}-2\right]=\mathbf{mu}\left[\mathbf{ny}-1\right]=y_{\max }$ needed for the B-spline representation (where $y_{\min }$ and $y_{\max }$ are as described in Section 3).

c – double *Output

On exit: a pointer to which, if $\mathbf{start}=\mathrm{Nag\_Cold}$, memory of size $\left(\mathbf{nxest}-4\right)\times \left(\mathbf{nyest}-4\right)$ is internally allocated. $\mathbf{c}\left[\left(n_y-4\right)\times \left(i-1\right)+j-1\right]$ is the coefficient $c_{ij}$ defined in Section 3.

Note that when the information contained in the pointers $\mathbf{lamda}$, $\mathbf{mu}$ and $\mathbf{c}$ is no longer of use, or before a new call to nag_2d_spline_fit_scat (e02ddc) with the same spline, you should free this storage using the NAG macro NAG_FREE. This storage will have been allocated only if this function returns with $\mathbf{fail}\mathbf{.}\mathbf{code}=\mathrm{NE\_NOERROR}$, NE_NUM_KNOTS_2D_GT_SCAT, NE_NUM_COEFF_GT, NE_NO_ADDITIONAL_KNOTS, NE_SPLINE_COEFF_CONV or, possibly, NE_ALLOC_FAIL.

14:   fail – NagError *Input/Output

The NAG error argument (see Section 3.6 in the Essential Introduction).

6  Error Indicators and Warnings

If the function fails with an error exit of NE_NUM_KNOTS_2D_GT_SCAT, NE_NUM_COEFF_GT, NE_NO_ADDITIONAL_KNOTS or NE_SPLINE_COEFF_CONV, then a spline approximation is returned, but it fails to satisfy the fitting criterion (see (2) and (3)) – perhaps by only a small amount, however.

NE_ALL_ELEMENTS_EQUAL

On entry, all the values in the array x must not be equal.

On entry, all the values in the array y must not be equal.

NE_ALLOC_FAIL

Dynamic memory allocation failed.

NE_BAD_PARAM

On entry, argument start had an illegal value.

NE_ENUMTYPE_WARM

$\mathbf{start}=\mathrm{Nag\_Warm}$ at the first call of this function. start must be set to $\mathbf{start}=\mathrm{Nag\_Cold}$ at the first call.

NE_INT_ARG_LT

On entry, $\mathbf{nxest}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{nxest}\ge 8$.

On entry, $\mathbf{nyest}=⟨\mathit{\text{value}}⟩$.
Constraint: $\mathbf{nyest}\ge 8$.

NE_NO_ADDITIONAL_KNOTS

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. $\mathbf{s}=⟨\mathit{\text{value}}⟩$.

NE_NON_ZERO_WEIGHTS

On entry, the number of data points with nonzero weights $=⟨\mathit{\text{value}}⟩$.
Constraint: the number of nonzero weights $\ge 16$.

NE_NUM_COEFF_GT

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

NE_NUM_KNOTS_2D_GT_SCAT

The number of knots required is greater than allowed by nxest or nyest, $\mathbf{nxest}=⟨\mathit{\text{value}}⟩$, $\mathbf{nyest}=⟨\mathit{\text{value}}⟩$. Possibly s is too small, especially if nxest, $\mathbf{nyest}>5+\sqrt{\mathbf{m}}$. $\mathbf{s}=⟨\mathit{\text{value}}⟩$, $\mathbf{m}=⟨\mathit{\text{value}}⟩$.

NE_REAL_ARG_LE

On entry, s must not be less than or equal to 0.0: $\mathbf{s}=⟨\mathit{\text{value}}⟩$.

NE_SPLINE_COEFF_CONV

The iterative process has failed to converge. Possibly s is too small: $\mathbf{s}=⟨\mathit{\text{value}}⟩$.

7  Accuracy

8  Parallelism and Performance

9  Further Comments

9.1  Timing

9.2  Choice of $S$ 

9.3  Choice of nxest and nyest

9.4  Restriction of the Approximation Domain

9.5  Outline of Method Used

9.6  Evaluation of Computed Spline

e02dec(n, tx, ty, ff, &spline, &fail)

e02dfc(kx, ky, tx, ty, fg, &spline, &fail)

10  Example

10.1  Program Text

Program Text (e02ddce.c)

10.2  Program Data

Program Data (e02ddce.d)

10.3  Program Results

Program Results (e02ddce.r)