FITS I/O in the IDL Astronomy Library

Briefly, a FITS file consists of a sequence of one or more Header and Data Units (HDUs). A header is composed of ASCII card images that in IDL is usually read into a string array variable. The header describes the content of the associated data unit, which might be a spectrum (IDL vector), an image (IDL array), or tabular data in ASCII or binary format (often read as an IDL structure). Image and vector data can be present in any HDU, but tabular data cannot appear in the first HDU. The HDUs following the first (or primary) HDU are also known as extensions, and thus a FITS file containing tabular data must contain at least one extension. 

The IDL Astronomy Library contains four different sets of procedures for reading, writing, and modifying FITS files. The reason for having four different methods of FITS I/O with IDL is partly historical, as different groups developed the software independently. However, each method also has its own strengths and weakness for any particular task. For example, the procedure MRDFITS() -- which can read a FITS table into an IDL structure --is the easiest procedure for analyzing FITS files at the IDL prompt level (provided that one is comfortable with IDL structures). But mapping a table into an IDL structure includes extra overhead, so that when performing FITS I/O at the procedure level, it may be desirable to use more efficient procedures such as FITS_READ and FTAB_EXT.

The four classes of IDL FITS I/O procedures are briefly described below, along with the strengths and possible drawbacks of each method.    Note that all methods can read gzip compressed FITS files.

1. MRDFITS()/MWRFITS:

   MRDFITS() will read all standard FITS data types into IDL arrays (for primary images and image extensions) or structures (for binary or ASCII tables). The procedure MWRFITS() will write an IDL structure to a FITS file, with many options available (binary or ASCII table, default generation of column names). These procedures were written by Tom McGlynn (USRA/Goddard). The use of these procedures is described in their documentation header, with further information on MRDFITS available online.

   Strengths: These procedures are easy to use and remember-- the MRDFITS() procedure can read any type of FITS file into a single IDL structure variable, which is then available for further IDL processing. MRDFITS() has a long history of use, and has been tested with many FITS files. MRDFITS can read Unix, bzip2 and FPACK compressed files. Options are available to read/write IDL unsigned data types, and to map variable length binary tables into IDL pointers.

   Drawbacks: Mapping an entire FITS table extension into an IDL structure can incur extra CPU and virtual memory overhead if one is not  interested in all the columns. The application of TSCAL/TZERO keywords is not flexible, and the user must specify all scaling as either floating point or double precision.

   The procedures MRDFITS() and MWRFITS make use of the following procedures from the IDL Astronomy Library: FXADDPAR , FXPAR(), FXPARPOS() , FXMOVE() , FXPOSIT() , GETTOK() , MRD_HREAD, MRD_SKIP , MRD_STRUCT() , and VALID_NUM()

2. READFITS()/WRITEFITS:

   READFITS() can be used to read FITS headers and arrays of a specified extensions into IDL variables. Additional procedures in the pro/fits_table directory are then required to interpret binary and ASCII tables. The FT* procedures in the /fits_table directory are used to interpret a FITS ASCII table, and the TB* procedures are used to interpret a FITS Binary table. The procedure WRITEFITS , can be used to write a primary image, ASCII table extension (when used with the FT* procedures), or image extension.

   Strengths: Due to its long history, both READFITS() and WRITEFITS have undergone extensive testing. For FITS files that do not contain tables or many image extensions, READFITS() and WRITEFITS   are as simple and fast as any other method.     READFITS() can be used  to read Unix, bzip2 and FPACK compressed files.

   Drawbacks: READFITS() currently cannot be used to read variable length binary tables, and WRITEFITS cannot be used to create any type of binary table. Interactive use of READFITS() with FITS tables is somewhat awkward, with the user required to supply (e.g. to FTGET() or TBGET()) a header array and a data array as separate IDL variables.

   READFITS() requires the following supporting procedures: GETTOK() , MRD_SKIP , STRNUMBER() , SXADDPAR , SXDELPAR , SXPAR() , and VALID_NUM()

   WRITEFITS requires the following additional supporting procedures: BREAK_PATH , CHECK_FITS , DAYCNV , FIND_WITH_DEF , FXPAR() , FXPARPOS() , FXPOSIT , GET_DATE , MRD_HREAD, , MKHDR , and STRN()

3. FX* Procedures:

   The directory pro/fits_bintable contains IDL procedures for FITS I/O originally written by Bill Thompson (ARC/Goddard) and used by the SOHO project. This software can be used to read or write all types of FITS images and binary tables. Further information on these procedures is available in the LaTeX file fits_bintable.tex. In November 1999, C. Markwardt added the procedures FXBWRITM and FXBREADM which can greatly improve the speed of the FX* procedures for FITS files without variable length binary tables, by writing and reading multiple FITS binary columns in a single call.

   Strengths: These are the most complete and well-tested IDL procedures for writing binary tables. Extensions can be specified by the EXTNAME keyword.

   Drawbacks: The FX* procedures do not handle ASCII tables. The coding is usually more involved than with the other FITS I/O procedures.

4. FITS_* and FTAB_* Procedures:

   The five procedures FITS_CLOSE, FITS_HELP, FITS_OPEN, FITS_READ, and FITS_WRITE were written by D. Lindler (ACC/Goddard) and are used by the STIS/NICMOS instrument teams for the Hubble Space Telescope (HST). Like READFITS/WRITEFITS, these procedures require further processing of binary and ASCII tables, by using procedures in the /fits_table directory. In particular, the procedure FTAB_EXT uses FITS_READ to provide a quick and easy extraction of FITS ASCII or Binary tables into IDL vectors.

   Strengths: The FITS_* procedures are the most efficient way to process FITS files with many extensions. These are the only IDL procedures to recognize the STScI Inheritance Convention.      They allow specification of an extension by the value of the EXTNAME keyword. FITS_READ() can be used  to read Unix, and FPACK compressed files

   Drawbacks: No easy capability for creating binary tables, or for reading variable length binary tables. Because the entire FITS file is always parsed, the procedure can be slow when only one extension is needed. The procedure is slow for gzip'ed FITS files, and FITS files cannot be read from a Unix pipe or an internet socket.

• FITS_INFO or FITS_HELP: Display information about FITS file(s) in a directory, including the number of extensions, and the size and type of each header or array. FITS_HELP has a nicer format but only does one file at a time.
• FITSDIR: List selected keywords from the primary or extension headers of a set of FITS files.
• FXADDPAR or SXADDPAR: Add or modify a keyword in a FITS header.
• FXPAR() or SXPAR(): Return the value of a keyword in a FITS header.
• HEADFITS(): Read just the FITS header (of a specified extension) into an IDL string array.
• HGREP: Find a substring in a FITS header or other string array.
• HPRINT: A FITS header is a string array with 80 characters per line. On many terminals, use of the IDL PRINT command to display the header will result in a space between every line. The HPRINT procedure will display a FITS header without this extra space, and includes options to display only specified lines of a header.
• MKHDR or FXHMAKE: Create a minimal FITS header to match a specified data variable
• MODFITS: Modify a FITS file by updating the header and/or data array.
• RDFITS_STRUCT will read an entire FITS file into an IDL structure. Each header and data array of every extension is placed into a separate structure tag. Note that individual table columns are not parsed into separate tags, so that this procedure is less generally useful than MRDFITS().
• SXDELPAR: Delete a specified keyword in a FITS header

Miscellaneous Notes: