Documentation:
C   COMPUTER            - VAX/DOUBLE
C
C   AUTHOR              - M.F.HUTCHINSON
C                         CSIRO DIVISION OF MATHEMATICS AND STATISTICS
C                         P.O. BOX 1965
C                         CANBERRA, ACT 2601
C                         AUSTRALIA
C
C   LATEST REVISION     - 15 AUGUST 1985
C
C   PURPOSE             - CUBIC SPLINE DATA SMOOTHER
C
C   USAGE               - CALL CUBGCV (X,F,DF,N,Y,C,IC,VAR,JOB,SE,WK,IER
C
C   ARGUMENTS    X      - VECTOR OF LENGTH N CONTAINING THE
C                           ABSCISSAE OF THE N DATA POINTS
C                           (X(I),F(I)) I=1..N. (INPUT) X
C                           MUST BE ORDERED SO THAT
C                           X(I) .LT. X(I+1).
C                F      - VECTOR OF LENGTH N CONTAINING THE
C                           ORDINATES (OR FUNCTION VALUES)
C                           OF THE N DATA POINTS (INPUT).
C                DF     - VECTOR OF LENGTH N. (INPUT/OUTPUT)
C                           DF(I) IS THE RELATIVE STANDARD DEVIATION
C                           OF THE ERROR ASSOCIATED WITH DATA POINT I.
C                           EACH DF(I) MUST BE POSITIVE.  THE VALUES IN
C                           DF ARE SCALED BY THE SUBROUTINE SO THAT
C                           THEIR MEAN SQUARE VALUE IS 1, AND UNSCALED
C                           AGAIN ON NORMAL EXIT.
C                           THE MEAN SQUARE VALUE OF THE DF(I) IS RETURN
C                           IN WK(7) ON NORMAL EXIT.
C                           IF THE ABSOLUTE STANDARD DEVIATIONS ARE KNOW
C                           THESE SHOULD BE PROVIDED IN DF AND THE ERROR
C                           VARIANCE PARAMETER VAR (SEE BELOW) SHOULD TH
C                           BE SET TO 1.
C                           IF THE RELATIVE STANDARD DEVIATIONS ARE UNKN
C                           SET EACH DF(I)=1.
C                N      - NUMBER OF DATA POINTS (INPUT).
C                           N MUST BE .GE. 3.
C                Y,C    - SPLINE COEFFICIENTS. (OUTPUT) Y
C                           IS A VECTOR OF LENGTH N. C IS
C                           AN N-1 BY 3 MATRIX. THE VALUE
C                           OF THE SPLINE APPROXIMATION AT T IS
C                           S(T)=((C(I,3)*D+C(I,2))*D+C(I,1))*D+Y(I)
C                           WHERE X(I).LE.T.LT.X(I+1) AND
C                           D = T-X(I).
C                IC     - ROW DIMENSION OF MATRIX C EXACTLY
C                           AS SPECIFIED IN THE DIMENSION
C                           STATEMENT IN THE CALLING PROGRAM. (INPUT)
C                VAR    - ERROR VARIANCE. (INPUT/OUTPUT)
C                           IF VAR IS NEGATIVE (I.E. UNKNOWN) THEN
C                           THE SMOOTHING PARAMETER IS DETERMINED
C                           BY MINIMIZING THE GENERALIZED CROSS VALIDATI
C                           AND AN ESTIMATE OF THE ERROR VARIANCE IS
C                           RETURNED IN VAR.
C                           IF VAR IS NON-NEGATIVE (I.E. KNOWN) THEN THE
C                           SMOOTHING PARAMETER IS DETERMINED TO MINIMIZ
C                           AN ESTIMATE, WHICH DEPENDS ON VAR, OF THE TR
C                           MEAN SQUARE ERROR, AND VAR IS UNCHANGED.
C                           IN PARTICULAR, IF VAR IS ZERO, THEN AN
C                           INTERPOLATING NATURAL CUBIC SPLINE IS CALCUL
C                           VAR SHOULD BE SET TO 1 IF ABSOLUTE STANDARD
C                           DEVIATIONS HAVE BEEN PROVIDED IN DF (SEE ABO
C                JOB    - JOB SELECTION PARAMETER. (INPUT)
C                         JOB = 0 SHOULD BE SELECTED IF POINT STANDARD E
C                           ESTIMATES ARE NOT REQUIRED IN SE.
C                         JOB = 1 SHOULD BE SELECTED IF POINT STANDARD E
C                           ESTIMATES ARE REQUIRED IN SE.
C                SE     - VECTOR OF LENGTH N CONTAINING BAYESIAN STANDAR
C                           ERROR ESTIMATES OF THE FITTED SPLINE VALUES 
C                           SE IS NOT REFERENCED IF JOB=0. (OUTPUT)
C                WK     - WORK VECTOR OF LENGTH 7*(N + 2). ON NORMAL EXI
C                           FIRST 7 VALUES OF WK ARE ASSIGNED AS FOLLOWS
C
C                           WK(1) = SMOOTHING PARAMETER (= RHO/(RHO + 1)
C                           WK(2) = ESTIMATE OF THE NUMBER OF DEGREES OF
C                                   FREEDOM OF THE RESIDUAL SUM OF SQUAR
C                           WK(3) = GENERALIZED CROSS VALIDATION
C                           WK(4) = MEAN SQUARE RESIDUAL
C                           WK(5) = ESTIMATE OF THE TRUE MEAN SQUARE ERR
C                                   AT THE DATA POINTS
C                           WK(6) = ESTIMATE OF THE ERROR VARIANCE
C                           WK(7) = MEAN SQUARE VALUE OF THE DF(I)
C
C                           IF WK(1)=0 (RHO=0) AN INTERPOLATING NATURAL 
C                           SPLINE HAS BEEN CALCULATED.
C                           IF WK(1)=1 (RHO=INFINITE) A LEAST SQUARES
C                           REGRESSION LINE HAS BEEN CALCULATED.
C                           WK(2) IS AN ESTIMATE OF THE NUMBER OF DEGREE
C                           FREEDOM OF THE RESIDUAL WHICH REDUCES TO THE
C                           USUAL VALUE OF N-2 WHEN A LEAST SQUARES REGR
C                           LINE IS CALCULATED.
C                           WK(3),WK(4),WK(5) ARE CALCULATED WITH THE DF
C                           SCALED TO HAVE MEAN SQUARE VALUE 1.  THE
C                           UNSCALED VALUES OF WK(3),WK(4),WK(5) MAY BE
C                           CALCULATED BY DIVIDING BY WK(7).
C                           WK(6) COINCIDES WITH THE OUTPUT VALUE OF VAR
C                           VAR IS NEGATIVE ON INPUT.  IT IS CALCULATED 
C                           THE UNSCALED VALUES OF THE DF(I) TO FACILITA
C                           COMPARISONS WITH A PRIORI VARIANCE ESTIMATES
C
C                IER    - ERROR PARAMETER. (OUTPUT)
C                         TERMINAL ERROR
C                           IER = 129, IC IS LESS THAN N-1.
C                           IER = 130, N IS LESS THAN 3.
C                           IER = 131, INPUT ABSCISSAE ARE NOT
C                             ORDERED SO THAT X(I).LT.X(I+1).
C                           IER = 132, DF(I) IS NOT POSITIVE FOR SOME I.
C                           IER = 133, JOB IS NOT 0 OR 1.
C
C   PRECISION/HARDWARE  - DOUBLE
C
C   REQUIRED ROUTINES   - SPINT1,SPFIT1,SPCOF1,SPERR1
C
C   REMARKS      THE NUMBER OF ARITHMETIC OPERATIONS REQUIRED BY THE
C                SUBROUTINE IS PROPORTIONAL TO N.  THE SUBROUTINE
C                USES AN ALGORITHM DEVELOPED BY M.F. HUTCHINSON AND
C                F.R. DE HOOG, 'SMOOTHING NOISY DATA WITH SPLINE
C                FUNCTIONS', NUMER. MATH. (IN PRESS)
C
C-----------------------------------------------------------------------
C


ALGORITHM

CUBGCV calculates a natural cubic spline curve which smoothes a given se
of data points, using statistical considerations to determine the amount
of smoothing required, as described in reference 2.  If the error varian
is known, it should be supplied to the routine in VAR.  The degree of
smoothing is then determined by minimizing an unbiased estimate of the t
mean square error.  On the other hand, if the error variance is not know
should be set to -1.0.  The routine then determines the degree of smooth
by minimizing the generalized cross validation.  This is asymptotically 
same as minimizing the true mean square error (see reference 1).  In thi
case, an estimate of the error variance is returned in VAR which may be
compared with any a priori approximate estimates.  In either case, an
estimate of the true mean square error is returned in WK(5).  This estim
however, depends on the error variance estimate, and should only be acce
if the error variance estimate is reckoned to be correct.

If job is set to 1, bayesian estimates of the standard error of each
smoothed data value are returned in the array SE.  These also depend on
the error variance estimate and should only be accepted if the error
variance estimate is reckoned to be correct.  See reference 4.

The number of arithmetic operations and the amount of storage required b
the routine are both proportional to N, so that very large data sets may
analysed.  The data points do not have to be equally spaced or uniformly
weighted.  The residual and the spline coefficients are calculated in th
manner described in reference 3, while the trace and various statistics,
including the generalized cross validation, are calculated in the manner
described in reference 2.

When VAR is known, any value of N greater than 2 is acceptable.  It is
advisable, however, for N to be greater than about 20 when VAR is unknow
If the degree of smoothing done by CUBGCV when VAR is unknown is not
satisfactory, the user should try specifying the degree of smoothing by
setting VAR to a reasonable value.

References:

1.  Craven, Peter and Wahba, Grace, "Smoothing noisy data with spline
    functions", Numer. Math. 31, 377-403 (1979).
2.  Hutchinson, M.F. and de Hoog, F.R., "Smoothing noisy data with splin
    functions", Numer. Math. (in press).
3.  Reinsch, C.H., "Smoothing by spline functions", Numer. Math. 10,
    177-183 (1967).
4.  Wahba, Grace, "Bayesian 'confidence intervals' for the cross-validat
    smoothing spline", J.R.Statist. Soc. B 45, 133-150 (1983).


Example

A sequence of 50 data points are generated by adding a random variable w
uniform density in the interval [-0.3,0.3] to the curve y=sin(3*pi*x/2).
The abscissae are unequally spaced in [0,1].  Point standard error estim
are returned in SE by setting JOB to 1.  The error variance estimate is
returned in VAR.  It compares favourably with the true value of 0.03.
The IMSL function GGUBFS is used to generate sample values of a uniform
variable on [0,1].


INPUT:

      INTEGER          N,IC,JOB,IER
      DOUBLE PRECISION X(50),F(50),Y(50),DF(50),C(49,3),WK(400),
     *                 VAR,SE(50)
      DOUBLE PRECISION GGUBFS,DSEED,DN
      DATA DSEED/1.2345D4/
C
      N=50
      IC=49
      JOB=1
      VAR=-1.0D0
      DN=N
C
      DO 10 I=1,N
      X(I)=(I - 0.5)/DN + (2.0*GGUBFS(DSEED) - 1.0)/(3.0*DN)
      F(I)=DSIN(4.71238*X(I)) + (2.0*GGUBFS(DSEED) - 1.0)*0.3
      DF(I)=1.0D0
  10  CONTINUE
      CALL CUBGCV(X,F,DF,N,Y,C,IC,VAR,JOB,SE,WK,IER)
       .
       .
       .
      END

OUTPUT:

IER = 0
VAR = 0.0279
GENERALIZED CROSS VALIDATION = 0.0318
MEAN SQUARE RESIDUAL = 0.0246
RESIDUAL DEGREES OF FREEDOM = 43.97
FOR CHECKING PURPOSES THE FOLLOWING OUTPUT IS GIVEN:

X(1)  = 0.0046    F(1)  =  0.2222     Y(1)  =  0.0342     SE(1)  = 0.1004
X(21) = 0.4126    F(21) =  0.9810     Y(21) =  0.9069     SE(21) = 0.0525
X(41) = 0.8087    F(41) = -0.5392     Y(41) = -0.6242     SE(41) = 0.0541

