.help tlinear Aug2000 tables
.ih
NAME
tlinear -- Fit a linear function to one or two table columns by linear
regression.
.ih
USAGE
tlinear intable outtable xcol ycol
.ih
DESCRIPTION
This task generates fitted Y values and their residuals in two columns.
These columns may be written to an output table, but cannot be written
to STDOUT--only the fit parameters can be written to STDOUT.
If there is more than one table in the input list then a separate fit
is made for each table.

When a column of weights is used (see 'wcol'),
the weights will be applied when computing the
coefficients of the fit (a, b),
their standard deviations (siga2, sigb2),
and chi squared (chi2),
where the names in parentheses are the headings in
the output printed to STDOUT.
If any row has a weight that is exactly zero,
that row will not be counted in the "pts in fit" value.
The weights will NOT be used when computing
the RMS of the residuals and mean of the residuals
(residual rms, residual mean);
these are unweighted averages
except that rows with exactly zero weight will not be included.
.ih
PARAMETERS
.ls intable [file name template]
A list of input tables containing the columns to be fit.
A fit will be made of the columns specified by the 'xcol' and 'ycol'
parameters.  If more than one file name is passed to 'intable', all of
the files must use the same column names.
.le
.ls outtable = STDOUT [file name template]
File names for creating output files, or STDOUT to send output to the screen.
If the value of this parameter is "STDOUT" then the parameters of the fit will
be written to STDOUT preceded by a header line (beginning with #) in tabular
form.
If 'outtable' is not "STDOUT" then the number of file
names must match the number
of names in 'intable', and the fitted Y values and residuals will be written
to an output table with the specified name.  The parameters of the fit will
be written to the table header.
.le
.ls xcol [string]
Column name in the input tables to be fit.
The values in this column will be fit for the X axis.
(The same column name is used for each input table.)  If a name is not specified
for the X values then row number is used.  The values in the 'xcol' column will
be copied to 'outtable' unless the output is being directed to STDOUT.
.le
.ls ycol [string]
Column name in the input tables containing value to be fit for the Y axis.
(The same column name is used for each input table.)  Values in 'ycol' will
be copied to 'outtable' unless 'outtable = STDOUT'.
.le
.ls (wcol) [string]
Column name in 'intable' that contains weight values for X and Y.
(The same column name is used for each input table.)  If no column
name is passed to either the 'wcol' or 'scol' parameters, then a weight
of 1. is used.  The value of the 'wcol' column is copied to 'outtable' unless
'outtable = STDOUT'.
.le
.ls (scol) [string]
Column in 'intable' containing the standard deviation of X and Y.
The X and Y values are weighted by the values in 'scol'
as the reciprocal of the values squared.  (The same column name is used for each
input table.)  If no value is passed to 'wcol' or 'scol', then
a weight of 1. is used.  This task can accept either a weight value or a
standard deviation value, but not both.  If both 'wcol' and 'scol' are
specified, then the weight column (i.e., 'wcol') will be used.
The value in the 'scol' column is written to 'outtable' unless 'outtable'
= STDOUT.
.le
.ls (rows = "-") [string]
Range of rows to use for fitting the data.
The default "-" means that all rows are used.
(Type "help xtools.ranges" for more information.)
.le
.ls (outcoly = "yfit") [string]
Column name for fitted Y values.
This parameter is not used if 'outtable' = STDOUT.
This column will be double data type.
.le
.ls (outcolr = "yres") [string]
Name of the column to contain residuals.
This parameter is ignored if 'outtable' = STDOUT.
This column will be of double data type.
.le
.ih
EXAMPLES
1. Fit the values in the "flux" column in every table whose name begins with
"hr"; put all parameters of the fits in the ASCII file "fit.lis".

.nf
  tt> tlinear hr*.tab STDOUT "" flux > fit.lis
.fi

2. Generate the same fits as in the previous example, but put the
results in tables, one output for each input table.  For example,
the fitted Y values and
residuals for an input table named "hr465.tab" would be put in "hr465h.tab".

.nf
  tt> tlinear hr*.tab hr*%%h%.tab "" flux
.fi

3. Fit the values in the "flux" column as a function of the values in the
"wavelength" column and write all the parameters of the fit to STDOUT.

.nf
  tt> tlinear hr*.tab STDOUT wavelength flux
.fi
.ih
BUGS
.ih
REFERENCES
This task was written by Betty Stobie.
.ih
SEE ALSO
ranges
.endhelp
