NFit

Abstract:

NFit is the Nirvana Graphical User Interface to MINUIT. 1-D histograms or curves can be interactively fitted, the answer of the fit is given in both graphical form (a curve superposed/compared to data) and in tabular form (Table of fit parameters). These fitting procedures are highly interactive, giving important feedback and checks to the user prior to finding the final solution.
This software was produced by the Nirvana project of the Physics Analysis Tools Group. The Nirvana project goal is to provide visualization tools for Fermilab physicists that make effective use of computer workstations and Graphical User Interfaces.
Copyright (c) 1994, 1995 Universities Research Association, Inc. All rights reserved.

This material resulted from work developed under a Government Contract and is subject to the following license: The Government retains a paid-up, nonexclusive irrevocable worldwide license to reproduce, prepare derivative works, perform publicly and display publicly by or for the Government, including the right to distribute to other Government contractors. Neither the United States not the United States Department of Energy, nor any of their employees, makes any warranty, express or implied, or assumes any legal liability or responsibility for the accuracy, completeness, or usefulness of any information apparatus, product, or process disclosed, or represents that its use would infringe privately owned rights.

Contents
Introduction
Using NFit
Release Notes
About this document ...

Introduction

Fitting data to a particular mathematical model is a task essential to performing an analysis in High Energy Physics. Numerous packages have already been written (PAW, PAW++, MNn Fit), demonstrating the interest in the matter. As with these existing packages, NFit is a tool based on the powerful MINUIT package from the CERN library. NFit, a Graphical User Interface (GUI) to MINUIT, has been designed to run on UNIX workstations, and takes advantage of the MOTIF windowing system. Ease of use, flexibility, access to all pertinent information and above all greater interaction between the user and the computer are the goals of NFit. In NFit, the minimization procedures are highly interactive :

The user is able to select and see the input data. Data files are either (i) flat ASCII list of data points, (ii) HistoScope file format (iii) HBOOK file format, or (iv) native NFit file format.
The user has various options to define the function used to fit the data, ranging from simple polynomial expressions, to his own algorithm, coded in FORTRAN or C.
The user is able to interactively change the function, as well as the parameter values, and immediately see the effects of the change on the minimization.
As the fit proceeds, updates of the fitted function compared to the fixed data can be viewed, as well as the evolution of the parameters and the corresponding (or LogLikelihood).
The minimization procedure can be stopped and restarted at anytime, should the user be unhappy with the direction MINUIT takes.
Although only one fit can be performed at a time in a given NFit session, multiple fits can be opened simultaneously, for comparative studies and/or references.
A complete history of the fitting procedure is kept, and the user can go back and look at what he or MINUIT did as a function of iteration number.
The user can save the result of his work in an NFit file.
An encapsulated Postscript file containing the title of the window, the plot with the fit superimposed and, optionally, the numerical result of the fit in tabular form can easily be generated anytime after a successful fit.
Upon demand, NFit will generate a FORTRAN program that performs the same minimization without a GUI. This code can easily be integrated into a larger program, rendering complex Application Interfaces to MINUIT obsolete.
A complete online Help facility is available.

Minuit is conceived as a tool to find the minimum value of a multi-parameter function and analyze the shape of the function around the minimum. The principal application is foreseen for statistical analysis, working on chisquare or Loglikelihood function, to compute the best-fit parameter values and uncertainties, including correlations between parameters. It is especially suited to handle difficult problems, including those which may require guidance in order to find the correct solution.

For simple and straightforward fits, no specific knowledge on how MINUIT minimizes the chi-square is needed, as the simple step by step approach described below will work. However, for more complicated problems where default options are not optimum, the user should consult the MINUIT manual for additional details. Much of the MINUIT terminology has been respected throughout the NFit package, its online help facility, and this document.

Using NFit

Getting Started

In this subsection, a straightforward step by step approach to using NFit is described. As for all other X applications, NFit requires setting the environmental variable DISPLAY

% setenv DISPLAY devicename:()

For example, setenv DISPLAY pspxt5.fnal.gov:0 tells the X software on a Unix host to use your X display pspxt5.fnal.gov. Next, set up the product NFit by typing

% setup nfit

Then,

% nfit

A display comparable to figure

