.help fsumrows May99 ftools.futils
.ih
NAME
fsumrows -- Sum or average values from a list of table columns over
a specified range of rows.
.ih
USAGE
fsumrows infile outfile cols rows operation
.ih
DESCRIPTION
Create a table from data summed or averaged from a table extension.
An arbitrary list of columns, and range of rows may be selected to
to be SUMmed or AVeraGed. The resulting single row table can be
placed into a new file or appended to an already existing file
as a table extension.
.ih
PARAMETERS
.ls infile [filename]
The FITS file to read.  If no extension is given, the program tries to
read the the first extension.
.le
.ls outfile [filename]
The FITS file to which to write the new table.  Any extension given is
ignored.  If the file does not exist, it will be created with a primary
array followed by a table extension.  If the ouput file exists, the output
table will be appended to the output file unless the clobber parameter is
set to 'yes'.
.le
.ls cols [string]
The names of all the columns to be listed in the output.  The names may
be either the exact name of the column, or they may contain wildcard
characters (*, ?, or #), or they may contain the integer number of the
desired column (with the first column = 1).  The '*' wild card character
matches any sequence of characters (including zero characters) and the
'?' character matches any single character.  The '#' wildcard will match
any consecutive string of decimal digits (0-9).  If  no
names  are  given,  then by default all the columns in the table
will be processed.  The column names must be  separated  by  commas
or  spaces  in the list.  If a column name contains a space, the
name must be enclosed in double quotes (").   If  any  names  in
the  column  list are enclosed in double quotes, the entire list
must be enclosed in single quotes (').  eg '"column 1",column2'

Optionally the list of column names can be placed  in  an  ASCII
file,  one  name  per  line,  and  then  the  name  of the file,
proceeded by an "@" character may  be  given  to  the  "columns"
parameter.

The  'flcol'  task  (with  the  NLIST parameter set to 1) may be
used to generate a list of column names suitable  for  input  to
this task.
.le
.ls rows [string]
A list of row ranges to process.  Ranges can be in reverse order (ie, hi to
low) or can leave off one (or both) ends to indicate a range starting
with the first or ending with the last row in the extension.
.le
.ls operation = "SUM" [string]
The operation to perform on the data.  "SUM" combines each input row into a
single, summed array.  "AVG" also sums the data, but before outputting the
array renormalizes it by the number or rows read.  "SUM" and "AVG" create a
table containing a single row.  The data type of the columns in the
output table is single precision float in order to avoid overflows when
summing and truncations when averaging, unless sametype = yes, in which
case the datatype of the column remains the same as in the input
table.
.le
.ls (nullval = -99) [int]
The numerical value to assign to NULLs found in an integer column of
an input ASCII table extension.  In all other cases the TNULLn or BLANK
keyword from the input extension is used instead for integer data and
NaN for real data.
.le
.ls (clobber = no) [boolean]
If outfile already exists and clobber=yes, outfile is deleted and a
new file created with the output table going into a table extension.
If clobber=no, the table will be appended to an already existing file,
aborting if the file does not exist.
.le
.ls (sametype = no) [boolean]
If set equal to yes, then the datatype of the columns in the output
table will remain the same as in the input table.  This could cause
overflow errors or loss of precision for integer datatype columns.
.le
.ih
EXAMPLES
1. Sum the entire column CCDFRAME (an array) from extension 3 of file
OBSERV.FITS into a table in a new file named OBJECT3.FITS.  NULLs should be
assigned values of -9 in the resulting image.
.nj
.ls
fi> fsumrows OBSERV.FITS[3] OBJECT3.FITS CCDFRAME - sum clobber=yes
nullval=-9
.ju
.le

2. Average rows 1-3, row 5, and all rows 9 and higher of CCDFRAME and append
the result to OBJECT3.FITS.
.ls
.nj
fi> fsumrows OBSERV.FITS[3] OBJECT3.FITS CCDFRAME 1-3,5,9-
operation=AVG
.ju
.le
.ih
BUGS
.ih
SEE ALSO
.endhelp
