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'
%    'not-a-knot', 'clamped', 'second', 'periodic', 'variational', 'Lagrange'
%    'cubic smoothing spline', 'quintic smoothing spline'
%    'knots',  'end knots', 'interior knots'
%    'least squares'
%    'NURBS', 'rational spline', 'rBform', 'rpform'
%    '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.

% cb 12-13,24-30aug,19sep99, 06feb00, 13feb00

%   Copyright 1987-2000 by C. de Boor and The MathWorks, Inc.
%   $Revision: 1.5 $  $Date: 2000/04/25 14:14:11 $ 

if ~isstr(term)|length(term)<2
   error('Input must be a string, of length>1.')
end

switch term(1:2)
case 'B-'
   if length(term)<3
      error(['The input, ',term,', is ambiguous.'])
   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'
   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 '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(['The input, ',term',', is ambiguous.'])
   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 '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 '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 '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  an integer >1  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