should appear on your screen. Initially, blank input data appears in the right hand corner of this panel. Your first task is to replace it with data you intend to fit. The "File" menu gives the choice between an NFit data file, Ascii tabular data file, HistoScope files, or HBOOK files (see the subsection on files for details). After selecting the histogram or set of points you want to fit, the input data is plotted in the topright corner. You can then zoom or pan by dragging the axis (for details, see HistoScope documentation and online help).

Your next task is to choose the mathematical model, implemented as either an Expression, or a FORTRAN77 or C callable Function. The easiest option is to select a predefined expression from the lower central pull down menu (Paste/Clear Expression), for instance a Gaussian or a Polynomial.

Before actually fitting the data, it is a good idea to check the expression and initial values by first looking at the parameter table (first item in "Fitting" menu), and pressing the "Plot Initial" Button. The fitted curve, or parts of it, should appear on top of the data. If the initial values are not sensible, use the "Tune Initial Value" menu item in the "Fitting" pulldown menu, and play with the suspicious parameter(s) until a decent curve appears on top of the data. Once the initial values are correctly set, press the fit button, and observe while MINUIT will search to minimize the (or the LogLikelihood).

Once the minimization completes, the detailed solution is available under the "Show Solution" option in the "Show" menu. NFit keeps a history of the fit: at each iteration, the values of the parameters and the corresponding are kept in memory and can be redisplayed using the history slider on the Main panel, or shown graphically using Show Evolution in the "Show" menu. Further studies can be undertaken from the "Fitting" menu, such as accurate error estimation, scanning the as a function of a specific parameter or contouring the solution.

It is prudent to save ("File" menu) the result of a particular fit, so that you will not have to re-select the input data, type the expression or initialize the parameters. You can also generate FORTRAN code that will perform the corresponding fit.

The Input data files

Four different input file formats can be used to import the data to be fitted in NFit:

Ascii Data File, "nPlot" format style. NPlot, or NFit, reads simple tab or space delimited data with each column representing a variable. Comments can be included in the file if they begin with a ``#'' in column 1. If a line beginning with > appears in the file, its contents will be used as column headings for the data. The column headings should be separated by spaces and or tabs. To include spaces in a column heading, enclose it in quotes. For example:
Two columns of data must be present. The third column is reserved for the error. If errors are unknown, NFit will give you the choice between setting fixed or proportional errors.
HistoScope File Format. Such a file has to be generated by a HistoScope v2.0 or v3.0 client application, through the utility routine hs_save_file or hs_save_file_items. See the HistoScope User's Guide V3 for details.
HBOOK File Format. Such a file has to be generated by a HBOOK v4 application. HBOOK is a CERN product. See the HBOOK v4.20 manual for details. Note that we assume ZEBRA direct access files ("RZ" files) have been written using the default block length (1024).
NFit File. An NFit file is a binary file generated by this application. The format is compatible with the HistoScope format. This binary file can be safely copied across systems via ftp, and will be readable by NFit or HistoScope on other Unix platforms.

The Expression or User function

NFit has three distinct modes of operation to define and use the mathematical model that fits the data:

Predefined Expressions: Simple and standard functions, such as Gaussian and polynomials are available in the pull down menu on the main NFit panel labeled ``Paste/Clear Expressions''. Upon selecting such a simple expression, the user not only defines the function used in the fit, but also sets the initial values and step sizes for all the parameters. This expression appears in the text widget located at the bottom of the Main panel (e.g. Expression). More than one such expression can be used in a single fit: pasting a second expression to an existing one is interpreted as adding two sub-expressions.
User-defined Expressions: You can also directly type your favorite formula in this text widget. The syntax for this expression is similar to the FORTRAN syntax, but evidently more limited. If this expression becomes too complicated or must implement conditional algorithms, use FORTRAN or C to code your routine, and use the Compiled Function mechanism to implement it in your fit (see next item). The syntax used for this expression is obviously the same as for a predefined expression. Thus, one can always start with a predefined expression, and modify the algebra as appropriate.
For example, selecting a Gaussian gives the following expression:
(a/(var*sqrt(2*pi))) * e**(-((X-mean)**2)/(2*var**2))

where a, var, and mean are the parameters we will fit for. pi and e are predefined constants.
Similarly, a "scaled polynomial" (using renormalized variables) gives :

