Institut für Astronomie und Astrophysik Abteilung Astronomie Sand 1, D-72076 Tübingen, Germany

Table of Contents

• Introduction
• Index of Subroutines

Introduction

The IDL Astronomy Library contains a variety of procedures for reading, writing, and modifying FITS files. Information on how to use these procedures is given in http://idlastro.gsfc.nasa.gov/fitsio.html and is also briefly described here. There are four main types of FITS I/O procedures available in the Library:

1. 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). Further information on MRDFITS is available in the Appendix below.
2. The procedure READFITS can be used to read FITS headers and arrays into IDL variables. Additional procedures in the 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 interpret FITS Binary table. The procedure WRITEFITS can be used to write a primary image, ASCII extension, or image extension (see the Appendix). The READFITS/WRITEFITS software currently cannot read variable length binary tables, or write any type of binary table.
3. The directory fits_bintable contains IDL procedures for FITS I/O written by Bill Thompson (Goddard/ARC). This software can be used to read or write all types of FITS images and binary tables. The one limitation of these procedures is that they do not handle ASCII tables. Further information on these procedures is available in the LaTeX file fits_bintable.tex in the /text directory.
4. 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 on the Hubble Space Telescope (HST). These procedures are especially efficient for FITS files with many extensions, and they also recognize conventions used in HST FITS files that are not part of the standard FITS definition. Like READFITS/WRITEFITS, these procedures require further processing of binary and ASCII table, 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. Besides the four main categories above, other FITS procedures are available to read/write FITS files on tape, or to convert between FITS and the STSDAS format (.hhh and .hhd files) used for HST data. (See pro/sdas/README for info on the STSDAS format.) This README file should be monitored for improvements in the FITS I/O package. A FITS header is a string array with 80 characters per line. Using 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.

   The procedures FITS_INFO and FITSDIR use the non-standard system variables !TEXTUNIT and !TEXTOUT. These can be added to one's session using the procedure ASTROLIB.

   The available FITS I/O routines can be summarized as follows:

   1. Disk FITS <====> IDL variables
      
      • The procedure MRDFITS is a very generalized FITS reader that can read almost any type of FITS file, including random groups, and variable length binary tables. ASCII and binary columns are directly mapped into the tags of an IDL structure. MWRFITS() will write an IDL structure to a FITS file.
      • READFITS() will read a disk FITS file into IDL data and header arrays. It can handle REAL*4 and REAL*8 data and extensions but not random group FITS. READFITS() also has STARTROW and NUMROW keywords to read selected rows from a primary image or extension. Under Unix, READFITS() can directly read a gzip or Unix compress file. ASCII and binary tables require further processing with the FT* and TB* procedures in the fits_bintable directory. In particular, FTAB_EXT can be used to extract IDL vectors from a FITS binary or ASCII table.
      • WRITEFITS will write an IDL data and header array to a disk FITS file. It can handle all valid FITS formats except random groups. Use the /APPEND keyword to WRITEFITS to add a FITS extension to an existing FITS file (see the Appendix).
      • The procedure HEADFITS() can be used to read just the FITS header.
      • The procedure FXREAD in fits_bintable can be used as an alternative to READFITS for reading a primary array. It is a procedure rather than a function and has the ability to read a subarray or every nth pixel from the primary FITS array. The procedure FXWRITE in fits_bintable can be used as an alternative to WRITEFITS.
      • The procedure FITS_INFO displays info about FITS file(s) in a directory. The info include the number of extensions, and the size and type of each header or array. The procedure FITSDIR displays selected keywords from the primary headers in a set of FITS files.
      • The procedure RDFITS_STRUCT will read an entire FITS file into an IDL structure. Each header, image or spectra, or table is placed into a separate structure tag.
   2. FITS Tape <=====> Disk FITS
      The procedures FXTAPEWRITE and FXTAPEREAD are no longer available.

      Alternatively, a Unix FITS tape file can be copied to disk using dd, (as in dd if=/dev/tape of=file.fits bs=2880).

   ---

   MRDFITS - A multiple format FITS reader. V2.0

   The MRDFITS utility is intended to be a general purpose function allowing users to quickly read FITS files in all standard formats. MRDFITS returns an array or structure containing the data from the specified FITS extension. Header information may optionally be returned as a string array. MRDFITS currently supports the following FITS data types:
   • Primary simple images
   • The IMAGE extension
   • Group data in both primary images and IMAGE extensions.
   • ASCII tables
   • BINARY tables including the suggested convention for variable length records.
   MRDFITS uses the dynamic structure definition capabilities of IDL to generate a structure matching the characteristics of the FITS data and then reads the data into the structure. Some tailoring of the FITS data is possible:
   • A specified range of data may be retrieved.
   • The data may be scaled to FLOAT or DOUBLE values as controlled by the BSCALE (TSCALE) and BOFFSET (TZERO) keywords. Note that the default is no scaling.
   • Only a subset of the columns may be retrieved for ASCII and binary tables.
   MRDFITS is called as a function similar to the old READFITS utility, e.g.,

       str = mrdfits(file, exten_no, header)
   

   where file is a file name, exten_no is the extension to be read (0 for the primary data array) and header is an optional variable in which the header information will be stored. A number of optional keyword parameters are available:

       /FSCALE and /DSCALE  cause scaling to single and double precision.
       COLUMNS=         allows users to specify the columns desired.
       RANGE=           allows users to retrieve only some rows.
       STRUCTYP=        gives the structure type for the structure
       TEMPDIR=         gives the directory for temporary files
       /SILENT          suppresses informative messages
       /USE_COLNUM          makes tag names of the form C#
       /NO_TDIM             disable processing of TDIM keywords.
       ERROR_ACTION=        action specified in on_error
   

   MRDFITS uses the EXECUTE function where possible but creates temporary procedures when complex structures are needed. The MRD_STRUCT function is used for the dynamic definition of structures.

   MRDFITS is largely a standalone utility, but does use the parameter parsing of FXPAR to find elements in a header. All I/O is done within MRDFITS. The IEEE_TO_HOST routine is called for to convert data to the local representation.

   Known limitations include:

   • No special handling is done for NULL values.
   • Note that MRDFITS is not a FITS checker. It may read in files that are not proper FITS since only a few FITS elements needed by the reader are actually explicitly checked. MRDFITS should read in all correct FITS files and I would appreciate copies of any correct FITS files that break the reader. MRDFITS seems to be somewhat stricter about compliance to FITS standards than some of the other IDL FITS readers. This may be good or bad depending upon your needs.

   On Unix systems MRDFITS can handle files compressed with either the `standard' Unix compress utility or with the Gnu gzip utility. It assumes that files ending with .Z, .gz and .GZ are to be decompressed. Decompression is done using a sub-process and pipes so that no temporary file is created. In the future I anticipate implementing decompression on other architectures but the process will likely involve temporary files.

   V2.0 of MRDFITS includes the following enhancements:

   • Handles FITS tables with an arbitrary number of columns.
   • Substantial changes to MRD_STRUCT to allow the use of substructures when more than 127 columns are desired.
   • All references to table columns are now made through the functions MRD_GETC and MRD_PUTC. See description above.
   • Use of SILENT will now eliminate compilation messages for temporary functions.
   • Bugs in handling of variable length columns with either a single row in the table or a maximum of a single element in the column fixed.
   • Added support for DCOMPLEX numbers in binary tables (M formats) for IDL versions above 4.0. Should still handle them the old way for previous versions.
   • Created regression test procedure to check in new versions.
   • Added error_action parameter to allow user to specify on_error action. This should allow better interaction with new CHECK facility. ON_ERROR statements deleted from most called routines.
   • Modified MRDFITS to read in headers containing null characters with a warning message printed.
   Please send comments and bug reports to:

       Tom McGlynn
       Compton Observatory Science Support Center
           mcglynn@grossc.gsfc.nasa.gov
       301-286-7743
   

   ---

   Writing an IMAGE Extensions with WRITEFITS

   The format of a FITS IMAGE extension duplicates that of a primary FITS array. Thus, unlike binary or ASCII tables extensions, a FITS IMAGE extension does not require any further interpretation after it has been read by READFITS with the EXTEN keyword. A FITS extension can be added to an existing FITS file by using WRITEFITS with the /APPEND keyword. Users need to make sure that (1) the primary FITS header includes an EXTEND keyword, and (2) the required keywords of the IMAGE extension header match those described in the defining document. One way to make sure that these criteria are met is to use the /EXTEND and /IMAGE keywords of the MKDHR procedure.

   For example, to create a FITS file with a dummy primary header (i.e. no primary array) and two IMAGE extensions containing the IDL arrays "im1" and "im2" to a file 'TEST.FITS'

           IDL> mkhdr,h,'',/EXTEN        ;Create a dummy header (NAXIS=0) and
                                         ;include an EXTEND keyword
   
       IDL> writefits,'test.fits','',h     ;Write the header to disk
                                               ;Since there is no primary image
                                               ;it is set to ''
   
       IDL> mkhdr,h1,im1,/IMAGE      ;Make a minimal IMAGE extension header h1
                                         ;appropriate to the array im1 using
                                         ;Additional header keywords can be added
                                         ;using SXADDPAR
   
   
       IDL> writefits,'test.fits',im1,h1,/app  ;Append to existing FITS file
   
           IDL> mkhdr,h2,im2,/IMAGE       ;Create IMAGE header for im2
   
       IDL> writefits,'test.fits',im2,h2,/APPEND    ;Append second extension
   

   
   

   ---

   
   

   Index of Subroutines

   CHECK_FITS	Check that keywords in a FITS header array match the associated data
   FITS_ADD_CHECKSUM	Add or update the CHECKSUM and DATASUM keywords in a FITS header
   FITS_ASCII_ENCODE()	Encode an unsigned longword as an ASCII string to insert in a FITS header
   FITS_CLOSE	Close a FITS data file
   FITS_HELP	To print a summary of the primary data units and extensions in a FITS file. ;
   FITS_INFO	Provide information about the contents of a FITS file
   FITS_OPEN	Opens a FITS (Flexible Image Transport System) data file.
   FITS_READ	To read a FITS file.
   FITS_TEST_CHECKSUM()	Verify the values of the CHECKSUM and DATASUM keywords in a FITS header
   FITS_WRITE	To write a FITS primary data unit or extension.
   FITSDIR	Display selected FITS keywords from the headers of FITS files.
   FITSRGB_to_TIFF	Combine separate red, green, and blue FITS images into TIFF format
   FXMOVE	Skip a specified number of extensions in a FITS file
   FXPOSIT	Return the unit number of a FITS file positioned at specified extension
   HEADFITS	Read a FITS (primary or extension) header into a string array.
   MKHDR	Make a minimal primary (or IMAGE extension) FITS header
   MODFITS	Modify a FITS file by updating the header and/or data array.
   MRD_HREAD	Reads a FITS header from an opened disk file or Unix pipe
   MRDFITS	Read all standard FITS data types into arrays or structures.
   MWRFITS	Write all standard FITS data types from input arrays or structures.
   RDFITS_STRUCT	Read an entire FITS file (all extensions) into a single IDL structure.
   READFITS	Read a FITS file into IDL data and header variables.
   SXADDHIST	Procedure to add HISTORY (or COMMENT) line(s) to a FITS header
   SXADDPAR	Add or modify a parameter in a FITS header array.
   SXDELPAR	Procedure to delete a keyword parameter(s) from a FITS header
   SXPAR	Obtain the value of a parameter in a FITS header
   WRITEFITS	Write IDL array and header variables to a disk FITS file.

   ---

   Last modified by pro2html on 2008 November 09 at 04:11 UTC

   ---

   [Home Page] [Software, Documentation] [IDL Documentation] [Quick Reference] [Feedback]

   Jörn Wilms (wilms@astro.uni-tuebingen.de)
   Updated automatically

   ---