EZ_FIT [DIR]


by Ben-chin Cha (01/18/99)


INTRODUCTION

The ez_fit package collects the current available fit functions in IDL and packaged into a user friendly and simple to use fit program. All the parameters required for a selected fitting method are automatically set up for the user, the curve fitting becomes very easy task in ez_fit. It can be called by any other IDL program. It has been thoroughly tested on solaris/sun4 system and W95.

Two of the fitting methods svdfit and curvefit also allow the user to specify his own fit function through loading (i.e. compiling) a user's private program into IDL after the loading of ez_fit. Examples of compiling linear and non-linear fit functions are given in the last section of this document.

The ez_fit package can be plugged into any other IDL program. Currently it can be accessed directly from the data viewer or catcher.

Available Fit Methods [DIR]

The current available fitting methods supported by ez_fit are listed below. Since this package is built upon the avaiable IDL curve fitting methods, for detail information for each corresponding fitting method please refer the RSI's IDL on-line help. The only exception is the Lorenzian and multiple Lorenzian fitting is locally implemented by me.

If a user need to implement a curve fitting which is not currently supported by ez_fit, he can load his own fit program (the user has to make sure that the file name and the fit function used is unique to IDL program) and then select the SVDFIT or CURVEFIT method. Examples are given below in the last section. For detail information about SVDFIT or CURVEFIT method, please refer the RSI's IDL reference manual.

			      
       Fit Method             Fit Function
      ------------------------------------------------------------
	COMFIT      		
	   EXPONENTIAL   Y = a0  * a1^x + a2 
	   GEOMETRIC 	 Y = a0 * x^a1 + a2 
	   GOMPERTZ	 Y = a0 * a1^(a2*x) + a3
	   HYPERBOLIC	 Y = 1./(a0 + a1*x)
	   LOGISTIC	 Y = 1./(a0 * a1^x + a2)
	   LOGSQUARE	 Y = a0 + a1*alog10(x) + a2 * alog10(x)^2

   	CURVEFIT	Non-linear least square fit with weight 
			Default: 'FUNCT' 
			FUNCT = A0 * exp( -Z^2 / 2 ) + A3 + A4 * X + A5 * X^2
			Z = (X - A1) / A2

			Note: the user can substitute the 'FUNCT' by his
			      own fit function in CURVEFIT

	LADFIT		Y = A + Bx	

	LINFIT		Y = A + Bx	minimize chi-square	

	POLYFIT		PY = A0 + A1*x + A2*x^2 + ...
	POLYFITWFIT    	Y = A0 + A1*x + A2*x^2 + ...  weighted

	SVDFIT		Least square fit with weight

			Default
			Y = A0 + A1*X + A2*X^2 + ...

			SVDLEG
			P0(X) = 1
			P1(X) = X 
			P2(X) = (3 * X^2 - 1)/2
			P3(X) = (5 * X^3 - 3 * X) / 2 
			 ...
			Pn(X) = ((2n - 1)* X * Pn-1(X) - (n-1) * Pn-2(X)) / n 

			Default: 'MYFUNCT' 
			Y = A0 + A1 * sin(2*X)/X + A2 * cos(4*X)^2 

			Note: the user can substitute the 'MYFUNCT' by his
			      own fitting function in SVDFIT

	GAUSSFIT	F(x) = A0*EXP(-z^2/2) + A3 + A4*x + A5*x^2
			z=(x-A1)/A2
			A0 = Peak
			A1 = Mean
			A2 = Sigma

	LORENTZFIT	F(X) = A0 * A2^2 / ((X-A1)^2 + A2^2)
			A0 = Peak
			A1 = Mean
			A2 = FWHM/2

PROGRAM PACKAGE [DIR]

The ez_fit is written in IDL language.

The complete program package of ez_fit consists of following files:

