Read a single image (multi-dimensional array) or binary table
from a FITS file. The source code readFITS.r is a model for
creating code to read more complex FITS files.
Position of Header and Data Unit (HDU) in FITS file: 1 for
the first HDU, 2 for the second HDU, etc.
maxLines
Integer: maximum number of header lines to read.
fixHdr
Deal with (illegal) nonprinting characters in the
header.
phdu
Rarely needed; see Details.
Details
readFITS is a simple but complete FITS file reader,
automatically detecting image and binary table data extensions
(ASCII tables and random groups are
not supported in this
release). It reads a single Header and Data Unit
(HDU) pair from a file and returns a list with data, header, and axis
information. Files with more complicated structures or
isolated header units can be read with an appropriate combination of
readFITSheader, readFITSarray, and
readFITSbintable. See the Example section for
readFITSimage for a step-by-step
example that includes file opening and closing.
phdu = 0 forces a read of a secondary HDU in a
fairly pathological case (specifically: indicating
a read of a secondary HDU by setting NAXISn = 0 for n > 1, but NAXIS != 0
and NAXIS1 != 0.) This does not seem to be forbidden by the FITS
standard but would be unlikely coding.
... passes additional values for file reading. The only use at
present is to pass values to fixHdr in readFITSheader.
fixHdr attempts to fix headers with non-printing characters,
either by removing them with fixHdr = 'remove', reading further
into the file until 2880 valid characters are present, or by
substituting spaces for non-printing characters with fixHdr =
'substitute'. This option should be used with caution, as non-printing
characters should not be in the header in the first place, so this
option may or may not corrupt the following data. The default is
fixHdr = 'none'. Partial matching is allowed.
Binary table bit, complex, and array
descriptor data types are not implemented in this release due to a lack
of examples for testing.
Value
Return values from readFITS are in a list. Depending on the
data type, list entries are:
header
Vector with input file header up to END statement.
hdr
Vector with keyword = value pairs parsed from header.
imDat
Data array (image).
axDat
Data frame with axis scaling and labels (image).
col
Data from each column (bintable).
colNames
Vector of column names, TTYPEn FITS variable (bintable).
colUnits
Vector of column units, TUNITn FITS variable (bintable).
TNULLn
Vector of undefined value definitions, FITS variable
(bintable).
TSCALn
Vector of multipliers for scaling, FITS variable (bintable).
TZEROn
Vector of zeros for scaling, FITS variable (bintable).
TDISPn
Vector of format information, FITS variable (bintable).
Note
Graphical FITS viewers such as fv
(http://heasarc.gsfc.nasa.gov/ftools/fv/) and SAOImage DS9
(http://hea-www.harvard.edu/RD/ds9/)
have excellent facilities for displaying FITS data, headers, and file
structure. Having one or more graphical viewers available will
prove extremely
useful
for working with FITS
files, even when the data are read into R for further processing.
fv and SAOImage DS9 are in active development
with support for
unix, Windows, and Mac OS-X operating systems, and are available at no cost.
See readFrameFromFITS to read a binary table
directly into an R data frame.
Author(s)
Andrew Harris
References
Hanisch et al., Astron. Astrophys. 376, 359-380 (2001)