The following example will display the contents of a sample FITS file, then will extract some of the data into a new FITS file.
0.2cm
To run this example, first copy the sample FITS data file that is distributed with FTOOLS into a convenient work directory:
0.2cm
1.0cm > cp ~ftools/ftools/testdata/crabk.fits .
0.2cm
(If this does not work, contact your system administrator for the path to the FTOOLS installation at your site).
0.2cm
In order to see what information is contained in the FITS file, the first step is to determine the basic structure of the file with the fstruct task:
0.2cm
1.0cm > fstruct crabk.fits
0.2cm
No. Type EXTNAME BITPIX Dimensions(columns) PCOUNT GCOUNT 0 PRIMARY -32 0 0 1 1 BINTABLE SPECTRUM 8 12(4) 128 0 1
0.2cm
This shows that the FITS file crabk.fits consists of a primary array with zero data elements (i.e., the primary array consists only of header records, with no data array) followed by a single binary table extension called 'SPECTRUM' which has 4 columns of data (with a total of 12 bytes of information in each row) and 128 rows.
0.2cm
Next, the flcol task (List COLumns task) can be used to get more information about the names and datatypes of all the columns in a particular table:
0.2cm
1.0cm > flcol crabk.fits
0.2cm
___Column_Names_________Formats__________Units___ CHANNEL I RATE E COUNTS/S STAT_ERR_RATE E COUNTS/S DQF I
0.2cm
Finally, the fdump task may be used to view the actual header and data contents of the FITS file:
0.2cm
1.0cm > fdump crabk.fits prhead=yes prdata=no
0.2cm
This will list all headers in the FITS file (hit <CR> to accept the default values of the other required parameters). Note that the convention used in many the FTOOLS tasks is to operate on the first extension in the FITS file by default unless another extension is explicitly specified in square brackets appended to the input file name or following a + sign. For tasks explicitly dealing with images the primary array is the default. For instance, to print the header of the initial primary array, enter
0.2cm
1.0cm > fdump 'crabk.fits[0]' or fdump crabk.fits+0
0.2cm
Most tasks operate on a single extension at a time, but some tasks, including fdump, can operate on all the extensions in a file in a single run, by specifying the extension number as [*]. Thus to display all the header records in the whole FITS file, type,
0.2cm
1.0cm > fdump 'crabk.fits[*]' prdata=no
0.2cm
Now to display the first 20 rows of data in the table type,
0.2cm
1.0cm > fdump crabk.fits prdata=yes prhead=no rows=1-20
0.2cm
As before, just hit <CR> to accept the default values of the other parameters. This should display the first 20 rows of data for all 4 columns of the table. Note that the first 14 rows of the data are undefined as indicated by the INDEF symbol.
0.2cm
To illustrate the use of a couple more FTOOLS tasks, we can modify the contents of this sample FITS file, to produce a new file. Suppose we want to create a new FITS table that only contains the rows which have defined data values (i.e., excluding the first 14 rows in the crabk.fits table. This can be done with the fselect task by selecting only those rows which have a value of 1 in the `DQF' column:
0.2cm
1.0cm > fselect crabk.fits new.fits DQF==1
0.2cm
This then creates a new output FITS file with a binary table extension containing only the rows from the input table which have DQF equal 1. This may be verified by typing:
0.2cm
1.0cm > fdump new.fits+1 rows=1-
0.2cm
This concludes the demonstration of FTOOLS, which has hopefully illustrated the basic techniques that are needed to explore the capabilities of the other FTOOLS tasks.
0.3cm
A more descriptive discussion of the FTOOLS usage can be found in the article ``FTOOLS Tutorial'' in Legacy - The Journal of the HEASARC, 4, 5, 1994.