NAG Library Function Document

nag_2d_spline_fit_panel (e02dac)

1  Purpose

2  Specification

3  Description

4  References

5  Arguments

1:    $\mathbf{m}$ – IntegerInput

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

Constraint: $\mathbf{m}>1$.

2:    $\mathbf{x}\left[\mathbf{m}\right]$ – const doubleInput

3:    $\mathbf{y}\left[\mathbf{m}\right]$ – const doubleInput

4:    $\mathbf{f}\left[\mathbf{m}\right]$ – const doubleInput

On entry: the coordinates of the data point $\left(x_{\mathit{r}},y_{\mathit{r}},f_{\mathit{r}}\right)$, for $\mathit{r}=1,2,\dots ,m$. The order of the data points is immaterial, but see the array point.

5:    $\mathbf{w}\left[\mathbf{m}\right]$ – const doubleInput

On entry: the weight $w_r$ of the $r$th data point. It is important to note the definition of weight implied by the equation (1) in Section 3, since it is also common usage to define weight as the square of this weight. In this function, each $w_r$ should be chosen inversely proportional to the (absolute) accuracy of the corresponding $f_r$, as expressed, for example, by the standard deviation or probable error of the $f_r$. When the $f_r$ are all of the same accuracy, all the $w_r$ may be set equal to $1.0$.

6:    $\mathbf{point}\left[\mathit{dim}\right]$ – const IntegerInput

Note: the dimension, dim, of the array point must be at least $\left(\mathbf{m}+\left(\mathbf{spline}\mathbf{.}\mathbf{nx}-7\right)\times \left(\mathbf{spline}\mathbf{.}\mathbf{ny}-7\right)\right)$.

On entry: indexing information usually provided by nag_2d_panel_sort (e02zac) which enables the data points to be accessed in the order which produces the advantageous matrix structure mentioned in Section 3. This order is such that, if the $\left(x,y\right)$ plane is thought of as being divided into rectangular panels by the two sets of knots, all data in a panel occur before data in succeeding panels, where the panels are numbered from bottom to top and then left to right with the usual arrangement of axes, as indicated in Figure 1.

Figure 1

A data point lying exactly on one or more panel sides is considered to be in the highest numbered panel adjacent to the point. nag_2d_panel_sort (e02zac) should be called to obtain the array point, unless it is provided by other means.

7:    $\mathbf{dl}\left[\mathit{dim}\right]$ – doubleOutput

Note: the dimension, dim, of the array dl must be at least $\left(\mathbf{spline}\mathbf{.}\mathbf{nx}-4\right)\times \left(\mathbf{spline}\mathbf{.}\mathbf{ny}-4\right)$.

On exit: gives the squares of the diagonal elements of the reduced triangular matrix, divided by the mean squared weight. It includes those elements, less than $\epsilon$, which are treated as zero (see Section 3).

8:    $\mathbf{eps}$ – doubleInput

On entry: a threshold $\epsilon$ for determining the effective rank of the system of linear equations. The rank is determined as the number of elements of the array dl which are nonzero. An element of dl is regarded as zero if it is less than $\epsilon$. Machine precision is a suitable value for $\epsilon$ in most practical applications which have only $2$ or $3$ decimals accurate in data. If some coefficients of the fit prove to be very large compared with the data ordinates, this suggests that $\epsilon$ should be increased so as to decrease the rank. The array dl will give a guide to appropriate values of $\epsilon$ to achieve this, as well as to the choice of $\epsilon$ in other cases where some experimentation may be needed to determine a value which leads to a satisfactory fit.

9:    $\mathbf{sigma}$ – double *Output

On exit: $\Sigma$, the weighted sum of squares of residuals. This is not computed from the individual residuals but from the right-hand sides of the orthogonally-transformed linear equations. For further details see page 97 of Hayes and Halliday (1974). The two methods of computation are theoretically equivalent, but the results may differ because of rounding error.

10:  $\mathbf{rank}$ – Integer *Output

On exit: the rank of the system as determined by the value of the threshold $\epsilon$.

$\mathbf{rank}=\left(\mathbf{spline}\mathbf{.}\mathbf{nx}-4\right)\times \left(\mathbf{spline}\mathbf{.}\mathbf{ny}-4\right)$

The least squares solution is unique.

$\mathbf{rank}\ne \left(\mathbf{spline}\mathbf{.}\mathbf{nx}-4\right)\times \left(\mathbf{spline}\mathbf{.}\mathbf{ny}-4\right)$

The minimal least squares solution is computed.

11:  $\mathbf{spline}$ – Nag_2dSpline *

Pointer to structure of type Nag_2dSpline with the following members:

nx – IntegerInput

On entry: $\mathbf{nx}$ must specify the total number of knots associated with the variables $x$. It is such that $\mathbf{nx}-8$ is the number of interior knots.

