NAME

fhyper -- Fit a hyperbolic function.

USAGE

fhyper infile

DESCRIPTION

This task fits a hyperbolic function of the form

(Y/A)**2 - (X/B)**2 = 1 

to two-column data in an ordinary text file. If the input to this task is the output file from the fradius task, then Y has units of radius (pixels), and X is the position of the refoc mirror. In addition to the values A & B, there are zero-point values for X and Y. For X, the zero point is the location of the focus. For Y, the zero point is a baseline offset, and the default is to leave the baseline fixed at zero because of possible coupling with A.

A plot of the input data and the fitted curve can be generated. A curve can be plotted without being fitted. If all parameters are held fixed, the curve defined by the parameters given in the par file will be plotted.

The downhill simplex method is used to fit the curve. The fitting is done by calling the Numerical Recipes AMOEBA subroutine (renamed "FAMOEB" because of a change in the calling sequence). If there are NPAR variable parameters, a simplex is a set of NPAR+1 points with connecting lines in NPAR-dimensional parameter space. Initially one vertex of the simplex is at the current best estimate of the parameters, and each of the other vertices is offset from the first vertex along only one axis, a different axis for each vertex. The fit is done by assigning initial values to the simplex and calling FAMOEB to modify the simplex (move the vertices) to find a minimum. The values at all vertices are then averaged to find a (presumably better) estimate of the parameters. The simplex is reinitialized using these parameter values, and FAMOEB is called again in case the minimum that was found on the first call was spurious.

If you would like to modify the function to be fit or write code for another function, here are the files and routines that depend on the function.

fhyper.x:
	procedure fhyper  This is the task itself.
	procedure f_3h_save  This saves the parameter values (that were
		determined by the fit) in the task par file.

fcsinit.x:
	procedure f_3h_init  This gets the initial values for the
		parameters, either from the par file or from the data.
	procedure f_3h_range  This gets an estimate of the range of
		values for each parameter.  The range is not intended
		to be the maximum possible range but rather a guess as to
		a reasonable range.

fcsfunk.x:
	real procedure fcs_hyper  This evaluates the hyperbola at one
		point.  It is called from f_hyp_funk and also by the
		plotting routine.
	real procedure f_hyp_funk  This is the function to be minimized.

PARAMETERS

infile = "" [string]

Name of input ASCII file. This file contains two columns, the independent variable values and the dependent variable values.

(init = "data") [string, Allowed values: data | par]

The initial values for the parameters can be taken either from the par file or estimated from the data. The values of parameters that are to be held fixed are always gotten from the par file.

(fitlocn = yes) [boolean]

Fit for the location of focus?

Each parameter may either be held fixed at the value given in the par file or allowed to vary in order to find the best-fitting curve.

(locn = 0.) [real]

Initial estimate of location of focus. This parameter is the X-coordinate of the center of symmetry about a vertical line. The corresponding parameter for the Y-coordinate is called "BASELINE." If the location is to be held fixed, the value is taken from this parameter. If the location is to be allowed to vary, the initial estimate will either be gotten from the data (if init="data") or from this parameter (if init="par"). The first guess from the data is simply the X location of the smallest Y value.

(fityscale = yes) [boolean]

Fit for the Y-scale?

(yscale = 1.) [real]

Initial estimate of y scale, A in (Y/A)**2 - (X/B)**2 = 1. The first guess from the data is the smallest Y value.

(fitxscale = yes) [boolean]

Fit for X-scale?

(xscale = 50.) [real]

Initial estimate of X scale, B in (Y/A)**2 - (X/B)**2 = 1. The first guess from the data is obtained by dividing the current value for A (yscale) by an estimate of the slope of the data for large Y.

(fitbase = no) [boolean]

Fit for the baseline? (Note that the default is "no".)

(baseline = 0.) [real]

Initial estimate of baseline. This is an offset in the Y direction.

(option = "lsq") [string, Allowed values: lsq | minsum]

The fit may be performed by minimizing the sum of squared deviations (option="lsq") between the data and the curve or by minimizing the sum of the absolute values of the deviations (option="minsum").

(ftol = 1.e-5) [real]

Fractional error allowed. The fit is terminated either when the maximum allowed number of iterations (currently 500) is reached or when the fractional error is less than ftol. The fit is performed by minimizing a function, e.g., sum of squared deviations. The function is evaluated at the vertices of a simplex, and the fractional tolerance is:

ABS (YHIGH - YLOW) / ((ABS (YHIGH) + ABS (YLOW)) / 2.)

where YHIGH and YLOW are the maximum and minimum values.

(logfile = "") [string]

Name of output file for info about fit. A file will be created with this name (if it's not null) and information will be written to it giving some details about the fit. The values of the variable parameters (but not the fixed parameters) and the value of the function to be minimized will be written to the file for each vertex of the simplex. These are written before each of the two calls to the amoeba routine, i.e., for the initial estimates of the parameters and also after a minimum has been found. In each case the first line gives the parameter values (and function value) for the vertex containing the current estimates of the parameters, while the other lines give values for the other vertices, which are the same except for one parameter at each vertex. The number of iterations for each call to the amoeba routine is printed. A line is also printed giving the final values of the variable parameters and the value of the function to be minimized.

If the data and fitted curve are to be plotted (see the description of the device parameter), the screen will be cleared after writing to the log file, so if logfile="STDOUT" the information will be lost.

(title) [string]

A title for the plot may be given with this parameter.

(xlabel = "refoc position") [string]

This is used as a label for the X axis.

(ylabel = "radius") [string]

This is used as a label for the Y axis.

(xmin -5.) [real]

The plot range in X may be specified with xmin and xmax. If either or both is INDEF then the plot limits will be determined by the input data.

(xmax = 235.) [real]

See xmin.

(device = "stdgraph") [string]

Name of graphics device. This parameter may be set to "stdgraph" or "stdplot" to plot the input data and the fitted curve. If this value is null (i.e., device="") no plot will be generated. If all the flags (i.e., fitlocn, fityscale, fitxscale, fitbase) are set to "no", a plot can still be made which will show the curve calculated with the parameters (locn, yscale, xscale, baseline) specified in the par file.

EXAMPLES

BUGS

REFERENCES

This task was written by Phil Hodge. A slightly modified version of the Numerical Recipes AMOEBA subroutine is used to do the fit. Numerical Recipes was written by W.H. Press, B.P. Flannery, S.A. Teukolsky, and W.T. Vetterling.

SEE ALSO

fgauss