STScI Logo

ngaussfit stsdas.analysis.fitting


NAME · USAGE · DESCRIPTION · PARAMETERS · EXAMPLES · BUGS · REFERENCES
SEE_ALSO

NAME

ngaussfit -- Fit multiple Gaussian functions (1-dimensional) to one or more lists, image sections, or tables.

USAGE

ngaussfit input output

DESCRIPTION

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.

PARAMETERS

input [file name template]
List of files to be fitted. May be STDIN, or one or more image sections, tables and columns, or lists.
output [file name]
Name of the STSDAS table to which fitting information will be written.
(errcolumn = "" ) [string]
Column name for the error column, if fitting a table. If a table is being fit, and this is left blank, it is assumed that there is no error column.
(function = "Gaussians") [string, allowed values: Gaussians | cgauss]
Type of function. (The two options are discussed above.)
(rt = no) [boolean]
Read the initial coefficient guesses from a table?
(tablein = "") [string]
File name of the table from which to read the initial coefficient guesses.
(row = 1) [integer, min=1]
Table row from which to read initial coefficient guesses. If more than one data set is being fitted, the same values will be used for all data sets.
(gausspars = "") [string]
The name of the file containing the function-dependent Gaussian parameters.
(cgausspars = "") [string]
The name of the file containing the function-dependent constrained Gaussian parameters.
(errorpars = "") [string]
The name of the file containing the error-related parameters (pset).
(controlpars = "") [string]
The name of the file containing the algorithm control parameters (pset).
(samplepars = "") [string]
The name of the file containing the sampling parameters (pset).
(interactive = yes) [boolean]
Work in the interactive graphics mode?
(verbose = no) [boolean]
Display messages about each fitting iteration?
(pcomp = yes) [boolean]
Plot individual composite function components?
(ltype = "continuous") [string, allowed values: continuous | boxes ]

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.

(device = "stdgraph") [string]
Graphics output device.
(cursor) [graphics cursor]
Graphics cursor input. (Type "help vdisplay.tvcursor" for more information about the cursor facility.)

EXAMPLES

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

BUGS

REFERENCES

This task was written by I.Busko

SEE ALSO

errorpars, controlpars, funcform, ncfit, selectors


Source Code · Package Help · Search Form · STSDAS