Example FTOOLS Session

The following example will display the contents of a sample FITS file, then will extract some of the data into a new FITS file.

To run this example, first copy the sample FITS data file that is distributed with FTOOLS into a convenient work directory:

> cp ~ftools/ftools/testdata/crabk.fits .

(If this does not work, contact your system administrator for the path to the FTOOLS installation at your site).

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:

> fstruct crabk.fits

  No. Type     EXTNAME      BITPIX Dimensions(columns)      PCOUNT  GCOUNT

   0  PRIMARY                -32     0                           0    1
   1  BINTABLE SPECTRUM        8     12(4) 128                   0    1

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.

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:

> flcol crabk.fits

___Column_Names_________Formats__________Units___
CHANNEL                    I
RATE                       E           COUNTS/S
STAT_ERR_RATE              E           COUNTS/S
DQF                        I

Finally, the fdump task may be used to view the actual header and data contents of the FITS file:

> fdump crabk.fits prhead=yes prdata=no

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

> fdump 'crabk.fits[0]' or fdump crabk.fits+0

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,

> fdump 'crabk.fits[*]' prdata=no

Now to display the first 20 rows of data in the table type,

> fdump crabk.fits prdata=yes prhead=no rows=1-20

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.

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:

> fselect crabk.fits new.fits DQF==1

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:

> fdump new.fits+1 rows=1-

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.

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.

FTOOLS HELP DESK

If FTOOLS has been useful in your research, please reference this site (http://heasarc.gsfc.nasa.gov/ftools) and use the ASCL reference for HEASoft [ascl:1408.004] or the ASCL reference for the original FTOOLs paper [ascl:9912.002]:

Blackburn, J. K. 1995, in ASP Conf. Ser., Vol. 77, Astronomical Data Analysis Software and Systems IV, ed. R. A. Shaw, H. E. Payne, and J. J. E. Hayes (San Francisco: ASP), 367.

Web page maintained by: Bryan K. Irby