naginterfaces.library.fit.dim2_spline_grid¶
- naginterfaces.library.fit.dim2_spline_grid(start, x, y, f, s, nx, lamda, ny, mu, comm)[source]¶
dim2_spline_grid
computes a bicubic spline approximation to a set of data values, given on a rectangular grid in the - 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://www.nag.com/numeric/nl/nagdoc_29/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).
The function will build up the knot set starting with no interior knots. No values need be assigned to the arguments , , , , [‘wrk’] or [‘iwrk’].
The function will restart the knot-placing strategy using the knots found in a previous call of the function. In this case, the arguments , , , , [‘wrk’] and [‘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 . This is particularly useful when different smoothing factors are used for the same dataset.
- xfloat, array-like, shape
must be set to , the coordinate of the th grid point along the axis, for .
- yfloat, array-like, shape
must be set to , the coordinate of the th grid point along the axis, for .
- ffloat, array-like, shape
must contain the data value , for , for .
- sfloat
The smoothing factor, .
If , the function returns an interpolating spline.
If is smaller than machine precision, it is assumed equal to zero.
For advice on the choice of , see Notes and Further Comments.
- nxint
If the warm start option is used, the value of must be left unchanged from the previous call.
- lamdafloat, array-like, shape
If the warm start option is used, the values must be left unchanged from the previous call.
- nyint
If the warm start option is used, the value of must be left unchanged from the previous call.
- mufloat, array-like, shape
If the warm start option is used, the values 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, , of the computed spline with respect to the variable.
- lamdafloat, ndarray, shape
Contains the complete set of knots associated with the variable, i.e., the interior knots as well as the additional knots
and
needed for the B-spline representation.
- nyint
The total number of knots, , of the computed spline with respect to the variable.
- mufloat, ndarray, shape
Contains the complete set of knots associated with the variable, i.e., the interior knots as well as the additional knots
and
needed for the B-spline representation.
- cfloat, ndarray, shape
The coefficients of the spline approximation. is the coefficient defined in Notes.
- fpfloat
The sum of squared residuals, , of the computed spline approximation. If , this is an interpolating spline. should equal within a relative tolerance of unless , when the spline has no interior knots and so is simply a bicubic polynomial. For knots to be inserted, must be set to a value below the value of produced in this case.
- Raises
- NagValueError
- (errno )
On entry, , , and .
Constraint: if , and .
- (errno )
On entry, .
Constraint: .
- (errno )
On entry, .
Constraint: .
- (errno )
On entry, .
Constraint: .
- (errno )
On entry, .
Constraint: .
- (errno )
On entry, .
Constraint: .
- (errno )
On entry, or : .
- (errno )
On entry, , and .
Constraint: for all .
- (errno )
On entry, , and .
Constraint: for all .
- (errno )
The number of knots needed in one direction is greater than or : , . Possibly is too small: .
- (errno )
The iterative process has failed to converge. Possibly is too small: .
- 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 to the set of data points , for , for .The spline is given in the B-spline representation
where and denote normalized cubic B-splines, the former defined on the knots to and the latter on the knots to . For further details, see Hayes and Halliday (1974) for bicubic splines and de Boor (1972) for normalized B-splines.
The total numbers and of these knots and their values and are chosen automatically by the function. The knots and are the interior knots; they divide the approximation domain into subpanels , for , for . Then, much as in the curve case (see
dim1_spline_auto()
), the coefficients are determined as the solution of the following constrained minimization problem:subject to the constraint
where
is a measure of the (lack of) smoothness of . Its value depends on the discontinuity jumps in 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).
denotes the residual ,
and
is a non-negative number specified by you.
By means of the argument , ‘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 is too large, the spline will be too smooth and signal will be lost (underfit); if is too small, the spline will pick up too much noise (overfit). In the extreme cases the function will return an interpolating spline if is set to zero, and the least squares bicubic polynomial if is set very large. Experimenting with -values between these two extremes should result in a good compromise. (See Choice of s for advice on choice of .)
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 ), 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()
ordim2_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