SEE_ALSO

## NAME

gfit1d -- Fit 1-dimensional functions to one or more lists, image sections, or tables.

## USAGE

`gfit1d input output`

## DESCRIPTION

This task fits 1-dimensional functions, by minimizing chi-square, to one or more lists, image sections, table columns, or table array cells ("3-D tables"). Supported functions are: polynomials of Chebyshev or Legendre types, linear or cubic splines. The fitting method accumulates and solves the normal equations using Cholesky factorization.

Lists and image sections can be mixed in the input list using wildcard characters. Fit results will be written to an STSDAS table. (Table formats are described below). If the table does not exist, it will be created. Otherwise, the fit results will be appended as the last row in the table.

If an image section operand has more than one dimension, the projection
(i.e., average) onto a designated axis will be computed (see `samplepars`
pset). If the input data is in the form of image sections, then FITS
keywords related to transformation from pixel to world coordinates are
read from the image header. Those keywords are used to generate the X and
Y variables in physical units. Supported keywords are: `W0`, `WPC`,
`CRPIXn`, `CRVALn`, `CDn_n`, `CDELTn`, `DISPAXIS`, `DC-FLAG`, `BSCALE`
and `BZERO` (n is the designated axis). If no suitable keywords are found,
then raw values (pixel number and content) are used.

The fitting parameters can be interactively set using the graphics cursor. Each data set may be fitted with different functions and orders if the task is used interactively. The dependent variable must be provided in linear units. The independent variable do not need to be equally spaced, nor ordered. Internal computations are made in double precision.

List input may be taken from the standard input or from a file, and consists of a sequence of Y values, X and Y values, or X,Y and error values; only one pair of coordinates can be placed on a line. Blank lines, comment lines, and extra columns are ignored. The first element in the list determines whether the list is a Y list or an X,Y list; it is an error if an X,Y list has fewer than two coordinates in any element. INDEF valued elements are ignored. The list does not need to be ordered, nor equally spaced, in X.

STSDAS table input is specified by a table name and column name, a table
and two columns, or a pair of table and column names. The table name
may be a file name template. The table name may have appended to it a
row selector. If the specified column(s) store arrays in each cell
("3-D table") the full array contents at each selected row are read and
used to build the 1-D data vectors. When reading from two separate columns,
both of them must store either scalars or arrays with same size. See the
"help selectors" help page in the `tables` package.

Error information, needed for properly computing chi-square, can be
input in a variety of ways. See help page for the `errorpars` pset.

The STSDAS output table contains the information described below. Each particular fit will result in a new row being appended to the table.

Column label Contents ====== ======== file Name of the file on which the fit was originally performed. time Date and time the fit was performed. function Fitted function. ncoeff Number of function coefficients (degree). unit '*' npoints Number of data points used in fit. xmin, xmax Limits for function normalization. chisq Chi-square of fit. rms Root mean square of fit. coeff1 First coefficient. err1 First coefficient error. coeff2 Second coefficient. err2 Second coefficient error. ... ...New columns are created as needed to hold any number of coefficients. The total number of columns in the table will depend on the maximum order used in a particular fit.

The `ps` parameter allows the user to control which coefficients will be
written to the output table. If `ps=yes`, then straight power-series
polynomial coefficients are output. If `ps=no`, Legendre or Chebyshev
orthogonal polynomial coefficients are output instead. This parameter has
no effect when fitting splines.

## PARAMETERS

- input [file name template]
- List of operands to be fitted. This parameter can be set to STDIN, or one or more image sections, tables and columns, or lists.

- output [file name]
- Output table that will contain fitting information.

- (function = "spline3") [string, allowed values: spline| legendre |
- chebyshev | spline1]
Fitting function to be used.

- (order = 1) [integer, min=1]
- Order of the fitting function.

- (xmin = INDEF) [real]
- Value of the independent variable corresponding to the lower limit for function normalization. If INDEF, the minimum X will be used. The same value holds for all files in the input list.

- (xmax = INDEF) [real]
- Value of the independent variable corresponding to the upper limit for function normalization. If INDEF, the maximum X will be used. The same value holds for all files in the input list.

- (ps = yes) [boolean]
- Write the coefficients as in a power-series polynomial? (Only when fitting Chebyshev and Legendre functions).

- (errorpars = "") [string]
- The name of the file containing the error-related parameters (pset).

- (samplepars = "") [string]
- The name of the file containing the sampling parameters (pset).

- (interactive = yes) [boolean]
- Set the fitting parameters interactively?

- (device = "stdgraph") [string]
- Graphics output device.

- (cursor) [graphics cursor file]
- Graphics cursor input. (Type "help vdisplay.tvcursor" for more information about the IRAF cursor facility.)

## EXAMPLES

1. Fit a section of the image `test` and store the fit results in the
table `testfit.tab` in the user's home directory:

fi> gfit1d test[100:500,256:300] home$testfit

2. Fit spectral order 80 to 83 on an echelle STIS extracted spectrum:

fi> gfit1d "file.fits[r:SPORDER=80:83] WAVELENGTH FLUX" output

## BUGS

In the graphics window banner, it is not possible to write the chi-square of the fit, because these graphics are handled by an internal IRAF library, which can only write the rms of the fit. Use the :chisq colon command to see the current chi-square value.

See also the BUGS section of the `errorpars` pset.

## REFERENCES

This task was written by I.Busko

## SEE ALSO

errorpars, samplepars, icfit, selectors