Help for IBISLSQ3

PURPOSE

   "ibislsq3" performs least squares fits on data in an IBIS interface
(tabular) file.  The solutions and/or residuals can be placed in 
specified columns of the file.  The solutions can also be output
to the terminal.  Multiple fits can be done on different parts of
one file.  A threshold can also be specified so that the program
will repeatedly perform least sqares fitting while throwing out 1
outlier at a time until all the residuals are under the defined 
threshold.  Note that if only x' is specified, the outlier will
be determined by the data point's residual value.  If both x' and
y' are specified then the outlier will be determined by
square root of (residual(x')^2 + residual(y')^2).

EXECUTION

     ibislsq3 INP=DATA.INT OUT=DATAOUT INDCOL=(1,2,3) DEPCOL=4
             CONCOL=7 RESCOL=8  COEFFCOL=(21,22,23) DEPCOL2=5
             RESCOL2=8 COEFFCOL2=(24,25,26) 'NOPRINT THRESH=2.0

    This example shows the use of all of the parameters.  The input
file, DATA.INT, is an IBIS interface file and the output file
is also an IBIS interface file.  The data for the independent
variables are in columns (1,2,3), and the data for the dependent 
variables are in column 4 and 5.  The control column 7 is used for
multiple fits to be done in one run.  The least square fits are done 
on sets of rows; a new set is started whenever the value in the control 
column changes.  If no control column is specified then one fit
is done on the whole file.  The COEFFCOL and RESCOL parameters specify
in which columns, of the input file, the results will be put.  If either
or both are not specified then they will not be output.  The COEFFCOL2
and RESCOL2 correspond to the DEPCOL2 data.  There must be
as many coefficient columns as there are independent columns and these
match the sequence of the independent variable columns.  The
coefficients of the solution are placed in columns 21,22,23.  The
residual column can be used to easily calculate the deviation of the
data points from the fitted line. Normally the solution for each set
is printed to the terminal, but this can be turned off with the
'NOPRINT keyword.  

    The length of each set should, of course, be longer than the
number of independent variables (columns).  If it is not then the
least squares fit will not be called and values of -999.0 will be
put out for the solution.  If some columns of the independent data
are dependent then the error MATRIX RANK TOO SMALL be be printed,
and -999.0's will be put out for the solution.  If there is no
solution then zeros will be put out for the residuals.

EXAMPLES

   Suppose that columns 1 and 2 contain points (x,y) in a plane 
   and  column  7 contains a function  f(x,y).   The  following 
   sequence  will perform a quadratic least squares fit  h(x,y) 
   and place the residuals in column 8.

   mf INP=A FUNCTION=("C3=C1*C1","C4=C2*C2","C5=C1*C2","C6=1")
   ibislsq3 INP=A OUT=B INDCOL=(1,2,3,4,5,6) DEPCOL=7 RESCOL=8

   Suppose that you want the program to automatically take out
   outliers one at a time and reperform least squares fitting.
   To repeat until all residuals are below 2.0:

   ibislsq3 INP=A OUT=B INDCOL=(1,2,3,4,5,6) DEPCOL=7 RESCOL=8
      THRESH=2.0

   Suppose now that columns 1, 2, and 3 represent the independent
   variables, columns 4 and 5 represent x' and y' respectively,
   column 7 represents the control column, 8 and 9 represents
   the residual columns for x' and y' respectively, columns 10,
   11, 12 represents the coefficients to the solution to x',
   and columns 16, 17, 18 represents the coefficients to
   y'.  Suppose also that we would like the solution to have the
   maximum residual for any data point to be below 2.0 and
   we want to not print the solution to the screen.  The
   following command performs this task:

   ibislsq3 inp=a out=b indcol=(1,2,3) depcol=4 depcol2=5        colcol=7 rescol=8 rescol2=9 coeffcol=(10,11,12)        coeffcol2=(16,17,18) thresh=2.0 'NOPRINT

RESTRICTIONS

The maximum number of independent columns (variables) is 20.
DEPCOL, COEFFCOL, and RESCOL corresponds to each other and
DEPCOL2, COEFFCOL2, and RESCOL2 corresponds to each other.
You can not mix them together... for example, you can not
have DEPCOL correspond to RESCOL2.

Original Programmer: A. L. Zobrist, 11 Sep, 2001
Current Cognizant Programmer: A. L. Zobrist
Last changed by: A. L. Zobrist, 27 Aug, 2002
   2022-07-27 B. Crocco afids to opensource (untested)
Changed from IBISLSQ2 to IBISLSQ3 by: P. Kim 10, Sep, 2007