;+
; NAME:
;        FITEXP
;
; PURPOSE:
;        Fits data to an exponential function of the form:
;
;                  a * exp( -b*(x-x0) )
; CATEGORY:
;        Math.
;
; CALLING SEQUENCE:
;
;        Result = FITEXP( X, Y [, Param, Sigma ] )
;
; INPUTS:
;        X,Y:      Data to be fitted.
;
; OPTIONAL INPUT KEYWORD PARAMETERS:
;
;        RESTRICT: Set this keyword to fit a restricted range of data, (0=Default).
;
;        HELP:     Set this keyword to display help messages on how to draw
;                  a line to determine the initial parameters.
;
;        Any other keywords will be passed on as _EXTRA keywords to the plot
;        procedure called in this routine.
;
; OUTPUTS:
;        This function returns a vector of fitted Y values for the given
;        parameters, Param.
;
; OPTIONAL OUTPUTS:
;
;        Param:    A vector containing the fitted parameters: [a, b, x0]
;
;        Sigma:    A vector of standard deviations for the elements of Param.
;
; OPTIONAL OUTPUT KEYWORD PARAMETERS:
;
;        CHI2:     Set this keyword equal to a named variable that will contain
;                  the value of chi-squared.
;
;        DOF:      Number of degrees of freedom associated with the chi-squared.
;
;        HERE:     A longword vector that contains the one-dimensional subscripts
;                  of the fitted elements of Y.
;
; MODIFICATION HISTORY:
;        Written by:    Han Wen, September 1996.
;        27-SEP-1996    Added RESTRICT keyword.
;-
pro EXPFCN, x, a, f, pder
         f    = a(0)*exp(-a(1)*x)
         pder = FLTARR(N_ELEMENTS(x),2)
         pder(*,0) = exp(-a(1)*x)
         pder(*,1) = -x*f
end

function FITEXP, X, Y, Param, Sigma_, HELP=Help, HERE=Here, TITLE=Title, $
         XRANGE=Xrange, YRANGE=Yrange, CHI2=Chi2, DOF=DOF, _EXTRA=Plot_keys, $
         RESTRICT=Restrict

         if (N_ELEMENTS(Plot_keys) eq 0) then Plot_keys = {YTYPE:1}
         if (N_ELEMENTS(Xrange)    eq 0) then Xrange    = [MIN(x,MAX=mx),mx]
         if (N_ELEMENTS(Yrange)    eq 0) then Yrange    = [MIN(y>1,MAX=mx),mx]
         if (N_ELEMENTS(Title)     eq 0) then Title     = ''

;   Select data region to fit and initial conditions for the fit parameters

         loadct,12 & red = 160
         if KEYWORD_SET(Restrict) then begin
              h    = WHEREGION(x,y>1,PSYM=10,/YTYPE, COLOR=red, $
                               TITLE=TITLE+' (Mark Rectangular Region:)',$
                               XRANGE=Xrange, YRANGE=Yrange, _EXTRA=Plot_keys)
         endif else h = LINDGEN(N_ELEMENTS(x))

         plot,x(h),y(h)>1,PSYM=10,/YTYPE, $
              TITLE='Mark line estimate:', _EXTRA=Plot_keys
         r    = MRK_LINE(/STATUS,HELP=Help,COLOR=red)
         p0   = r(*,0) & p1=r(*,1) & m=(alog(p0(1))-alog(p1(1)))/(p1(0)-p0(0))
         b    = p0(1) - m*p0(0)

;   Determine restricted data region

         hh   = WHERE( y(h) gt 0, npts )
         here = h(hh)
         xfit = x(here) & xfit = xfit - xfit(0)
         yfit = y(here)
         wfit = 1./yfit
         DOF  = npts - 3

         x0   = x(h(hh(0)))
         y0   = m*x0 + b
         Param= [y0,m]

;   Apply a minimize least-squares algorithm to determine fit parameters

         fit  = CURVEFIT(xfit, yfit, wfit, Param, Sigma_, $
                        FUNCTION_NAME='EXPFCN', CHI2=Chi2)
         plot,x(h),y(h)>1,PSYM=1,SYMSIZE=0.5,/YTYPE,TITLE=Title+' (Results)' $
              ,_EXTRA=Plot_keys
         oplot,xfit+x0,fit, COLOR=red

         fit  = Param(0)*exp( -Param(1)*(x - DOUBLE(x0)) )

         Param          = [Param      ,x0]
         Sigma_    = [Sigma_, 0]

         return, fit
end