next up previous contents FITSIO Home
Next: 10.10 Row Filtering Specification Up: 10. Extended File Name Previous: 10.8 Image Section

10.9 Column and Keyword Filtering Specification

The optional column/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. This filtering specifier must be enclosed in square brackets and can be distinguished from a general row filter specifier (described below) by the fact that it begins with the string 'col ' and is not immediately followed by an equals sign. The original file is not changed by this filtering operation, and instead the modifications are made on a copy of the input FITS file (usually in memory), which also contains a copy of all the other HDUs in the file. This temporary file is passed to the application program and will persist only until the file is closed or until the program exits, unless the outfile specifier (see above) is also supplied.

The column/keyword filter can be used to perform the following operations. More than one operation may be specified by separating them with semi-colons.

The expression that is used when appending or recomputing columns or keywords can be arbitrarily complex and may be a function of other header keyword values and other columns (in the same row). The full syntax and available functions for the expression are described below in the row filter specification section.

For complex or commonly used operations, one can also place the operations into an external text file and import it into the column filter using the syntax '[col @filename.txt]'. The operations can extend over multiple lines of the file, but multiple operations must still be separated by semicolons. Any lines in the external text file that begin with 2 slash characters ('//') will be ignored and may be used to add comments into the file.

Examples:

   [col Time;rate]               - only the Time and rate columns will
                                   appear in the filtered input 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 PI=PHA * 1.1 + 0.2]      - creates new PI column from PHA values

   [col rate = rate/exposure]   - recomputes the rate column by dividing
                                   it by the EXPOSURE keyword value.


next up previous contents FITSIO Home
Next: 10.10 Row Filtering Specification Up: 10. Extended File Name Previous: 10.8 Image Section