MRDFITS V2.17

The MRDFITS utility in the IDL Astronomy Library 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 was originally written by Tom McGlynn (NASA/GSFC) but is now maintained by Wayne Landsman.

MRDFITS currently supports the following FITS data types:

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: MRDFITS has been tested to work on IDL Version V6.1 through V7.1, Less capable versions of MRDFITS are available in earlier frozen versions of the IDL Astronomy Library.

MRDFITS is called as a function similar to the READFITS() utility, e.g.,

   str = MRDFITS(file_or_unit, exten_no_or_name, [ header] )
where file_or_unit is either a file name or the unit number of an open FITS file, exten_no_or_name is either the extension number to be read (0 for the primary data array), or the extension name (stored in the EXTNAME keyword), and header is an optional variable in which the header information will be stored. A number of optional keyword parameters are available. By default, MRDFITS uses the EXECUTE() function to create the dynamic structure but the use of EXECUTE() can be bypassed in IDL V6.1 or greater to allow use of MRDFITS() with the IDL virtual machine. The MRD_STRUCT() function is used for the dynamic definition of structures.

For calls from other programs, MRDFITS has an output STATUS keyword to indicate whether it was successful. A status of >=0 indicates a successful read. The returned status value has the following meanings:

One known limitation of MRDFITS is that 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 uses the /COMPRESS keyword to OPENR to allow it to read gzip'ed files on any machine architecture. MRDFITS can also read files (via a pipe to SPAWN) compressed with `standard' Unix compress utility, the Linux bzip2 utility, or the FPACK compression utility. MRDFITS assumes that files ending with .fz, .Z, .gz, .GZ and .bz2 are to be decompressed, but it also has the COMPRESS keyword so that the user can specify that any file is compressed.

The variable length array facility is a mechanism to save storage space, by allowing each row of an array to have a different length.   MRDFITS has two ways of handling such variable length arrays.    In the default (or /FIXED_VAR) method, the corresponding structure tag is dimensioned using the largest record.     A new "length" column is then added, giving the  actual length of each row of the variable length column.         For example, suppose the fifth column in a binary table with 3000 rows is a variable length  array named MATRIX, with a longest length of 27.   The default structure created by MRDFITS would have a tag named MATRIX  dimensioned  27 by 3000 containing the data, along with a tag named L5_MATRIX dimensioned LONARR(3000) containing the actual length (always less than or equal to 27)  of each row of MATRIX.        If the /POINTER_VAR keyword of MRDFITS is set, then the MATRIX tag is returned as an IDL pointer, and the data values for each row can be determined by dereferencing this pointer.   For example,

IDL> help,*str(0).matrix
<PtrHeapVar18001>
                DOUBLE    = Array[14]
IDL> help,*str(1).matrix
<PtrHeapVar18014>
                DOUBLE    = Array[27]

Instead of a file name, MRDFITS() can be given the unit number of an already opened FITS file. In this case, the EXTEN_NO parameter gives the number of extensions to skip *from the current location in the FITS file*. The use of a unit number instead of a file name is more efficient when multiple extensions of a FITS file are to be read. For example, to process all extension in a FITS file starting with the third one, one might do the following:

   lun=fxposit(filename, 3)      ;Open a FITS file and move to extension 3
   repeat begin
          thisHDU = mrdfits(lun, 0, hdr, status=status)
          ... process the HDU ...
   endrep until status lt 0
MRDFITS comprises several files. The following procedures are included in the main file MRDFITS() The following procedures are in separate files (because they are of general use outside of MRDFITS.) MRDFITS() also requires the following procedures from the IDL Astronomy Library: FXADDPAR , FXPAR() , FXPARPOS() , GETTOK() , and VALID_NUM() .
Last modified:20-Jul-2009
Please send comments and bug reports to: Wayne Landsman.