u = (X - 7.5E-01)/1.5
coeff0 * ( 1.0 + coeff1*u + coeff2*u**2 )
where 7.5 and 1.5 are numerical constants, u is a temporary variable, and coeff* are the parameters to be fitted for. The last line is the final subexpression, its value is returned at the Expression value.
The practical rules to code such an NFit Expression are as follows:
- Numerical constants are allowed, type in integer or floating point format.
- Variables: User variables used to write large expressions in a cleaner fashion are supported and recommended. Some restrictions on variable names apply: the variable X is reserved, and matches the abscissa on the graph. In future versions, the Y variable will be reserved as well to fit 2D histograms. Others also reserved include: (i) pi = 3.14159.., (ii) e = 2.71828.. , (iii) gamma is the Euler number = 0.5772156.. and (iv) deg is the degree to radian conversion factor = 57.2957.. User variables used to write large expressions in a cleaner fashion are supported and recommended.
- Operations: All arithmetic operations are allowed, the syntax is FORTRAN77 (+, -, *, **, /). Built in functions are:
  sin, cos, atan, log, log10, exp, sqrt, int and abs.
- Flow control: None: The final expression is always estimated based on sub-expressions and variables in all instances.
FORTRAN77 or C Compiled Functions. The ``Compiled Function'' mechanisms allows you to use complex expressions or algorithms to return the fitted function values. This user function may be coded in C or FORTRAN77. To implement this scheme, you will have to code two subroutines, one called at initialization time, the other is called each time NFit needs a returned value from the subroutine.
A brief example of these two routines will serve as a tutorial (file userFCode.f in the $NFIT_DIR/examples directory):
```
        subroutine nf_initialize(ifcn, numParam)
        implicit none
        integer ifcn, numParam
          ifcn = 1
          numParam = 2
        return 
        end

        subroutine nf_calculate(x, y, param, yp)
        implicit none
        double precision x, y, param(*), yp 
        double precision xa 
           xa = (x - 0.75)/2. 
           yp = param(1) * (1. + param(2) * xa **3)
        return 
         end   
```
The first routine ``nf_initialize'' simply declares to NFit (i) the type of minimization that will be done; always set to 1 for this version (2D histogram fitting is not yet supported) and (ii) the number of parameters used in the model. The second routine ``nf_calculate'' returns the value "yp" for a given "x" coordinate, and the parameter array. The variable "y" is not used, and is reserved for future versions of NFit.
A synopsis for these two routines is:
```
       nf_initialize(ifcn, numParam) 

c   Output Parameters : 
c	
c       Ifcn : Integer. The type of function.
c              Always 1 for this release.
c	       
c       numParam : Integer.
c                  The number of declared MINUIT
c                  parameters used in NFit, mostly for self
c                  consistency.
c
       nf_calculate(x, y, param, yp)

c      Input Parameters :
c
c      x : Double Precision. The X coordinate where to
c          function needs to estimated.
c      y : Double precision. The Y coordinate, unused for
c          1D plots.
c      Param: Double Precision array.
c             The parameter values set by NFit/MINUIT.
c
c      Output Parameters : 
c
c      yp : Double Precision
c           The returned value of the Function.
c
```
Any user function that will be used with NFit can be tested independently of NFit by making a dummy MAIN that calls these two routines. Then the code can be incorporated into NFit. The communication between NFit and the user process is via a UNIX "pipe" between the NFit process and a "calculate" process forked by NFit. This subprocess runs a dedicated executable that must be built. A Makefile is supplied for each UNIX system. Use the following shell commands as a guide:
```
       %setup nfit
       %cp -i $NFIT_DIR/examples/* . 
       %make userFCode
```
The makefile links the user written subroutines with the supplied userFunc.o main program, which is a pre-compiled module that feeds data to the user-controlled userFCode module. To use this compiled function with NFit, run NFit and define the corresponding set of parameters using the Parameters Panel. Then, on the main NFit Panel, press the "Compiled Function" button and fill in the "Exec Name.." text string with the executable name, "userFunc" in our simple example. Then press the "Plot Initial" button to get a first graphical feedback. If o.k., the system is ready for a fit. If not, make appropriate changes to the parameters and/or changes to the code. Each time a new version of the "userFunc" executable gets rebuilt, you must press the "Re-Load" button before continuing with NFit.

About Setting and tuning the Parameters Values

