flookup HEADAS help file

NAME

flookup -- Create a new FITS file from selection based on a lookup table

USAGE

        flookup infile[ext#] outfile lookup

DESCRIPTION

This task creates a new table based on the criteria specified in a lookup table. Based on the value of each row's element in the column specified by the tcolumn parameter, the upper and lower bounds of acceptable value of "column" are found in the lookup table. Depending on the value of the "bounds" parameter, all rows with values satisfying the requested condition are copied to the output file. Single value lookups are specified by setting the ubcol parameter equal to a blank or a '-'.

The bounds parameter is used to describe the condition between the upper and lower bounds in the lookup table, and the condition column in the input file. In this parameter a parenthesis specifies that the value of the bound in NOT included in the condition, and a square bracket means that the value IS included. Further, the direction of the parenthesis or bracket indicates the position of the table condition column value with respect to the lower or upper bound column value. This is best described with examples:

             condition                       bounds
     lbcol < column < ubcol                        ()
     column < lbcol or column > ubcol        )(
     lbcol <= column <= ubcol                []
     column < lbcol or column >= ubcol        )[
     lbcol < column                                (
     column <= lbcol                                ]
     lbcol = column                                []
     lbcol <> column                                )(

PARAMETERS

infile [filename]: A file name (including optional extension number in square brackets) of the FITS table to be searched.
outfile [filename]: The name of the created FITS file to contain the selected rows from the input table. If preceeded by a !, an existing file of the same name will be overwritten.
lookup [filename]: The name (and extension) of the lookup table.
tcolumn = "PHA" [string]: The name of the column that is the key to the lookup table.
lcolumn = "CHAN" [string]: The name of the column in the lookup table corresponding to tcolumn. This column must be in ascending order.
lbcol = "RTI_MIN" [string]: The name of the column in the lookup table containing the lower bound.
ubcol = "RTI_MAX" [string]: The name of the column in the lookup table containing the upper bound. If this parameter is blank or '-', only a single value lookup is performed. See the description above for details on the specification.
column = "RTI" [string]: The name of the column in the input file to be compared.
bounds = "()" [string]: This parameter specifies the condition to be tested and whether the bounds of the condition include the value of lbcol and/or ubcol. See the description above for details.
(history = yes) [boolean]: If true, history records will be added to the output file primary header indicating that FLOOKUP created the file, and another will be added to the extension header.
(copyall = yes) [boolean]: If true, all other extensions, including the primary array are copied to the output file.
(copyprime = no) [boolean]: If true, and if copyall is false, only the primary array is copied to the output file.
(clobber = no) [boolean]: If true, an existing file with the same name as the requested output file will be overwritten.

EXAMPLES

NOTES:

This program is currently optimized for lookup table keys that are one value apart (i.e. 1,2,3) and 1024 elements or less.

Rows containing null values in either the key column or the comparison column are never copied to the output file. BUGS