NAME

fitband -- Fit a parameterized passband function to throughput data

USAGE

fitband input obsmode

DESCRIPTION

The task will fit a model passband to an observed throughput stored in a throughput table. You specify an expression containing free variables and initial values of these variables. The task then searches for values of those variables which minimize the squared difference between the model passband and the passband stored in the table. When the task finds the optimized solution, it writes the fitted values of the free variables back to the parameter file and prints the expression with the fitted values substituted for the free variables.

The name of the throughput table is given by the task parameter input. The model passband is specified by task parameter obsmode. If the model passband is too long to fit in the task parameter (63 characters max), the model passband can be placed in a file. The task parameter should then be set to the file name preceded by an "@". If the model passband is placed in a file, the expression may be split over more than one line wherever a blank is a legal character in the expression. The variables in the model passband are indicated by a dollar sign followed by a digit. The initial values of these variables are given by setting task parameters vone through vnine. All variables not used should be set to INDEF. The model passband expression should not skip variables, for example, if the model contains three free variables, they should be named $1, $2, and $3, not $1, $2, and $4. Upon exiting the task these vone through vnine will contain the final fitted values of the free variables.

The task can use two different methods to compute the least squares fit: the Levenberg Marquardt method and the downhill simplex method, sometimes called the amoeba method. The method used is selected by the task parameter slow. The downhill simplex method is used if slow is set to yes. The downhill simplex method is slow because it requires more iterations to converge to a solution. In compensation, however, it converges to the solution over a larger range of initial values than the Levenberg Marquardt method. However, the initial values of the free variables should always be as accurate as possible as neither method will converge to a solution from arbitrarily chosen initial values of the free variables. If the inital values are outside the range of convergence, the task may either compute a false solution or wander outside the range where the model expession is defined and terminate with an error.

PARAMETERS

input [file name]

The name of a throughput file. The throughput table can have the columns WAVELENGTH, THROUGHPUT, and ERROR. These columns contain the wavelength, throughput at that wavelength, and error in the measurement of throughput, respectively. The ERROR column is optional. If the throughput file is an ascii file, the first and second columns are the wavelength and throughput with an optional third column containing the error.

spectrum [string]

The model passband expression to be fitted to the throughput data. The free variables in the expression are indicated by a dollar sign followed by a digit. The model passband can be placed in a file, whose name is passed to this parameter, preceded by a "@" character, command. Newlines may be placed in the expression wherever blanks are legal in a synphot expression. The form of a synphot expression is discussed in detail in the help file for the calcband task.

(output = "none") [string]

The name of the output table containing the fitted passband. If output is set to "none" or left blank, no table will be produced. The output table contains the model passband expression evaluated with the fitted values of the free variables. The header of the table contains the names of the graph and component lookup tables and the model expression.

(ftol = 1.0e-5) [real, min = 0.0, max = INDEF]

The fractional tolerance convergence criterion. Iteration of the least square fit ceases when the scaled distance between two successive estimates of the free variables is less than this value. Each component of the scaled distance is scaled by dividing the difference between the two estimates by half their sum. Please note that the fit soulution may not converge to an arbitrarily small value, instead it may cycle between several values, so setting ftol to too small a value may result in failure of the solution to converge.

(maxiter = 500) [int, min = 1, max = INDEF]

The maximum number of iterations to be performed. If convergence is not achieved in this number of iterations, then the task stops execution with a warning message to that effect.

(nprint = 0) [int, min = 0, max = INDEF]

The number of iterations between diagnostic prints. If nprint is set to zero, there will be no diagnostic prints. Diagnostic prints are sent to STDERR and contain the number of the iteration, the chi squared value, and the model passband with the trial values of the free variables.

(slow = no) [bool]

Select which method to use to compute the least squares fit. If slow is set to no, it uses the Levenberg Marquardt method and if it is set to yes, it uses the downhill simplex method. The Levenberg Marquardt method computes an approximation to the matrix of second derivatives of the model in order to extrapolate to the point where the chi squared is a minimum. The downhill simplex method constructs a polygon of trial points and replaces the point with the highest chi squared with a new point with a lower chi squared, chosen by one of a set of strategies. The Levenberg Marquardt method usually converges on the solution in a fewer number of iterations, but the downhill simplex method will converge to the solution from a wider range of initial estimates of the free variables.

(equal = no) [bool]

Select whether to weight the data points when computing the chi squared. If equal is set to no and the input table contains the error column, data points will be weighted according to their errors. Points with indefinite, negative, or zero errors are not used in the fit. If equal is set to yes or the error column is zero, the data points will not be weighted.

(vone = INDEF) [real]

The value of the first free variable. Before running this task, this parameter should contain the initial estimate of the first free variable and on exit it will contain the final fitted value. If this variable is not in the equation, it should be set to INDEF.

(vtwo = INDEF) [real]

The value of the second free variable.

(vthree = INDEF) [real]

The value of the third free variable.

(vfour = INDEF) [real]

The value of the fourth free variable.

(vfive = INDEF) [real]

The value of the fifth free variable.

(vsix = INDEF) [real]

The value of the sixth free variable.

(vseven = INDEF) [real]

The value of the seventh free variable.

(veight = INDEF) [real]

The value of the eighth free variable.

(vnine = INDEF) [real]

The value of the ninth free variable.

EXAMPLES

Fit a gaussian to the f555w filter of the wfpc2. Equal is set to yes because the errors for the f555w filter are all zero.

sy> fitband crwfpc2comp$wfpc2_f555w_001.tab "gauss($1,$2)*$3" \
>>> out=fit555w.tab nprint=1 vone=5500 vtwo=500 vthree=1 equal+

irep = 1 chisq = 0.070178 exp = gauss(5500.,500.)*1.01
irep = 2 chisq = 0.038999 exp = gauss(5446.848,1049.767)*0.6572117
irep = 3 chisq =  0.01281 exp = gauss(5203.743,1899.694)*0.8564375
irep = 4 chisq = 0.008162 exp = gauss(5317.004,1231.655)*1.021223
irep = 5 chisq = 0.005793 exp = gauss(5250.328,1477.763)*0.9997244
irep = 6 chisq = 0.005556 exp = gauss(5265.959,1366.362)*1.053696
irep = 7 chisq =  0.00552 exp = gauss(5256.392,1402.267)*1.04326
irep = 8 chisq = 0.005519 exp = gauss(5259.122,1389.024)*1.04894
irep = 9 chisq = 0.005518 exp = gauss(5258.048,1393.428)*1.04723
irep = 14 chisq = 0.005518 exp = gauss(5258.108,1393.239)*1.047264
irep = 15 chisq = 0.005505 exp = gauss(5258.134,1393.157)*1.036914

Final solution:
gauss(5258.108,1393.239)*1.036895

Plot the ratio of the fit to the throughput table to see how good the fit is.

sy> plband "crwfpc2comp$wfpc2_f555w_001.tab / fit555w.tab" \
>>> left=4000 right=8000

REFERENCES

Written by Bernie Simon based on XCAL code written by Keith Horne. The Levenberg Marquardt code was taken from the minpack library at Argonne National Laboratory. The downhill simplex code was adapted from Numerical Recipes.

SEE ALSO

calcband