ezfit                   - Unix script file auto starts
viewer_startup.pro      - IDL startup file used by ezfit script
os.init			- Operating system configuration file
plot1d.pro		- General purpose multi-line 1D plot package 
ez_fit.pro		- General purpose curve-fitting package 
The ezfit and viewer_startup.pro are specially written for the solaris/sun UNIX system for easy startup of ez_fit. For the W95 system, the IDLDE's file preferences dialog should be used to set up the startup file and environment.

The operating system configuration file is defined in os.init. The current setting works for the UNIX and W95 operating systems. It is assumed that for the UNIX operating system the ez_fit is installed under the $EPICS_EXTENSIONS/bin/$HOST_ARCH directory; for W95, the ez_fit is installed under the C:\IDL\VIEWER2.2 directory, or use the same EPICS file structure as for UNIX.

Setup Requirement

The automatic and easy to use curve fitting package ez_fit.pro can be plugged into any IDL program as long as the $EPICS_EXTENSIONS/bin/$HOST_ARCH directory is in user's IDL search path and the environment variable IDL_PATH is defined before invoking IDL. On UNIX,

	setenv EPICS_EXTENSIONS /usr/local/epics/extensions
	setenv IDL_PATH $EPICS_EXTENSIONS/bin/$HOST_ARCH:$IDL_PATH

Access EZ_FIT

On UNIX to run ez_fit as a stand alone process, just enter the following command at the UNIX command prompt.
	$ ezfit
To access ez_fit from the IDL prompt within the IDL session is given below:
	IDL> .run ez_fit
	IDL> ez_fit [,Xarray=x,Yarray=y] [,Im=im] [,Group=group]
Please refer EZ_FIT for the detailed commands syntax description. Ez_fit accepts X,Y input variables either directly from the keyword Xarray, Yarray on the command line or through reading data from an input file (as described in next section).

X holds the vector values of the independent variable. If 1D data to be loaded, then Y holds the array of all dependent variables. If 2D image to be loaded, then Yarray should hold the second independent variable Y vector, and IM should hold the 2D image array.

USER INTERFACE

Ez_fit is a mouse driven window application. The normal steps of running this application at the top level main window are: first load the input file, then select the curve to be fitted on the 2D Image window, then push 'Y vs X' button to display the selected curve on the 2D Image window, then just select the desired method of fitting from the 'Curve Fit' menu. Multiple Lorenzian fit can be accessed from the 'Multi Fit' menu.

At the end of each fitting calculation both the plot window and the tabulated text window will pop up showing the detail calculated results. The fitting plot window is re-adjustable by the mouse. A user can easily generate results for various fit methods and compare results from different fitting methods at his finger tip.

Available Input File Format [DIR]

If data is not passed into ez_fit on the command line then a user should use the 'File' menu to load the data into ez_fit. The input file can be either in XDR binary format or ASCII format. The ez_fit supports both 1D vector array or 2D image array. Currently, following three types of input format file are accepted by the ez_fit.

a. 1D Binary File [DIR]

Input 1D file must be saved in XDR binary format. It is composed of 2 pieces of data objects: Xarray and Yarray. They must be saved by the U_WRITE routine. Please refer u_readRef for creating/reading/writing/closing the XDR binary file.

The Xarray(N) contains N values of independent variable X. The Yarray(N,M) contains M dependent variables, and for each dependent variable it contains the N values corresponding to the N X values.

b. 2D Binary File [DIR]

Input 2D file must be saved in XDR binary format. It is composed of 3 pieces of data objects: Xarray, Yarray, and IM. They must be saved by the U_WRITE routine. Please refer u_readRef for creating/reading/writing/closing the XDR binary file.

The Xarray(N) contains N values of the first independent variable X. The Yarray(M) contains M values of the second independent variable Y. The IM(N,M) contains the 2D variable as function of X and Y, it gives the Z value corresponding to pair of X,Y values.

c. ASCII File [DIR]

Input ASCII file takes the column formatted tabulated data. It is loaded into ez_fit by calling the READASCII routine. Please refer READASCII for detail description about the ascii file.