A MINUIT parameter is a quantity used in the mathematical model describing the input data. Such a quantity can be (i) Freely Variable: no limits are imposed during the search for a minimum. (ii) Variable within limits: allowed to vary only between limits specified by the user. (iii) Fixed: same as a variable parameter, but the user decides to freeze that parameter at its current "Initial" value. (iv) Constant: taking only one value specified by the user. Implemented in NFit as a Fixed parameter. Please refrain from using parameters as constants, since they unnecessarily overburden the application. (v) Undefined. NFit/MINUIT allows for 100 Parameters defined at any given time, 50 of them variables. However, most problems do not required such a large set. The Parameter Settings panel, accessible through the ``Fitting'' pull down menu from the Main panel, works in conjunction with the main NFit panel, so you can set or verify initial conditions prior to starting a minimization. If Expressions are used, the parameter names appearing on the Parameter panel must match those used in the expression. Initial values and step size are mandatory fields (if a step size is set to 0., MINUIT will interpret this as a fixed parameter). In some difficult cases, it might be necessary to place limits on these parameters. Note that, if you define one of these limits (upper or lower), you'll have to set the other one as well, for algorithmic reasons within MINUIT.

This Parameter Panel is shown in figure . The parameter table can not be directly edited, however, selecting a line allows you to use the text fields below. The set of four buttons on the top left allows you to paste the information into a buffer, clear, cut or copy the corresponding line. To make a change effective, press the change button, or press the Enter or Return key on your keyboard. The "Value" text field does not accept input, as it is the result of a MINUIT minimization sequence. After a minimization (successful or not), the current value of a given parameter appearing in the "Value" text field can be transferred to the "Init. Value" field by pressing the arrow button located in between these two fields.

At the beginning of an NFit session, in order to understand and verify the algebra used in the expression or function, it might be necessary to play with different parameter settings, and have immediate visual feedback on the Main Panel. The ``Tuning Parameter'' panel, shown also in figure can be used for that purpose.

Fitting

For simple problems, just pressing the ``Fit'' button on the Main panel does it. MINUIT starts iterating, and the display gets periodically updated (the frequency of these updates is determined by an adjustable clock that can be set from the ``Preference'' pull down menu). After MINUIT converges to a solution, the displays (the fitted curve, as well as the parameter values or other ancillary windows) are refreshed automatically, and the complete information about that solution is available from the ``Show solution'' option in the ``Show/Print'' pull down menu. A non-converging fit can be stopped anytime by pressing the stop button. After necessary modification of the initial value of the suspected parameters (or other factor in the minimization problem), a new fit can be attempted by pressing again the ``Fit'' button.

The user is able to select the range of data to be fitted by either moving the margin bar at the bottom of the plot, or typing a specific range in the fields located just below the margin widget.

For more complicated fits, the user might want to consider changing some of the default algorithm parameters and switches used in MINUIT, such as the maximum number of iterations, the tolerance, the strategy switch, or the minimization method. For details, see the MINUIT reference manual.

Graphical Representation of the Solution

The plot located on the right top corner of the Main panel is managed through a HistoScope Widget, either the 1D histogram or the X-Y Widget. The user can resize the plot by rescaling the panel or moving the separator bar. Direct interaction, such as zoom, can occur by dragging the axis. For details, see the HistoScope manual. In addition, explicit ranges and scaling options (logarithm vs linear) are also available under the ``Preferences'' menu. If the input data format is a 1D histogram, three different representations of the data vs fit are available (shown in figure ): (i) the fitted curve superimposed on the histogram, (ii) the same curve superimposed on the bin contents represented by solid circles and their respective errors and (iii) the curve value at the bin center subtracted from the bin contents. If the input data does not originate from a 1D histogram, only the latter two are available. These options are available under the heading ``Data points vs Histograms'' in the ``Preferences'' menu.

The Evolution and Correlation Window

Difficult minimizations (or lengthy, if not suspicious ones) can be easily detected by observing the evolution of the fitted curve on top of the data. Finding out why the minimization is problematic may require access to further information. The ``Evolution'' panel, available under the ``Show Evolution'' menu item from the ``Show'' pull down menu, allows the user to study the path in parameter space that MINUIT took to converge to a single minimum, or get hopelessly lost. The most obvious handle is the evolution of the (or LogLikelihood) versus iteration number. The user can plot this versus any parameter variable, to detect the parameters that drive the function values and therefore the minimization outcome. Also interesting are possible correlations among parameters. The implementation of this ``Evolution'' panel is based on the HistoScope NTuple system: for each iteration, that is, each time MINUIT calls the user function, possibly changing one or more parameter values, the values of all parameters and the value of the are stored in a HistoScope NTuple data structure, that can be interactively viewed from the ``Evolution'' panel. For details on how to use the different graphical widget used from this panel (showed in figure ), see the HistoScope manual.

