function [expl,term] = spterms(term) %SPTERMS Explanation of spline toolbox terms. % % EXPL = SPTERMS(TERM) returns a string, or cell array of strings, containing % an explanation of the term specified by the string TERM. % Here are the possibilities: % 'B-form', 'basic interval' % 'B-spline','breaks' % 'cubic spline interpolation', 'endconditions' % 'not-a-knot', 'clamped', 'second', 'periodic', 'variational', 'Lagrange' % 'cubic smoothing spline', 'quintic smoothing spline' % 'error' % 'knots', 'end knots', 'interior knots' % 'least squares' % 'NURBS', 'rational spline', 'rBform', 'rpform' % 'roughness measure' % 'thin-plate spline', 'centers', 'stform', 'basis function' % 'spline' % 'spline interpolation', 'Schoenberg-Whitney conditions' % 'order' % 'ppform' % 'sites_etc' % 'weight in roughness measure' % % Only the first so many (at least 2, but usually no more than 2) letters % of a term need to be supplied, with the optional second output argument % providing the full term understood. % % SPTERMS(TERM) without an output argument returns nothing, but puts the % explanation into a message box. % Copyright 1987-2003 C. de Boor and The MathWorks, Inc. % $Revision: 1.14 $ $Date: 2003/04/25 21:11:54 $ if ~ischar(term)|length(term)<2 error('SPLINES:SPTERMS:wrongterm','Input must be a string, of length>1.') end switch term(1:2) case 'B-' if length(term)<3 error('SPLINES:SPTERMS:unclearterm',... ['B-form OR B-spline?']) end if term(3)=='f' term = 'B-form'; mess =... {['The B-form of a spline provides an order, a knot sequence, and',... ' the coefficients in a weighted sum of the B-splines (for that',... ' order and knot sequence) that adds up to that spline.']}; else term = 'B-spline'; mess =... {'';['The B(asic)-SPLINE with knot sequence t(i) < ... < t(i+k) is',... ' the pp function, unique up to scaling, of order k with breaks',... ' t(i:i+k), that is nonzero only inside the interval (t(i) .. t(i+k))',... ' and has k-2 continuous derivatives.']; ['This definition carries over to the more general knot sequence',... ' t(i) <= ... <= t(i+k) , except that, across a break that',... ' appears with multiplicity m>1 in the knot sequence,',... ' only the first k-1-m derivatives are continuous.']; 'A standard notation for this B-spline is B( . | t(i:i+k) ) .'; ['In the Spline Toolbox, the B-splines are normalized so that they',... ' sum to 1,']; ''; ['sum_{i=j-k+1:j} B( . | t(i:i+k) ) = 1 on the interval',... ' [t(j)..t(j+1)] .']; '';['Use the GUI bspligui to generate pictures of some B-splines,',... ' and explore the dependence of a B-spline on its knots.']}; end case 'ba' switch term(5) case 'c' term = 'basic interval'; mess =... {['The various forms of a spline incorporate a',... ' BASIC INTERVAL. It is the interval of interest.']; ['In the B-form (BBform, rBform), it is the interval given by its',... ' first and last knot.']; ['In the ppform (rpform), it is given by the first and last entry in',... ' its break sequence.']; ['The two kinds of form differ in that a spline in B-form is zero',... ' outside its basic interval, while a spline in ppform is defined',... ' outside its basic interval by continuation of its first,',... ' respectively, last polynomial piece.']}; case 's' term = 'basis function'; mess = ... {'The basis function of an stform is the function whose translates, ',... 'by the centers of that form, provide the individual terms in the ',... 'weighted sum that is the function described by that form.'}; end case 'br' term = 'breaks'; mess = ... {[' A BREAK is a site at which two neighboring polynomial pieces',... ' of a pp function meet.']; ['Use the toolbox command fnbrk(cs,''breaks'') to extract the',... ' breaks, along with the endpoints of the ''basic interval'' of',... ' the pp function whose ppform is contained in the variable cs .']}; case 'cu' if length(term)<8 error('SPLINES:SPTERMS:unclearterm',... ['cubic spline OR cubic smoothing spline?']) end if term(8)=='p' term = 'cubic spline interpolation'; mess = ... {'';['A CUBIC SPLINE INTERPOLANT to given data x,y matches the given',... ' data exactly. Between any two neighboring data sites,',... ' x(i) and x(i+1), it is a cubic polynomial. Neighboring cubic',... ' polynomials match in value, first, and second derivative',... ' across their common data site.']; ['This determines the cubic spline completely up to two degrees',... ' of freedom, and these are usually prescribed as two',... ' END CONDITIONS, one at each end.']}; else term = 'cubic smoothing spline'; mess = ... {'';'Schoenberg''s cubic SMOOTHING SPLINE s uniquely minimizes the weighted average'; ''; ' p * sum( w.*(y - s(x)).^2 ) + (1-p) * integral (D^2 s)^2'; ''; ['of an ERROR measure and a ROUGHNESS measure, for given data (x,y) and',... ' given SMOOTHING PARAMETER p (and D^2 s the 2nd derivative of s ).']; ['For p==1 , the smoothing spline is just the variational spline',... ' interpolant.']; ['For p==0 , the cubic smoothing spline is the least-squares straight',... ' line approximation.']}; end % end conditions case 'no' term = 'not-a-knot end condition'; mess = ... {['The jump in the third derivative across the data site next to the',... ' end is set to zero. With that, the two cubic polynomial pieces',... ' involved become the same. In effect, the interpolant has no',... ' break or knot at that site. Hence the name ''not-a-knot''.']}; case 'cl' term = 'clamped end condition' % complete or clamped or first derivative; mess = ... {['In clamped or complete cubic spline interpolation, the endslopes',... ' are set to specified values.']}; case 'se' term = 'second end condition' % second derivative; mess = ... {'The second derivative at the two ends are set to specific values.'}; case 'pe' term = 'periodic end condition'; mess = ... {'With a:=x(1) and b:=x(end) the two endpoints, the three conditions'; ' f(a) = f(b), Df(a) = Df(b), and D^2 f(a) = D^2 f(b) are enforced.'}; case 'va' term = 'variational end condition' % variational; mess = ... {['In variational cubic spline interpolation, the second derivative',... ' at the two ends is set to zero. This is also called ''natural''',... ' cubic spline interpolation, with ''natural'' the term used in',... ' the Calculus of Variations for end conditions that arise when',... ' no end condition is explicitly enforced.']; ['The variational problem here is the minimization of the integral',... ' of the square of the second derivative of the function that',... ' matches the given data.']}; case 'La' term = 'Lagrange end condition'; mess = ... {['The endslope is made to agree with the slope of the cubic',... ' polynomial that matches the four data points nearest that end.']}; case 'ro' term = 'roughness measure'; mess = ... {'The roughness of a spline f of order 2*m is measured by the number';'';... ' integral lambda(t) | (D^m f)(t) |^2 dt';'';... ['with lambda a piecewise constant function with breaks at the data',... ' sites (and nowhere else). The default for lambda is the constant',... ' function, 1 .']}; case 'we' term = 'weight in roughness measure'; mess = ... {'The roughness of a cubic spline f is measured by the number';''; ... ' integral lambda(t) | (D^2 f)(t) |^2 dt';'';... ['with lambda a piecewise constant function with breaks at the data',... ' sites (and nowhere else). The default for lambda is the constant',... ' function, 1 .']; ... ['To specify lambda , provide, for i=2:n, its value lam(i-1) on the', ... ' interval (x_{i-1} .. x_i). In calling on csaps, this is done by', ... ' giving the input p as the n-vector [smoothing parameter, lam], while',... ' for spaps, one gives the input tol as the n-vector ',... ' [tolerance, lam].']}; case 'kn' term = 'knots'; mess = ... {'';'KNOTS are parameters used in the B-form of a spline.'; 'Any nondecreasing sequence t can serve as a knot sequence.'; ['Assuming t has length n+k , there are exactly n B-splines of order k ',... ' associated with t , with the j-th Bspline having the knots t(j:j+k), all j.',... ' These n B-splines serve as a convenient basis for the space',... ' S_{k,t} of splines of order k with knot sequence t .']; ['The elements of this space are piecewise polynomial of order k with',... ' breaks at the knots, but their smoothness across each break depends on the',... ' multiplicity with which that break occurs in the knot sequence. The rule:']; ''; ' number of smoothness conditions + knot multiplicity = order .'}; case 'en' term = 'end knots'; mess = ... {'';['When constructing the B-form of a cubic spline, the first four',... ' knots are usually chosen to equal the left end of the', ... ' interval of interest, and the',... ' last four knots are chosen to equal the right end of that',... ' interval (thereby making it the ''basic interval'' for the',... ' resulting B-form).']; ['These END KNOTS have no influence on the behavior of the spline on',... ' that interval of interest and could even be chosen to be distinct',... ' and lie outside that interval (which would increase the',... ' ''basic interval'' of the resulting B-form).']; ['More generally, for a spline of order k , the first and last k ',... ' knots in its B-form are usually chosen to equal the corresponding',... ' end points of the interval of interest and thereby become the end knots.']}; case 'er' term = 'error'; mess = ... {['The error is, by definition, the difference between the exact value',... ' and the approximation.']; ... ['In least-squares approximation and in smoothing, the error in the',... ' approximation f to the data (x(j), y(:,j)), j=1:length(x), is',... ' measured by the weighted sum of squares'];''; ' sum_j w(j) | y(:,j) - f(x(j)) |^2';''; 'for some nonnegative weights w .'}; case 'in' term = 'interior knots'; mess = ... {['The knots of a spline inside its basic interval are its INTERIOR',... ' KNOTS. Usually, some derivative of a spline has a jump across',... ' such a knot. The lowest order derivative in which a jump may',... ' occur depends on the multiplicity m of that knot and the order',... ' k of the spline: it''s the derivative of order k-m .']; ['For example, across a simple knot (m=1), a cubic spline (k=4)',... ' may have a jump in the 3rd derivative (3 = 4-1), but not in any',... ' lower-order derivative (like the 2nd, 1st, or 0th derivative).']}; case 'le' term = 'least squares'; mess = ... {['In (discrete) LEAST_SQUARES spline approximation, the element s ',... ' from the specified spline space closest to the data (x,y) is',... ' constructed, with the distance measured by the ERROR: ',... ' sum( w.*(y - s(x)).^2 ) .']; 'A SPLINE SPACE is specified by giving its knot sequence and its order.'; ['The knot sequence is required to satisfy the Schoenberg-Whitney', ... ' Conditions wrto some subsequence of the given data sites, x .']}; case {'NU','nu'} term = 'NURBS'; mess = ... {'A rational spline in which each coefficient of the denominator spline'; ['is an explicit factor of the corresponding coefficient of the',... ' numerator spline.']}; case 'ra' term = 'rational spline'; mess = ... {'A rational spline is a ratio of splines, that is a function of the form';... '';' r(x) = s(x)/w(x),';''; ... 'with both s and w splines, of the same order and with the same knots or';... 'breaks, and with w scalar-valued, while s may be vector-valued.';'';... 'A rational spline may be in rBform or rpform which, in effect, is the';... 'B-form or ppform of the corresponding vector-valued spline';'';... ' R(x) = [s(x);w(x)].'}; case 'rB' term = 'rBform'; mess = ... {'The rBform of a rational spline r(x) = s(x)/w(x) provides its order,',... ' its knot sequence, and the coefficients for the B-form of the',... ' corresponding (vector-valued) spline R(x) = [s(x);w(x)].'}; case 'rp' term = 'rpform'; mess = ... {'The rpform of a rational spline r(x) = s(x)/w(x) provides its order,',... ' its break sequence, and the local polynomial coefficients for the',... ' ppform of the corresponding (vector-valued) spline R(x) = [s(x);w(x)].'}; case 'st' term = 'stform'; mess = ... {['The stform provides the centers, coefficients, and type of a function ',... 'of the form sum_j coefs(:,j)*psi_j(x) + p(x) , with p a lower-', ... 'order polynomial, and psi_j(x) = psi(x-c_j), all j. Here, the c_j are ',... 'the centers, and the function psi, called the basis function, and the ',... 'degree of the polynomial p are specified by the particular type. '];, ... 'The thin-plate spline is a standard example.'}; case 'th' term = 'thin-plate spline'; mess = ... {'A thin-plate spline is any bivariate function of the form f(x) = ',... 'sum_j coefs(:,j) phi(norm(x-centers(:,j))^2) + coefs(:,end-2)*x(1) ',... '+ coefs(:,end-1)*x(2) + coefs(:,end), with phi(t) := t log(t) .'}; case 'ce' term = 'centers'; mess = ... {'The centers of a stform are the sites by which the basis function of ',... 'that form is translated to provide the individual terms of that form.'}; case 'qu' term = 'quintic smoothing spline'; mess = {... ['The QUINTIC smoothing spline differs from the cubic smoothing spline',... ' only in that its roughness measure involves the 3rd rather than the',... ' 2nd derivative. Correspondingly, it is a spline of order 6 rather than',... ' of order 4.'];'';... ['In the Spline Toolbox, the quintic smoothing spline is provided by',... ' the command spaps . The level of desired smoothness is specified',... ' indirectly, by specifying a certain tolerance, and the command',... ' returns the smoothest spline within that tolerance of the given data.']}; case {'sp','Sc'} % this one, we have to split further if isempty(findstr(' ',term))&term(2)~='c' term = 'spline'; mess = ... {['That''s a hard one. Roughly speaking, a (univariate, polynomial) SPLINE',... ' is any more or less smooth piecewise polynomial function.']}; else switch term(2) case 'p' term = 'spline interpolation'; case 'c' term = 'Schoenberg-Whitney conditions'; end mess =... {['General spline interpolation to data (x,y) is carried out in this', ... ' toolbox with the command SPAPI, and requires, in addition to the data,',... ' specification of a knot sequence, t, that satisfies the SCHOENBERG-',... 'WHITNEY CONDITIONS wrto the the given data sites, in the following sense.']; ... '';['Assuming that x is nondecreasing and of length n , and assuming',... ' that also t is nondecreasing, the difference k := length(t) - n',... ' must be positive, and, further,'];''; ' t(i) <= x(i) <= t(i+k), for i=1:n ,';''; ['with equality allowed only when the relevant knot has multiplicity k', ... ' (as is typically the case for the endknots).'];''; ['If the knot sequence t satisfies the Schoenberg-Whitney conditions',... ' wrto the data sites x , then there is exactly one spline of order k',... ' with knot sequence t that matches the given data.']; ['It is this spline that is being supplied by the command spapi(t,x,y).'];... ['The variant spapi(k,x,y), with k a natural number, supplies a knot', ... ' sequence t of length k+length(x) that satisfies the Schoenberg-',... 'Whitney conditions wrto x . See the help for spapi for further detail.']}; end case 'or' term = 'order'; mess = ... {[' The ORDER of a spline counts the number of coefficients in any',... ' one of its polynomial pieces.']; 'For example, a cubic spline is of order 4.'}; case 'pp' term = 'ppform'; mess = ... {['The PPFORM of a spline provides its breaks, its order, and the',... ' coefficients for the shifted power form of its polynomial pieces.']}; case 'si' term = 'sites_etc'; mess = ... {['The terms SITES and VALUES are used here instead of their',... ' oldfashioned counterparts, ABSCISSAE and ORDINATES.']; ['The data POINT (x(i),y(i)) tells us that, at the SITE x(i) ',... ', we would like the spline to take the VALUE y(i) .']}; otherwise mess = {'nothing yet'}; end if nargout>0 expl = mess; else msgbox(mess,['Explanation: ',term]) end