The READASCII routine returns the corresponding Xarray, and Yarray based on the user selection on the read ascii dialog. The first column read in will be treated as the independent variable, the remaining columns read in will be treated as the corresponding dependent variables.

When the data is loaded in from the input file, the dependent variables will be shown as a 2D image, a user has to first select the curve number to be fitted by clicking the display image area. If none is selected by the user then the very first vector from the dependent array will be assumed.

GetData Menu [DIR]

The GetData menu let the user preview or varify the independent variable X and dependent variable Y (1D) or ZX/ZY (2D) selected before calling various fitting methods.
	GetData->VectorX
		 VectorY
		 VectorYz
		 VectorZx
		 2DImage

	VectorX  - draw the X vector vs Index (1D input only)
	VectorY  - draw the Y vector vs X vector (1D input only)
	VectorYz - draw the YZ vs X (2D input only)
	VectorZx - draw the ZX vs Y (2D input only)
	2DImage  - draw the Z value as 2D TV image (2D input only)

Curve Fit Menus [DIR]

There are two curve fitting menus: 'Curve Fit' and 'Multi Fit'. Currently there is only one method, multiple-Lorentzian fitting, available for Multi Fit.
	Curve Fit->COMFIT     ->EXPONENTIAL  
			   	GEOMETRIC 
			   	GOMPERTZ
			  	HYPERBOLIC	
			 	LOGISTIC
			  	LOGSQUARE	

		   CURVEFIT	
		   GAUSSFIT	 	
		   LADFIT
		   LINFIT	
		   LORENTZFIT
		   POLYFIT
		   POLYFITWFIT  
		   SVDFIT

	Multi Fit->REGRESS  (not implemented yet)
		   LORENTZIAN

Fit-Output Windows [DIR]

The fitting output consists of two windows: plot1d and tabulated text window. The coefficients, fit function, the original, and fit data are all displayed on both window.

User Supplied Fit Function [DIR]

IDL provides two ways of fitting user supplied fit function: CURVEFIT and SVDFIT. The CURVEFIT can be used for non-linear least squares fit. The SVDFIT method can be used for linear least squares fit. Examples are given below.

The private function to be fit must be written as an IDL function and compiled prior to calling SVDFIT or CURVEFIT.

1. MYFUNCT2 - Linear Function Example [DIR]

The IDL program 'test1.pro' gives an example of defining a private fitting program. It consists of two routines: MYFUNCT2 and GET_SVDFIT_MYFUNCT.

The private function MYFUNCT2 to be fit accepts two scalar values : X and M. X is the independent variable, and M is the number of coefficients in the fit function. It must return an M-element vector containing the basis functions. See the Example program given below.

The routine GET_SVDFIT_MYFUNCT is required by ez_fit to print out the fit function on plot and tabulated text output windows.

a. test1.pro [DIR]
FUNCTION myfunct2,X,M
; X : independent variable names
; M : number of terms defined in this function this must be consistant
;     with the return terms by this function
;

Y = [ [1.0], [sin(2*x)], [cos(4*x)^2], [cos(6*x)^4] , [x *sin(x)], [x], [x*x]]

nterm = n_elements(Y)
if M ne nterm then $
        res=dialog_message('For myfunct the NTERMS must be '+string(nterm), $
                /info,title='FITTING Info')
        return, Y
END

