| ngaussfit | stsdas.analysis.fitting | ngaussfit |
ngaussfit -- Fit multiple Gaussian functions (1-dimensional) to one or more lists, image sections, or tables.
ngaussfit input output
This task fits 1-dimensional Gaussian functions to one or more lists, image sections, table columns, or table array cells ("3-D tables"). Chi-square fitting is performed by either the downhill simplex minimization algorithm ("amoeba") or the Levenberg-Marquardt algorithm.
Lists and image sections may be mixed in the input list using wildcard characters in the file name template. Fit results will be written to a STSDAS table. See below for a description of the table format. 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 are 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.
List input may be taken from the standard input (STDIN) or from a file, and consists of a sequence of Y values, X and Y values, or X,Y and error values, one pair of coordinates per line in the list. Blank lines, comment lines (beginning with a #), 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.
If the input file is an STSDAS table, then the input is specified as a either: 1) a table name and column name, 2) a table and two column names;, or 3) a pair of table and column names. Table names can be file name templates (i.e., wildcard characters are allowed). 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, as well as for generating estimates for the function coefficient errors, can be input in a variety of ways. See help page for the errorpars pset.
The functional form fitted to the data is a sum of N Gaussian components, each represented by three parameters: amplitude, center, and fwhm. Amplitudes are specified above a "straight line" baseline, common to all components. If other baseline trends are present in the data, they must be removed prior to running this task.
Two function types can be used: "Gaussians", in which all coefficients are given in absolute data units; and "cgauss" (constrained Gaussians), in which only the first component is given in absolute units and subsequent components are specified relative to the first (amplitudes as a factor of the first, and centers as an offset from the first). This constrained form is useful in cases in which the user wants to keep fixed (during the fit), not the absolute values of the Gaussian coefficients, but their relative values, as when constraining spectral line ratios by atomic physics values, or spectral line positions by their difference in wavelength. Functional forms can be changed at will when the task is used interactively. Type "help funcform" for more details.
Most fitting parameters may be set interactively. Each data set can be fitted with different sets of functions and parameters if the task is used interactively. Type "help ncfit" to get more details.
The fitting algorithms need initial guesses for the function coefficients. Guesses can be specified through task parameters, from a previously generated table, or interactively. Parameter sets (psets) are used for function coefficients at startup. If psets are used, a maximum of three Gaussians is allowed. Additional Gaussians can be entered interactively. There is no limit on the number of initial Gaussian components entered from a table. If both task parameters and table values are insufficient to define at least one meaningful Gaussian component, then the task defaults to a single Gaussian with its peak corresponding to the highest value in the dependent variable vector, and FWHM set to 1/100 of the independent variable range of values.
When using a table for initial guess, the values of the coefficient errors are used to determine if the corresponding coefficients are to be varied. If the error is negative, its coefficient will be held fixed during the fitting.
The user can specify, either at startup or at any other time (interactively), which coefficients are to be varied and which are to be held fixed during the fitting process.
The STSDAS output table contains the information described below. Each particular fit will result in a new line 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, either "Gaussians" or "cgauss" ncoeff Number of function coefficients unit '*' npoints Number of data points used in fit xmin, xmax Not used 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 will be dependent of the maximum number of coefficients used in a particular fit.
Plot data points as continuous line or individual boxes ? In "boxes" mode, and if the error bars are not all equal, error bars are also plottted for each point.
1. Fit a section of the image test and store the fit results in the file testfit.db in the user's home directory:
fi> ngaussfit test[100:500,256:300] home$testfit.db
2. Fit spectral order 80 to 83 on an echelle STIS extracted spectrum:
fi> ngaussfit "file.fits[r:SPORDER=80:83] WAVELENGTH FLUX" output
This task was written by I.Busko
errorpars, controlpars, funcform, ncfit, selectors
