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.
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:
Primary simple images
The IMAGE extension
Group data in both primary images and IMAGE extensions.
BINARY tables including variable length records.
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
- 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
- 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 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.
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
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
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
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.
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,
DOUBLE = Array
DOUBLE = Array
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
lun=fxposit(filename, 3) ;Open a FITS file and move to extension 3
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: 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.
MRDFITS() also requires the following procedures from the IDL Astronomy
Dynamic structure definition.
Skip a specified number of extensions in a FITS file.
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
a FITS header from an opened disk file or Unix pipe
a number of bytes from the current location in a file or pipe
Please send comments and bug reports to: