----- file created by xop_makedoc on: Tue Oct 26 11:09:34 2004

----- Documentation for /scisoft/XRayOptics/xop2.1/src_idl/wutil/fufifa.pro -----

                         ===============================
                         = Functional Fitting Facility =
                         ===============================

 FuFiFa 1.0Beta 1  December 2001


 Fufifa is an application to fit interactively a SEVERAL spectra to a FUNCTION.

 The goal is to provide with a point-and-click application for fitting many scans
 (usually from a SPEC file) with a user-defined function. The function can be built
 interactively using a set of components (straight line, polynomial, peaks
 (gaussian, lotentzian and pseudovoigt), steps (error function and arc tangent) or
 any user-define function). The application allows to fit a bunch of scans and to
 refine individually the individual fits. At the end, a plot of the fitted
 parameters and chi square versus the scan index can help to estimate the quality
 of the fits. 

 To operate with fufifa follow the following steps:

 1) Start the application by either: 

 i) Start xop and from the Xop->Tools->FuFiFa, This will create the fufifa window.
 ii) Enter "xop fufifa" at the unix prompt

 2) Import your data.
   Press the load button in the data sector (top right of the main window).
   You should select a file (SPEC type) which has been previously "cleaned".
   "Cleaned SPEC file" means that:
     i) you have removed the unwanted scans (only kept those used for fitting)
     ii) Each scans has ONLY two or three columns
         The first one is the abscissas X
         The second one is the ordinates Y
         The third (optional) one contains the errors of Y. The errors used for
            the fit are defined in the Fit->Preferences menu item. 
    You can use the EXODUS application (available in the XOP/XAID - XAFS toolbox)
         for this purpose (i.e., cleaning your SPEC file).

    Example: Using the file /scisoft/users/srio/Working/IDL/fufifa/cat3.spec I
             extracted (using EXODUS) the scans [82,83,92,93,111,112 and 113] I used 
             column 1 for X and column 16 for Y. The result was written to file 
             exodus.spec. This file was imported into fififa. Then I selected all
             scans (by pressing ctrl-click iteratively or doing multiple selection 
             with shift-click). The result of these operations are in Fig1.

 3) Define your model:
    Using the bottom sector of your fufifa window, I defined a function consisting 
    in a step function (errorF) and a lorentzian peak. For this I clicked "Add
    function" twice, one for each functional component. I did not adjust the input 
    parameters. 
    First I select my first scan (clicking on the list at the top right sector).
    Then I click in one of the small "G" buttons of the first line of the function. 
    That allows me to define, by clicking three points the initial guess parameters 
    for this function. I do the same thing for the second line, in order to define 
    my lorentzian peak. The result of this selection is in Fig2. You see your data
    in red, your model in green, your model components in blue and the residuals
    in cyan. The "F" buttons is used to fix (freeze) the respective parameter.

 4) First attempt to fit.

    If you press "**Fit**" you fit the function parameters to data. Then you can 
    press "propagate model" that copies the fitted values for the first scan to
    the rest of scans. 

    If you want to fit all spectra, just make a multiple selection and press the
    fit button. Then you can select individual scans to see better the results.
    Perhaps some scans are not well fitted. You can select by hand the guess
    parameters and fit again. 
    With these operations I obtained the plot in Fig3. 
    Not very good, I admit.

 5) Refinement of the fit. 
    You can preprocess the data using the "Data" menu items to:
      i) perform some operation (like normalization). Try it!
      ii) Cut unwanted data and redefine your interval. Use it to remove 
          points of the pre-edge and the incomplete last oscillation. 
      iii) Substract a linear background (not needed in this case). 

      After doing that, I added two more lorentzian peaks. I got results shown
      in Fig4. Much better!

 6) Visualizing and saving results:
     By pressing "Pars vs Scans" you can mahe plots of the parameters and the reduced 
     Chi square versus the scan number. This permits you to see if there are drastic 
     changes in some parameters.  In our case I see that scan 3 is the worst fitted. 

     The function used can be saved to a file using Model-Save to a file. This 
     file can be edited and reloaded. This option saves only the definition of the
     function and one parameter sets. It does not save the parameters fitted for all
     scans.
     In order to save the full information, you can use FuFiFa->Save as... It will
     create a SPEC-type file with all scans, error used, and models. In the scan
     header you can find the information on the fitted parameters and chi**2. The
     last scan (numbered 1000) contains the varuiation of the parameters versus
     the scan index. Of course, you can use Xplot to view this resulting file. 




 This is a beta version. Please send bugs and ideas to improve it to srio@esrf.fr





 TO DO
 =====

 - Allow MCI inputs
 - Load components of the function from an external (customizable) file
 - Access to boundaries of parameters for the fit?
 - Abort button (when fitting...)
 - Customize colors
 - Polinomial inputs from mouse
 - "Expert" mode (do not show information windows)
 - Integrate in xplot and in xop 
 - Interactive help



    
 srio@esrf.fr 7 December 2001
 Modified:
     2003/12/09 srio@esrf.fr Fix an incompatibility problem for IDL >=5.6