PRO get_svdfit_myfunct,fname,expres
ffname = strlowcase(fname)
if ffname eq 'myfunct2' then begin
        expres='Function Name Used: MYFUNCT2'
        expres=[expres,'Y = A0 + A1 * sin(2*x) + A2 * cos(4*x)^2 + A3 * sin(6*x)
^4 + A4 *x*sin(x) + A5 *x + A6*x^2']
end
END
b. Access SVDFIT [DIR]
Then a user can load the program into IDL after loading ez_fit this will add the fit function 'myfunct2' into ez_fit. The steps to access this new fitting method are given below:
In IDL ez_fit main window, select the 
	
	1. Load data into ez_fit
	2. Select the curve to be fit
	3. Pops up the SVDFIT Setup dialog by select:  Curve Fit->SVDFIT    
	4. Use Cntl^C and carriage return keys to interrupt ez_fit 
	   and then  move mouse into main ez_fit window to get the
           IDL prompt
	5. Load 'test.pro' into ez_fit by 
		IDL>  .run test1
		IDL>  retall
		IDL>  xmanager
	6. Move mouse into SVDFIT Setup dialog window to update fields
		Function_Name:  myfunct2
		NTERMS : 7
          	Press 'Accept' button


2. FUNCT2 - Nonlinear Function Example [DIR]

The following IDL program 'test2.pro' gives an example of defining a private fit program. It consists of two routines: FUNCT2 and GET_CURVEFIT_FUNCT_PVT.

The private routine FUNCT2 specifies the non-linear function to be fit must accept values of X, A, and returns F, PDER. Where X(NPOINT) is the vector of input independent variable X, A(NTERMS) is the vector of fitting coefficients, F(NPOINT) returns the dependent function values at X, and PDER(NPOINT,NTERMS) return array of corresponding derivatives of F.

The routine GET_CURVEFIT_FUNCT_PVT is required for printing out fit function on plot and tabulated text output windows.

a. test2.pro [DIR]

PRO     FUNCT2,X,A,F,PDER
;       F = A(0)*EXP(-Z^2/2) + A(3) 
;       Z = (X-A(1))/A(2)
;
        ON_ERROR,2                        ;Return to caller if an error occurs
        NTERMS = 4
        if n_elements(A) ne NTERMS then begin
                res = dialog_message('Number of fitting terms must be'+ $
                string(NTERMS),/Error)
                return
        end 
        if A[2] ne 0.0 then Z = (X-A[1])/A[2] $ ;GET Z
        else z= 10.
        EZ = EXP(-Z^2/2.)*(ABS(Z) LE 7.)                ;IGNORE SMALL TERMS
        F = A[0]*EZ + A[3]              ;FUNCTIONS.
        IF N_PARAMS(0) LT 3 THEN RETURN ;NEED PARTIAL?
;
        PDER = FLTARR(N_ELEMENTS(X),4)                  ;init ARRAY.
        PDER[0,0] = EZ          ;COMPUTE PARTIALS
        if A[2] ne 0. then PDER[0,1] = A[0] * EZ * Z/A[2]
        PDER[0,2] = PDER[*,1] * Z
        PDER[*,3] = 1.
        RETURN
END

PRO get_curvefit_funct_pvt,fname,expres
ffname = strlowcase(fname)
if  ffname eq 'funct2' then begin
        expres='F(X) = A0 * exp( -Z^2 / 2 ) + A3 ,'
        expres=[expres,' Z = (X - A1) / A2' ]
        return
        end

END

b. Access CURVEFIT [DIR]
Then a user can load the program into IDL after loading ez_fit this will add the fit function 'funct2' into ez_fit. The steps to access this new fitting method are given below:

In IDL ez_fit main window, select the 
        
        1. Load data into ez_fit
        2. Select the curve to be fit
        3. Pops up the CURVEFIT Setup dialog by select:  Curve Fit->CURVEFIT    
	4. Use Cntl^C and carriage return keys to interrupt ez_fit 
	   and then  move mouse into main ez_fit window to get the
           IDL prompt
        5. Load 'test2.pro' into ez_fit by 
                IDL>  .run test2
                IDL>  retall
                IDL>  xmanager
        6. Move mouse into CURVEFIT Setup dialog window to update fields
                Procedure_Name:  funct2
                Initial Fitting Coefficients (comma separated)
			2.,1.,1.,1.
                Press 'Accept' button

	   Note:
		 Initial Fitting Coefficients are required only
		 for privatly defined routine. 
		 The number of coefficient entered must be the same as the
		 terms defined in funct2, they must be separated by
		 comma. 
		 



Tim Mooney
mooney@aps.anl.gov.
Last modified 12/19/98