.help fstatistic Apr2013 ftools.futils
.ih
NAME
fstatistic -- Compute statistics (min, max, mean, etc..) for a given column in a 
FITS ASCII or binary table file extension.
.ih
USAGE
fstatistic infile[ext#] colname 
.ih
DESCRIPTION
This task computes the mean, standard deviation, minimum, and maximum
of the data in the specified column.  The rows included in the calculation
can be specified.  Maximum and minimum values can be specified, outside of 
which the data will not be included in the calculation.  If either the maximum
and/or the minimum requested is equal to INDEF, it will not be tested for.  The
output is written to STDOUT and to the parameter file by default.  The output
may also be directed to a file.

Note that in the case of vector columns, statistics are computed on the *sum*
of the vector elements in each row of the table (i.e. the reported mean value
is that of all the individual sums in each row).  For alternate vector column
handling, please use the ftstat task which computes statistics for the total
number of elements, in all of the rows of each column.
.ih
PARAMETERS
.ls infile [filename]
The name of the FITS file (including extension number in square brackets) 
of the input FITS table.
.le
.ls colname [string]
Name of the column in the input table.  The statistics are calculated for
this column.  If the column is multi-dimensional, the statistics are based
on the sum of all elements of the column.  The statistics on a specific
element of the vector/array can be requested by specifying the element:
COLNAME(10,4) or COLNAME[30;4].
.le
.ls rows [string]
String containing the requested rows to include in the calculation.  If the
value is "-", the entire file will be used.
.le
.ls (outfile=STDOUT) [filename]
Optional output file name to write the statistics.  If preceeded by a !,
an existing file of the same name will be overwritten.
.le
.ls (maxval=INDEF) [real]
The maximum value to include in the calculation.  A value of INDEF indicates
that no upper limit will be used in the calculation.
.le
.ls (minval=INDEF) [real]
The minimum value to include in the calculation.  A value of INDEF indicates
no lower limit.
.le
.ls (sum= ) [real]
Value of the sum of the specified column is returned to this parameter.
.le
.ls (mean= ) [real]
Value of the mean of the specified column is returned to this parameter.
.le
.ls (sigma= ) [real]
The value of the standard deviation is written to this parameter.
.le
.ls (min= ) [real]
The minimum value in the requested column is written into this parameter.
.le
.ls (max= ) [real]
The maximum value in the requested column is written to this parameter.
.le
.ls (numb= ) [integer]
The number of values actually used in the calculation is returned.
.le
.ls (clobber=no) [boolean]
If true, an existing file of the same name as the requested output file
will be overwritten.
.le
.ih
EXAMPLES 
1.  Compute the statistics for the 'FLUX' column in the second 
    extension in the input FITS file named 'myfile.fits':

    ft> fstatistic myfile.fits[2] flux
.fi
.ih
SEE ALSO
ftstat, ftlist
.endhelp
