fits_bintable.tex

basic median filter simulation

\documentstyle[11pt]{article}

\setlength{\oddsidemargin}{0in}		%  1 inch (0 + 1) from left.
\setlength{\topmargin}{-0.5in}		%  1 inch (1.5 - 0.5) from top.
\setlength{\textwidth}{6.5in}		%  1 inch (8.5 - 1 - 6.5) from right.
\setlength{\textheight}{9in}		%  1 inch (11 - 1 - 9) from bottom.

\addtolength{\parskip}{0.5\baselineskip}

\begin{document}			% Remember to put in \end{document}.
\thispagestyle{empty}			% Don't number first page.

\begin{center}
{\Large\bf IDL Software for FITS Binary Tables}\\
\mbox{}\\
William Thompson\\
NASA Goddard Space Flight Center\\
2 July 1993\\
Modified W. Landsman 12 Aug 1997 \\
Modified C. Markwardt 10 Jan 2000
\end{center}

This software package was developed to support reading and writing FITS binary
table extensions.  The primary source for a description of the FITS binary
table extension is the document ``Binary Table Extension to FITS''
by W. D.  Cotton, D. Tody and W. Pence (1995, A\&AS, 113, 159).  This
information is also included  in the FITS standards document
``Definition of the Flexible Image Transport System (FITS)'' by Hanisch et al.
(2001, A\&A, 376, 359), and at the Web site \\
{\tt http://heasarc.gsfc.nasa.gov/docs/heasarc/fits.html}.  As well as routines
that are directly related to binary tables, there are also supporting routines
which allow the user to read and write primary FITS header and data units
(HDUs), and to copy FITS files to and from tapes.

\section{Primary FITS Header and Data Units}

Every FITS file must contain a primary Header and Data Unit (HDU).  This part
represents the most basic kind of FITS file.  It allows for the storage of an
array with NAXIS dimensions, but one can also have a primary HDU which only
consists of a header without any data (signaled in the header by setting
NAXIS=0).  All FITS extension HDUs, must then follow the primary HDU.

The following routines are for writing primary FITS header and data units.
They are listed in the order they would be used to create a basic FITS file to
which binary table extension could then be appended.
\begin{quote}
\begin{description}
\item[FXHMAKE:]
Creates the primary FITS header based on the array passed as an optional
parameter.  If no data array is passed, then a header array consistent with no
data in the primary HDU is created.  When appending FITS extensions, such as
binary tables, to the file, FXHMAKE should be called with the /EXTEND qualifier
to generate a header record that reads ``EXTEND=T'' (true).
\item[FXADDPAR:]
Adds keyword=value records to the primary header, or modifies those that are
already there.  The use of this routine is entirely at the user's
discretion---the required keywords are inserted by FXHMAKE.
\item[FXWRITE:]
Writes the primary header and (optional) data array to a FITS file on disk.
\end{description}
\end{quote}

There are a number of routines available to read and interpret FITS primary
HDUs.  For example, the IDL Astronomy User's Library, available at \\
{\tt http://idlastro.gsfc.nasa.gov/homepage.html}, contains a number of routines including
READFITS\@.  The following lists two routines included in this package to
support this function.
\begin{quote}
\begin{description}
\item[FXREAD:]
Reads a basic FITS file, or the primary HDU from a FITS file with extensions.
This routine can either read the entire array, or a sub-array.  It also gives
the user the option of reducing the amount of data read either by reading every
$n$th pixel, or by averaging together \mbox{$n \times n$} pixels.
\item[FXPAR:]
Extracts values from FITS headers.
\end{description}
\end{quote}

\section{Creating FITS binary table files}
\label{creating}

The processes of creating a FITS binary table file is fairly easy.  However,
there are enough individual steps involved in creating the file, that it is
anticipated that it will be carried out primarily using procedure files, rather
than interactively from the keyboard.

The routines used in writing FITS binary tables files are:
\begin{quote}
\begin{description}
\item[FXBHMAKE:]
Starts the definition of the FITS binary table header.  At this time the number
of rows in the table is defined, but no information about the individual
columns is as yet included.  Optionally, the extension is given a name.
\item[FXBADDCOL:]
Add the information about the columns to the binary table extension header.
This routine is called once for each column that will be in the table.
\item[FXBCREATE:]
Opens the FITS file that the binary table will be appended to and writes the
header.
\item[FXBWRITE or FXBWRITM:]
Writes the data into the binary table.  A separate call to FXBWRITE is
made for every row and and every column in the table.  FXBWRITM may be
used to write multiple rows and columns in a single call.
\item[FXBFINISH:]
Finishes up and closes the file containing the newly created binary table.
\end{description}
\end{quote}

The basic steps involved in creating a FITS binary table extension file are as
follows:
%
\begin{itemize}
\item
	First the primary FITS data unit must be created.  At the very minimum,
	this will include a FITS header with the keyword ``EXTEND'' set to
	T(rue).  It may also have data associated with it, or it may simply
	have ``NAXIS'' set to zero to signal that there is no primary data
	array.  This step is carried out through the FXHMAKE and FXWRITE
	routines.
\item
	Next, the binary table extension header must be created, and the
	various columns to be used have to be defined.  The routines FXBHMAKE
	and FXBADDCOL take care of this.
\item
	Then, the extension file must be opened, and the header written out.
	FXBCREATE takes care of this.
\item
	The next step is to actually write the data arrays themselves into the
	table.  This is done using multiple calls to FXBWRITE or one or more
	calls to FXBWRITM.
\item
	Finally, the table file is closed with the FXBFINISH command.
\end{itemize}

The following IDL statements demonstrate how to use these routines to create a
simple binary table with three columns and five rows.  Some test arrays are
generated to write into these columns, and are slightly modified for each row,
to make the test more complete.
%
\begin{quote}
\begin{verbatim}
;  Create the data to write to the binary table.
;
a = intarr(10,100)
b = reverse(intarr(20,100),2) - 100
c = fix(dist(50))
;
;  Create a primary header and write it out.
;
fxhmake,header,/initialize,/extend,/date
fxwrite,'sample.fits',header
;
;  Create a binary table extension header for a table with 5 rows.
;
fxbhmake,header,5,'TESTEXT','Test binary table extension'
;
;  Create the columns for the a, b, and c arrays.
;
fxbaddcol,acol,header,a,'Column 1'
fxbaddcol,bcol,header,b,'Column 2'
fxbaddcol,ccol,header,c,'Column 3'
;
;  Write out the extension header.
;
fxbcreate,unit,'sample.fits',header
;
;  Write out the data.  For each row, multiply the test arrays by the row
;  number.
;
for i=1,5 do fxbwrite,unit,a*i,acol,i
for i=1,5 do fxbwrite,unit,b*i,bcol,i
for i=1,5 do fxbwrite,unit,c*i,ccol,i
;
;  Same result is achieved with following call to FXBWRITM:
;  x = findgen(5) + 1
;  fxbwritm, unit, [acol, bcol, ccol], a*x, b*x, c*x
;
;  Close the binary extension.
;
fxbfinish,unit
end
\end{verbatim}
\end{quote}
%
The primary FITS header created by this routine is very simple, and looks like
this
%
\begin{quote}
\begin{verbatim}
SIMPLE  =                    T /Written by IDL:  30-Jan-1992 11:19:34.00
BITPIX  =                    8 /
NAXIS   =                    0 /
EXTEND  =                    T /File contains extensions
DATE    = '30/01/92'           /
END
\end{verbatim}
\end{quote}
%
And the binary table extension header looks like this
%
\begin{quote}
\begin{verbatim}
XTENSION= 'BINTABLE'           /Written by IDL:  30-Jan-1992 11:35:49.00
BITPIX  =                    8 /
NAXIS   =                    2 /Binary table
NAXIS1  =                11000 /Number of bytes per row
NAXIS2  =                    5 /Number of rows
PCOUNT  =                    0 /Random parameter count
GCOUNT  =                    1 /Group count
TFIELDS =                    3 /Number of columns
EXTNAME = 'TESTEXT '           /Test binary table extension
TFORM1  = '1000I   '           /Integer*2 (short integer)
TTYPE1  = 'COLUMN 1'           /Label for column 1
TDIM1   = '(10,100)'           /Array dimensions for column 1
TFORM2  = '2000I   '           /Integer*2 (short integer)
TTYPE2  = 'COLUMN 2'           /Label for column 2
TDIM2   = '(20,100)'           /Array dimensions for column 2
TFORM3  = '2500I   '           /Integer*2 (short integer)
TTYPE3  = 'COLUMN 3'           /Label for column 3
TDIM3   = '(50,50) '           /Array dimensions for column 3
END
\end{verbatim}
\end{quote}

One thing that sometimes confuses first time users is that UNIT is an output
parameter of FXBCREATE, not an input parameter.  One does not specify the
logical unit number for the file; instead FXBCREATE assigns one via a call to
GET\_LUN.  A similar situation exists in regard to the column number argument
to FXBADDCOL.  Column numbers are assigned in the order in which FXBADDCOL is
called.  In the above example, the values of acol, bcol, and ccol will be
returned by FXBADDCOL as 1, 2, and 3 respectively.

\section{Reading FITS binary table files}

The process of reading FITS binary tables is much simpler than writing them,
since the structure of the table is already set.  There are only three basic
steps in reading a FITS binary table file:
%
\begin{itemize}
\item
	The file is opened, and the binary table extension selected, with the
	routine FXBOPEN.
\item
	Data is read from the table with the routines FXBREAD or
	FXBREADM.  Using FXBREAD, a particular row and column can be
	read, or an entire column can be read into a single array
	(except for columns containing variable-length arrays).
	FXBREADM can read multiple columns in a single procedure call.
\item
	The file is closed with the routine FXBCLOSE.
\end{itemize}
%
For instance, the binary table created in the above example could be read with
the following statements.
%
\begin{quote}
\begin{verbatim}
IDL> FXBOPEN,UNIT,'sample.fits','testext',header
IDL> FXBREAD,UNIT,A,'Column 1'
IDL> FXBREAD,UNIT,B,'Column 2'
IDL> FXBREAD,UNIT,C,'Column 3'
IDL> FXBCLOSE,UNIT
IDL> HELP,A,B,C
A               INT       = Array(10, 100, 5)
B               INT       = Array(20, 100, 5)
C               INT       = Array(50, 50, 5)
\end{verbatim}
\end{quote}
%
In the above example the columns were read individually using three
calls to FXBREAD.  The same effect can be achieved by calling FXBREADM
in the following way.
%
\begin{quote}
\begin{verbatim}
IDL> FXBREADM,UNIT, ['Column 1', 'Column 2', 'Column 3'], A, B, C
\end{verbatim}
\end{quote}
%