5.4.1 Column and Keyword Filtering

The column or keyword filtering specifier is used to modify the column structure and/or the header keywords in the HDU that was selected with the previous HDU location specifier. It can be used to perform the following types of operations.

• Append a new column to a table by giving the column name, optionally followed by the datatype in parentheses, followed by an equals sign and the arithmetic expression to be used to compute the value. The datatype is specified using the same syntax that is allowed for the value of the FITS TFORMn keyword (e.g., 'I', 'J', 'E', 'D', etc. for binary tables, and 'I8', F12.3', 'E20.12', etc. for ASCII tables). If the datatype is not specified then a default datatype will be chosen depending on the expression.

• Create a new header keyword by giving the keyword name, preceded by a pound sign '#', followed by an equals sign and an arithmetic expression for the value of the keyword. The expression may be a function of other header keyword values. The comment string for the keyword may be specified in parentheses immediately following the keyword name.

• Overwrite the values in an existing column or keyword by giving the name followed by an equals sign and an arithmetic expression.

• Select a set of columns to be included in the filtered file by listing the column names separated with semi-colons. Wild card characters may be used in the column names to match multiple columns. Any other columns in the input table will not appear in the filtered file.

• Delete a column or keyword by listing the name preceded by a minus sign or an exclamation mark (!)

• Rename an existing column or keyword with the syntax 'NewName == OldName'.

The column filtering specifier is enclosed in square brackets and begins with the string 'col'. Multiple operations can be performed by separating them with semi-colons. For complex or commonly used operations, you can write the column filter to a text file, and then use it by giving the name of the text file, preceded by a '@' character.

Some examples:

  [col PI=PHA * 1.1 + 0.2]      - creates new PI column from PHA values

  [col rate = counts/exposure]  - creates or overwrites the rate column by
                                  dividing the counts column by the
                                  EXPOSURE keyword value.

  [col TIME; X; Y]              - only the listed columns will appear
                                  in the filtered file

  [col Time;*raw]               - include the Time column and any other
                                  columns whose name ends with 'raw'.

  [col -TIME; Good == STATUS]   - deletes the TIME column and
                                  renames the STATUS column to GOOD

  [col @colfilt.txt]            - uses the filtering expression in
                                  the colfilt.txt text file

The original file is not changed by this filtering operation, and instead the modifications are made on a temporary copy of the input FITS file (usually in memory), which includes a copy of all the other HDUs in the input file. The original input file is closed and the application program opens the filtered copy of the file.