NAME

inlfit -- The interactive non-linear least squares fitting package

SYNOPSIS

The INLFIT package is a set of procedures, callable from any IRAF task, for interactively fitting an arbitrary function of n independent variables using non-linear least squares techniques. The calling task must supply the function to be fit and its derivatives, initial values for various convergence and bad data rejection parameters, the data to be fit, and weights for all the data points. The INLFIT package is layered on the NLFIT package which does the actual fitting.

DESCRIPTION

INLFIT fits an n-dimensional function to a set of data points iterating until the reduced chi-squared changes by less than tolerance percent between successive iterations, or until machine precision is reached, or until the maximum number of iterations maxiter is reached. If the maximum number of iterations is reached before convergence a status flag is set.

After computing an initial fit, INLFIT presents the user with a plot of the fit and activates the graphics cursor. At this point the user may examine and/or interact with the fit by, for example, reprogramming the default graph keys, editing the default convergence or bad data rejection parameters, deleting and undeleting points, altering which parameters in the fitting function are actually to be fit and which are to be held constant, and refitting the data.

If nreject is greater than zero the RMS of the residuals is computed and points whose residuals are less than low_reject * RMS or greater than high_reject * RMS value are excluded from the fit. Points within a distance grow of a rejected point are also excluded from the fit. The function is then refit without the rejected points. The rejection algorithm is executed until the number of rejection iterations reaches nreject or no more points are rejected.

CURSOR COMMANDS

The following interactive cursor keystroke commands are available from with the INLFIT package.

?

The terminal is cleared and a menu of cursor keystroke and colon commands is printed.

c

The id, coordinates of the data point nearest the cursor, along with the function value, the fitted value and the residual, are printed on the status line.

d

The data point nearest the cursor and not previously deleted is marked with an X. It will not be used in further fits until it is undeleted.

f

The function is fit to the data and the fit is graphed using the default plot type.

g

Redefine the graph keys "h-l" from their defaults. A prompt is issued for the graph key to be redefined. Another prompt is issued for the data to be plotted at which point the user must enter the x and y axis data to plot, delimited by a comma. The data types are the following (they can be abbreviated to up to three characters).

    function    Dependent variable or function
    fit         Fitted value
    residuals   Residuals (function - fit)
    ratio       Ratio (function / fit)
    nonlinear   Nonlinear component
    identifier  Independent variable named "identifier" (if defined)
    var n       Independent variable number "n"
    user n      User defined plot equation "n"  (if defined)

The application program can define independent variable names and user plot functions, aside from the standard options provided. If variable names are supplied, the user can reference them by their names. Otherwise they can be always referenced by "var n", where "n" is the variable number (the user has to know the variable order in this case). The ":variables" command will list the currently defined variables by name and number. The application program may define any number of plot equations aside from the defaults provided. In this case the user may reference them by "user n", where "n" is the plot function number (the user must know the equation order in this case).

h, i, j, k, l

By default each key produces a different graph. The graphs are described by the data which is graphed along each axis as defined above. The default graph keys, which may be redefined by the application program or interactively by using the 'g' key, are the following.

        h       function, fit
        i       function, residuals
        j       function, ratio
        k       var 1, function
        l       user 1, user 2 (default)

The initial graph key, if not redefined by the application program is 'h'.

o

Overplot the next fit provided the graph format has not changed.

q

Exit from the interactive curve fitting package.

r

Redraw the current graph.

t

Toggle fit overploting on and off. If this option is on the data and fitted values are overplotted. Otherwise only data points are plotted. The fitted values are marked using boxes.

u

Undelete the data point nearest the cursor which has been previously deleted. This option does not work over points marked as deleted by the application program before calling inlfit.

w [key]

Set the graph window or data range along each axis to be graphed.. This is a gtools option which prints the prompt "window:". The available cursor keystroke commands are printed with '?' and on-line help is available by typing "help gtools".

I

Interrupt the task immediately without saving the current fit.

Colon commands are used to show or set the values of parameters. The application program calling inlfit can add more commands. Parameter names can be abbreviated. The following commands are supported.

:show [file]

Show the current values of the fitting parameters high_reject, low_reject, niterate, grow, tol, itmax. The default output device is the terminal (STDOUT) and the screen is cleared before the information is output. If a file is specified then the information is appended to the named file.

:variables [file]

List the currently loaded variables. The number, id, minimum value and maximum value of each variable is printed. The default output device is the terminal (STDOUT) and the screen is cleared before the information is output. If a file is specified then the information is appended to the named file.

:data [file]

List the raw data. The value of each standard catalog and observations catalog variable for each data point is printed. The default output device is the terminal (STDOUT) and the screen is cleared before the information is output. If a file is specified then the information is appended to the named file.

:errors [file]

Show the error analysis of the current fit. The number of iterations, total number of points, the number of rejected and deleted points, the standard deviation, the reduced chi, the average error (always = 1.0 if weight=1.0, otherwise = 1.0 / <weight>), the average scatter (always 0.0 if no weights scatter term is fit), the reduce chi, and the rms are printed on the screen. The fitted parameters and their errors are also printed. The default output is the terminal (STDOUT) and the screen is cleared before the information is output. If a file is specified then the information is appended to the named file.

:results [file]

List the results of the current fit. The function value, the fitted value, the residual, and the weight are printed for each data point. The default output device is the terminal (STDOUT) and the screen is cleared before the information is output. If a file is specified then the information is appended to the named file.

:vshow [file]

A verbose version of ":show" which is equivalent to a ":show" plus a ":errors" plus a ":results". The default output device is the terminal (STDOUT) and the screen is cleared before the information is output. If a file is specified then the information is appended to the named file.

:page file

Page through the named file.

:tolerance [value]

Show or set the value of the fitting tolerance. Tolerance is the maximum fraction by which the reduced chi-squared can change from one iteration to the next for the fit to meet the convergence criteria.

:maxiter [value]

Show or set the maximum number of fitting iterations.

:nreject [value]

Show or set the maximum number of rejection iterations. A value of zero means that automatic bad data rejection is turned off.

:low_reject [value], :high_reject [value]

Show or set the values of the bad data rejection limits. If both low_reject and high_reject are zero then automatic bad data rejection is turned off. If either of the high or low rejection limits are greater than zero, and nreject is greater than zero, the rms of the initial fit is computed. Points with residuals more than low_reject * rms below zero and high_reject * rms above zero are removed before the final fit. Rejected points are marked on the graphs with diamonds.

:grow [value]

Show or set the value of the rejection growing radius. Any points within this distance of a rejected point are also rejected.

:fit [parameter] [value]

Set the starting guess value for the named coefficient and allow the parameter value to change (converge) during the fit. If the value is not specified inlfit will use the last starting guess.

:const [parameter] [value]

Set the named parameter to be a constant with the specified value, i.e, its value won't change during the fit. If the value is not specified inlfit will use its last starting value.

:/help

Print help for the graph formatting options.

:.help

Print help for the general IRAF graphics options.

ALGORITHMS

INLFIT uses the standard Levenberg-Marquardt non-linear least squares algorithm to fit the data. Detailed descriptions of the algorithm can be found in the following two references.

1. Bevington, P.R., 1969, Data Reduction and Error Analysis for the
   Physical Sciences, Chapter 11, page 235.

2. Press, W.H. et al., 1986, Numerical Recipes: The Art of Scientific
   Computing, Chapter 14, page 523.

SEE ALSO

gtools