Constraint: $\mathbf{nx}\ge 8$.

lamda – doubleInput/Output

On entry: $\mathbf{lamda}\left[i+4\right]$ must contain the $i$th interior knot ${\lambda }_{\mathit{i}+4}$ associated with the variable $x$, for $\mathit{i}=1,2,\dots \mathbf{nx}-8$. The knots must be in nondecreasing order and lie strictly within the range covered by the data values of $x$. A knot is a value of $x$ at which the spline is allowed to be discontinuous in the third derivative with respect to $x$, though continuous up to the second derivative. This degree of continuity can be reduced, if you require, by the use of coincident knots, provided that no more than four knots are chosen to coincide at any point. Two, or three, coincident knots allow loss of continuity in, respectively, the second and first derivative with respect to $x$ at the value of $x$ at which they coincide. Four coincident knots split the spline surface into two independent parts. For choice of knots see Section 9.

On exit: the interior knots $\mathbf{lamda}\left[4\right]$ to $\mathbf{lamda}\left[\mathbf{nx}-5\right]$ are unchanged, and the segments $\mathbf{LAMDA}\left(1:4\right)$ and $\mathbf{LAMDA}\left(\mathbf{nx}-3:\mathbf{nx}\right)$ contain additional (exterior) knots introduced by the function in order to define the full set of B-splines required. The four knots in the first segment are all set equal to the lowest data value of $x$ and the other four additional knots are all set equal to the highest value: there is experimental evidence that coincident end-knots are best for numerical accuracy. The complete array must be left undisturbed if nag_2d_spline_eval (e02dec) or nag_2d_spline_eval_rect (e02dfc) is to be used subsequently.

ny – IntegerInput

On entry: $\mathbf{ny}$ must specify the total number of knots associated with the variable $y$.

It is such that $\mathbf{ny}-8$ is the number of interior knots.

Constraint: $\mathbf{ny}\ge 8$.

mu – doubleInput/Output

On entry: $\mathbf{mu}\left[i+4\right]$ must contain the $i$th interior knot ${\mu }_{i+4}$ associated with the variable $y$, $i=1,2,\dots ,\mathbf{ny}-8$.

On exit: the same remarks apply to $\mathbf{mu}$ as to $\mathbf{lamda}$ above, with y replacing x, and $y$ replacing $x$.

c – doubleOutput

On exit: gives the coefficients of the fit. $\mathbf{c}\left(\left(\mathbf{ny}-4\right)\times \left(i-1\right)+j\right)$ is the coefficient $c_{\mathit{i}\mathit{j}}$ of Sections 3 and 9, for $\mathit{i}=1,2,\dots \mathbf{nx}-4$ and $\mathit{j}=1,2,\dots \mathbf{ny}-4$. These coefficients are used by nag_2d_spline_eval (e02dec) or nag_2d_spline_eval_rect (e02dfc) to calculate values of the fitted function.

In normal usage, the call to nag_2d_spline_fit_panel (e02dac) follows a call to nag_2d_spline_interpolant (e01dac), nag_2d_spline_fit_grid (e02dcc) or nag_2d_spline_fit_scat (e02ddc), in which case, members of the structure spline will have been set up correctly for input to nag_2d_spline_fit_panel (e02dac).

12:  $\mathbf{fail}$ – NagError *Input/Output

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

6  Error Indicators and Warnings

NE_ALLOC_FAIL

Dynamic memory allocation failed.
See Section 3.2.1.2 in the Essential Introduction for further information.

NE_BAD_PARAM

On entry, argument $〈\mathit{\text{value}}〉$ had an illegal value.

NE_CONSTRAINT

On entry, $\mathbf{nx}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{nx}\ge 8$.

On entry, $\mathbf{ny}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{ny}\ge 8$.

NE_INT

On entry, $\mathbf{m}=〈\mathit{\text{value}}〉$.
Constraint: $\mathbf{m}>1$.

NE_INTERNAL_ERROR

An internal error has occurred in this function. Check the function call and any array sizes. If the call is correct then please contact NAG for assistance.

An unexpected error has been triggered by this function. Please contact NAG.
See Section 3.6.6 in the Essential Introduction for further information.

NE_KNOTS_COINCIDE

More than four knots coincide at a single point.

NE_KNOTS_CONS

At least one set of knots is not in nondecreasing order.

NE_NO_LICENCE

Your licence key may have expired or may not have been installed correctly.
See Section 3.6.5 in the Essential Introduction for further information.

NE_PANEL_ORDER

Array point does not indicate the data points in panel order.

NE_WEIGHT_ZERO

All the weights are zero, or rank determined as zero.

7  Accuracy

8  Parallelism and Performance

9  Further Comments

10  Example

10.1  Program Text

Program Text (e02dace.c)

10.2  Program Data

Program Data (e02dace.d)

10.3  Program Results

Program Results (e02dace.r)