NAME

fsumrows -- Sum or average values from a list of table columns over a specified range of rows.

USAGE

        fsumrows infile outfile cols rows operation

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.

PARAMETERS

infile [filename]

The FITS file to read. If no extension is given, the program tries to read the the first extension.

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'.

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.

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.

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.

(ignorenull=NO) [boolean]

If not set (the default), then the presence of any null values in the input file will lead to a null value in the sum or average. If ignorenull is set to YES, then null values in the input will be ignored; in that case the output sum or average will be over the non-null values in the input. This check is done on a per-element basis, which is important for vector columns.

(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.

(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.

(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.

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.

         fi> fsumrows OBSERV.FITS[3] OBJECT3.FITS CCDFRAME - sum clobber=yes
           nullval=-9

2. Average rows 1-3, row 5, and all rows 9 and higher of CCDFRAME and append the result to OBJECT3.FITS.

         fi> fsumrows OBSERV.FITS[3] OBJECT3.FITS CCDFRAME 1-3,5,9-
           operation=AVG

BUGS

SEE ALSO

CATEGORY