skip to content
 
 

MRDFITS V2.21

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:

  • Primary simple images
  • The IMAGE extension
  • Group data in both primary images and IMAGE extensions.
  • ASCII tables
  • BINARY tables including variable length tables.
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.
  • - Automatic mapping into IDL unsigned data types (/UNSIGNED) when the appropriate BSCALE(TSCAL) and BZERO(TZERO) keywords appear in the header
  • - Variable length binary tables may be read either into a fixed length column (default) or into a IDL pointers (with /POINTER_VAR) for maximum efficiency
MRDFITS has been tested to work on IDL Version V6.4 through V8.2, 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.
  • ALIAS Specify translation of column names to structure tags
  • /FSCALE and /DSCALE cause scaling to single and double precsion.
  • COLUMNS= allows users to specify the columns desired.
  • RANGE= allows users to retrieve only a specified range of rows.
  • ROWS= allows users to retrieve only a specified vector of rows.
  • STRUCTYP= gives the structure type for the structure
  • /SILENT suppresses informative messages
  • /USE_COLNUM makes tag names of the form C#
  • /NO_TDIM disable processing of TDIM keywords.
  • /POINTER_VAR -set to use pointer arrays for variable length arrays
  • ERROR_ACTION Set the ON_ERROR action to this value
  • /UNSIGNED Convert to IDL unsigned integer type when possible
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:

  • 0 -> successful completion
  • -1 -> error
  • -2 -> end of file

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()
  • MRDFITS: The main function with some utilities.
  • MRD_ASCII: Code to handle ASCII tables.
  • MRD_TABLE: Code to handle BINARY tables.
  • MRD_IMAGE: Code to handle simple images and group data.
  • MRD_SCALE: Data scaling.
  • MRD_COLUMNS: Column selection.
The following procedures are in separate files (because they are of general use outside of MRDFITS.)
  • MRD_STRUCT: Dynamic structure definition.
  • FXMOVE: Skip a specified number of extensions in a FITS file.
  • FXPOSIT: Find an extension in a FITS file. Note that in Mar 2009, fxposit.pro was modified to open FITS files for "on the fly" byte swapping, and the current MRDFITS must be used with the current FXPOSIT
  • MRD_HREAD: Read a FITS header from an opened disk file or Unix pipe
  • MRD_SKIP Skip a number of bytes from the current location in a file or pipe
MRDFITS() also requires the following procedures from the IDL Astronomy Library: FXADDPAR , FXPAR() , FXPARPOS() , GETTOK() , and VALID_NUM() .
Last modified:20-Nov-2013
Please send comments and bug reports to: Wayne Landsman.