Advanced Features

A systematic study of a minimization can be done by scanning systematically the around the extremum, or a suspicious region in parameter space. This is available under the ``Scanning'' heading in the ``Fitting'' pull down menu. After setting up the scan (i.e. selecting the parameter, the range and the number of steps), pressing the ``Scan'' button initiates a loop that calls the user function or the Expression without using MINUIT. The result can be studied from the Evolution panel.

In addition, MINUIT has the following capabilities to characterized a successful minimization:

``Contouring'' provides a graphical representation of the correlations and the corresponding covariance matrix between two parameters. MINUIT finds the ``Iso-chisquare'' curve in the a 2 dimensional plane. For details see the MINUIT manual, "Contour" command, or the help bullet on the "Contour" panel.
Accurate Error calculation: Once an extremum has been found, the MINUIT "MINOS" command computes the errors on the parameters taking into account the correlations among parameters and the non-linearities in the problem. These errors are generally asymmetric. For details, see the MINUIT manual on errors estimations.
``Improve'' instructs MINUIT to make further attempts to find a better extremum. It rarely works, but does not cost much to try.

For additional functional details, see the online help bullet on ``fitting''.

Saving, Restoring and Performing Similar Fits

Once the user reaches a conclusion in his analysis, he can save the fit into an NFit file (``Save'' or ``Save as...'' in the ``File'' pull down menu. Printing is available, he can also paste the ``Show Solution'' in his electronic LogBook. The fit can be easily restored from the NFit file, and can be used as a starting point for further analysis, by either changing the user function or the expression, or replacing the input data. The former modification is straightforward, by just interacting with the bottom part of the Main panel, and adjusting parameters accordingly in the ``Parameter Settings'' panel. The latter action can be done by opening a new input data file from the ``File'' menu. NFit will then replace the obsolete data with the new one, and a new fit can be immediately initiated without further actions. If a large number of similar fits must be performed on an ensemble of input data sets, and none of these fit are likely to be controversial, one clearly no longer needs a GUI to perform each fit individually, but would rather write a program that does it automatically. This task can be greatly facilitated by generating a stand-alone FORTRAN program that performs the current fit, and modifying this code so that it can be inserted in a larger analysis framework. This feature is available under the option ``Generate Fortran Code'' under the ``File'' menu.

Release Notes

First, let us mention that the original design of NFit called for having the capability to fit and represent 2D Histograms. The internals of NFit currently have appropriate hooks for this extension, the graphical aspect of the joint representation of the fit and the input data is a little bit more difficult and has been postponed until further releases. NFit has been developed under IRIX 5.2, and is available under IBM AIX 3.2, OSF 1 V3.2 and SUN SOLARIS. There is no plan to support NFit under Open VMS. Following limitations are :

Handling of user processes using the "Compile Function" feature: These processes are automatically cleaned up by NFit as the user reloads a function, closes windows, or exits NFit. If you terminate NFit by any other mean, the user obviously has to kill the idle sub-processes. Note obsolete processes may still appear under a ``ps'' command, while NFit is currently running. They should go away from the system when NFit terminates and when the user logs off.
In the Main panel, the Logarithm scale option will fail if any of the data points overlap negative values within their errors, despite the fact that the user may have set the visible range to mask negative values.
The Contour plots could be improved. Currently, only the points returned by MINUIT through the MNCONTR algorithm are used to draw the continuous lines. No spline fits are used to smooth out these contours. Also, the printed line style could be different from what is on the screen.
Upon reading an NFit file, if the file has no fit stored, the parameter list on the upper left corner of the main NFit panel is not updated. Use the Parameter Panel to check the parameters.
The Improve function, in the NFit/MINUIT interface, has the following deficiency: if MINUIT fails to find a different minimum (no improvement can be made), MINUIT will not give us back the original solution, and will be confused unless we do the original fit again.