Search:

[Advanced Search]



FTOOLS: A General Package of Software to Manipulate FITS Files

A Quick Tutorial

The following guide provides a brief introduction on the use of the FTOOLS software package for analyzing FITS-format data files. FTOOLS is a collection of utility programs to create, examine, or modify data files in the FITS (Flexible Image Transport System) format. This guide should give you an overview of how the core FTOOLS work, but beginning users may also find it useful to just type fgui, the FTOOLS GUI interface, and begin playing around with that.

FTOOLS currently is supported in a number of different (primarily Unix) environments.

Prior to beginning this tutorial, users should setup the FTOOLS for their personal use. There are instructions at the end of the INSTALL file, included with the FTOOLS distribution.

Getting Help

General help information about FTOOLS, as well as detailed help on each individual task, can be obtained with the fhelp task. Type:

fhelp ftools to get a brief description of each FTOOLS task and all available help files. To get detailed help on any particular FTOOLS task, type: fhelp taskname where taskname is the name of the task in which you are interested.

The help file for each task gives a description of what the task does and a description of all of its required and optional (hidden) parameters.

It is important to note that when running an FTOOLS task, the user is required only to enter values for the most important parameters, such as the name of the input FITS file. However, most of the tasks also have other "hidden" parameters, which have a predefined value unless the user explicity resets them to a new value. These hidden parameters can alter significantly the operation of the task, so one must be aware of the hidden parameters available for a given task, as well as the default values of each parameter. One way to determine this information is to read the help file for the task, using the fhelp command. A quicker way to see all the task parameters and their current values is to use the plist command (analogous to the lpar command in IRAF). For example: 

  >plist flcol
  Parameters for /local/redshift/home/elwin/pfiles/develop/flcol.par
         infile =                  Name of FITS file and [ext#]
         (nlist = 3)               Amount of column information
       (outfile = STDOUT)          Name of optional output file
      (showdims = yes)             Show dimensionality of columns?
       (clobber = no)              Overwrite existing output file?
          (mode = ql)
The above example shows that the flcol task has four hidden parameters. The names of the hidden paramters are enclosed in parentheses. The hidden parameters control the amount of information displayed (nlist), the name of the output file, or STDOUT to display to the terminal, (outfile), whether to show the dimensionality of columns (showdims), and whether to overwrite an already existing copy of the output file (clobber). Note that all tasks have a hidden mode parameter which controls how the parameter file is used by the program, but its value should not, in general, be changed by the user.

Running a Task

The simplest way to run a task is to enter its name on the input command line followed by a carriage return, as in:

ftlist

The task then will prompt the user for the value of all the required parameters. First, the current value of each parameter is displayed. If that value is acceptable, the user simply strikes a carriage return to accept it. If not, the user enters a new value followed by a carriage return. The user is not prompted for hidden paramters; the task simply assumes the default values (which can be listed with the plist command as previously shown).

If the user knows the value of any or all of the required task parameters, they may alternatively enter their values directly on the command line in the same order as listed by plist. This action eliminates the need for the user to be prompted for every required parameter. Instead, the task will prompt only for the values of any remaining non-hidden parameters that were not entered on the command line. For example:

ftlist rate.fit HC

will list a 1-line summary of each HDU (H) and the names and units of (C)olumns in any tables in the FITS file rate.fits onto the standard output device (STDOUT). As mentioned previously, the ftlist task will assume default values for any hidden parameters.

One can override the default value of a hidden paramter in one of three ways: 1) by specifying the new value on the command line, 2) by using the pset command, or 3) by editing the par file.

In the first method, the specification of the hidden parameters must follow any required parameters that also are given on the command line, as in:

ftlist rate.fits HC outfile=rate.txt columns=RATE rows=1-100

This command supplies values for the first two parameters, just as in the previous example, and then specifies that the columns parameter should have the value RATE, and the rows parameter should have the value 1-100.

The second way to specify the value of any parameter, including the hidden parameters, is through the pset command, as follows:

pset ftlist

When this command is used, the user is prompted in sequence for the value of every parameter in the ftlist task. Finally, the user may specify the value of an individual parameter without being prompted for every parameter by specifying the name and the value of the parameter on the command line:

pset ftlist separator="|"

This example sets the column separator parameter in the ftlist task to the pipe character "|". Note that the pset command does not execute the task, but instead sets the default parameter values for the next time that the task is run.

Useful Links

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