Identifier     inter_pol

 Purpose        Perform different kinds of interpolation to resample a 
                spectrum 

 Synopsis       status = inter_pol([algo], xarr, yarr, sarr, refarr, 
                                   yarr_out, sarr_out)


 Arguments      Name      I/O Type       Description
                -----------------------------------------------------
                algo       I  string     indicate interpolation algorithm;    
                                         default = 'poly1 ' (linear)
                xarr       I  Fltarr     x-scale (e.g. wavelength array) that
                                         is to be resampled
                yarr       I  Fltarr     y-scale (e.g. flux array) that
                                         is to be resampled
                sarr       I  Fltarr     sigma array (stdev) for yarr
                refarr     I  Fltarr     reference scale to which x-scale
                                         is to be resampled
                sarr_out   O  Fltarr     the propagated errors of yarr_out
                yarr_out   O  Fltarr     the rebinned yarr (interpolated
                                         flux array)

 Returns        error status, 1 for fatal, 0 otherwise       

 Description    xarr has to be strictly monotonically increasing (or decreasing).
                If the reference array contains multiple points at the 'same'
                value, the interpolation provides each of these points
                with the same value. This means that the reference array
                has to be monotonically but need not to be strictly 
                monotonically increasing (or decreasing).
                The supported methods of interpolation are:
                  1) cubic spline interpolation 
                     Value of algo: 'spline'

                  2) polynomial interpolation 
                     Value of algo: 'polyx' where x stands for the grade of
                     the polynomial. Example: poly3 for third order polynomial. 

                The reference scale can be locally coarser or finer than the
                data. Both may be unequally sampled.

                The error for each interpolated data point (flux) is computed 
                as follows.
                weighted mean of the standard deviations of the points
                used in interpolation (For cubic spline, 5 points are
                used, the closest point, and 2 additional points on each
                side). Weights are  computed as the seperations between
                the reference point and the points in input xarr array.

 Comment        A more sphisticated method to comput error propagation will 
                be used in later versions.   Also, linear interpolation 
                (flux conserving) will be available in upcoming version.


 Example        1) status = inter_pol(lsanwav, lsanflx, lsanflxu,lsanwav2,
                                      lsanflx2, lsanflxu2)
                   new grid is given by lsanwav2 (the wavelength scale
                   of a second spectrum). By default linear interpolation is
                   performed.

 Dependencies   CALLS:  avgsig, binsrch, kwd_notset, polyint, sap_error
                CALLED FROM: sap_rebin, tippex

 Category       ISAP

 Filename       inter_pol.pro

 Author         Iffat R. Khan

 Version        0.3

 History             27.7.95   definition of requirements - first draft   E. Sturm 
                      8.8.95   revision of requirements                   E. Sturm
                      1.9.95   revision of requirements and code          J. Mazz
                0.1   8.9.95   Design and coding                          I. Khan
                0.2  17.10.95  revised code (include "linear" for algo)   I. Khan
                0.3  02.11.95  Revised parameters                         I. Khan
                               checking/Error messages
                1.0  24-05-96  change usage to FUNCTION from PRO          I. Khan
                               to handle error status flag

;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
Copyright (C) 1995, California Institute of Technology.  ;
U.S. Government Sponsorship under NASA Contract NAS7-918 ;
is acknowledged.                                         ;
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;