fits_bintable.tex

basic median filter simulation

Note that, because the entire columns were read in, the arrays A, B, and C each
have an extra last dimension of 5.  Also, the same comment in
Section~\ref{creating} above about FXBCREATE and UNIT also applies to FXBOPEN.

The following routines support reading FITS binary table extensions:
\begin{quote}
\begin{description}
\item[FXBOPEN:]
Opens a FITS binary table extension for reading.  One can open several binary
tables at once, either in the same or different files, by specifying different
variable names for FXBOPEN to store the logical unit number into.
\item[FXBREAD or FXBREADM:]
Reads data from a column in a FITS binary table.  One can read an entire
column, a range of rows within a column, or a single row and column
combination.  FXBREADM can read multiple columns in a single call.
\item[FXBTDIM:]
Parses keywords from binary tables with a TDIM-like format.  See
Section~\ref{tdim} for more information.
\item[FXBHELP:]
Prints to the screen a simple table giving information about each of the
columns in the binary table.
\item[FXBFIND:]
Finds the values of keywords in the header associated with the binary table
columns.  For example, the command
\begin{quote}
\begin{verbatim}
fxbfind, header, 'TTYPE', columns, values, n_found
\end{verbatim}
\end{quote}
would return an array containing the values of the keywords TTYPE1, TTYPE2,
etc., the columns for which they were found, and how many were found.
\item[FXBCOLNUM:]
Returns the column number of a FITS binary table specified either as a number
or by name.
\item[FXBHEADER:]
Returns the header of a FITS binary table opened with FXBOPEN.  (Note that the
header can also be returned as an optional parameter of FXBOPEN.)
\item[FXBISOPEN:]
Returns whether or not a logical unit number points to a FITS binary table that
is open for read.
\item[FXBSTATE:]
Similar to FXBISOPEN, but returns a state variable denoting whether or not a
logical unit number points to an open FITS binary table, and if so whether that
table is open for read or for write.
\item[FXBCLOSE:]
Closes a FITS binary table that had been opened with FXBOPEN.
\end{description}
\end{quote}

\section{Modifying Existing FITS Binary Tables}

After a FITS binary table extension has been written, a subsequent
need may arise to modify or augment the table.  This may be required
if, for example, new data or corrections must be overwritten in a
pre-existing data file.  In general this is accomplished using the
standard procedures to write data to FITS columns, typically FXBWRITE
or FXBWRITM.  However, after a table extension has been created, it is
not possible to change its number of columns or the number of header
keywords.

Since the table has already been created, there is no need to call
FXBHMAKE or FXBADDCOL again.  An existing FITS table extension is
opened for write access using the FXBOPEN procedure with the ACCESS
keyword.
%
\begin{quote}
\begin{verbatim}
IDL> FXBOPEN,UNIT,'sample.fits','testext',header, ACCESS='RW'
\end{verbatim}
\end{quote}
%
The keyword value \verb|'RW'| indicates that the FITS file is both
readable and writable.  [ The default is \verb|'R'|, read-only. ]

After the table has be opened for writing, the FXBWRITE and/or
FXBWRITM procedures should be used to modify the desired columns.
Finally, FXBFINISH should be used to close the table.

\section{Enlarging an Existing FITS Binary Table}

After a FITS binary table has been created it may also be necessary to
increase the number of rows in the table.  As mentioned above, one
cannot change the number of columns.  The number of rows can be
changed to the new value \verb|NEW_NROWS| by using the following
FXBGROW procedure call.  .  FXBGROW is safe for variable-length tables.
%
\begin{quote}
\begin{verbatim}
IDL> FXBOPEN,UNIT,'sample.fits',1,access='RW'
IDL> FXBGROW,UNIT,HEADER, NEW_NROWS
IDL> FXFINISH,UNIT
\end{verbatim}
\end{quote}
%
Both the header and the unit must be passed to FXBGROW because both
disk and memory images of the header must be modified.  Also, be aware
that the number of rows in the table can never decrease by calling
FXBGROW.

\section{Tape I/O}

The following routines are for writing and reading FITS files to and from tape.
Each has a menu driven interface, so that the user only has to enter the name
of the routine itself, and everything else is prompted for.  Currently, these
routines are only supported under VMS and are only available in the /obsolete
directory of the IDL Astronomy Library
\begin{quote}
\begin{description}
\item[FXTAPEREAD:]
Reads FITS files from tape to disk.  This routine is for standard FITS tapes,
i.e. raw tape files separated by filemarks, with a blocking factor of \mbox{$N
\times 2880$}~bytes, where $N$ is between 1 and 10.  The selected files are
copied from tape to disk as a byte stream, without any conversion being
applied.
\item[FXTAPEWRITE:]
Writes FITS files from disk to tape.  This routine writes standard FITS tapes.
Optionally a user-selected keyword can be inserted into the primary header as
written to tape to store the filename of each FITS file.  Otherwise, the
selected files are copied from tape to disk as a byte stream, without any
conversion being applied.
\end{description}
\end{quote}

\section{Multidimensional Array Facility}
\label{tdim}

The routines described here provide direct support for the Multidimensional
Array Facility described in C\&T\@.  This convention uses keywords TDIM$n$ of
the format
\begin{quote}
TDIM$n$ = '($D_1$, $D_2$, \ldots)'
\end{quote}
to define the dimensions associated with column $n$.  For an example of the use
of this keyword, see the sample binary table header in Section~\ref{creating}
above.

Support for this convention is automatic---FXBADDCOL inserts TDIM$n$ keywords
into the header, and FXBOPEN interprets any found in the header---unless the
/NO\_TDIM keyword is used.  Values of TDIM$n$ can also be overridden with the
DIMENSIONS keyword in the FXBREAD routine.

In addition to the keywords described in the binary tables extension proposal,
several additional keywords are supported by FXBADDCOL.  These keywords have a
one-to-one correspondence with standard keywords used in primary FITS headers,
i.e.
\begin{center}
\begin{tabular}{cc}
Additional Keyword	& Standard Equivalent\\
\hline
			&	\\
TDMIN$n$		& DATAMIN \\
TDMAX$n$		& DATAMAX \\
			&	\\
TDESC$n$		& CTYPE$m$ \\
TROTA$n$		& CROTA$m$ \\
TRPIX$n$		& CRPIX$m$ \\
TRVAL$n$		& CRVAL$m$ \\
TDELT$n$		& CDELT$m$ \\
\end{tabular}
\end{center}
The anticipated use of these keywords is such that TDMIN$n$ and TDMAX$n$ would
have a ordinary FITS record format, no different from their standard
equivalents, and that the rest would have a format similar to TDIM$n$.

\section{Variable-Length Array Facility}

These routines also support the Variable-Length Array Facility described in
C\&T\@.  Variable-length array columns are defined by using FXBADDCOL with the
/VARIABLE keyword.  Other than that, support for variable-length arrays is
automatic.  Some operations, such as reading entire columns, and the
multidimensional array facility described above, are not allowed with
variable-length arrays.

Ordinarily, the default THEAP value \mbox{(NAXIS1 $\times$ NAXIS2)} is used to
write the variable-length arrays.  However, a different THEAP value can be used
by using FXADDPAR to insert the desired value into the binary table header
before calling FXBCREATE.

\section{IEEE Not-a-Number (NaN) Special Values}

Data dropout in FITS binary table arrays are signalled in one of two ways.
Dropouts in integer arrays are signalled with values specified by TNULL$n$
keywords.  However, dropouts in floating point arrays (including single or
double precision, and real or complex) are signalled with standard IEEE NaN
(not-a-number) special values.  The routine FXBREAD will optionally translate
these NaN numbers into a user-specified value, given by the NANVALUE keyword.
Conversely, the same keyword, when used with the FXWRITE or FXBWRITE routines,
will write out NaN for any points in the array with the value of the NANVALUE
keyword.

\section{Bit, Logical, and Double-precision Complex Arrays}

Prior to V4.0, IDL did not support a data type corresponding to double-precision
complex (type ``M'' in FITS binary tables).   Users with earlier versions of
IDL can still use these routines to read and write
double complex as ordinary double-precision arrays with an extra first
dimension of two.  Support for this is automatic when reading binary tables.
Columns can be defined as type ``M'' when writing binary tables if the
/DCOMPLEX keyword is passed to FXBADDCOL, and the data array is complex with
the first dimension being of size two.    For users with V4.0 or later,
these routines will recognize the double complex data type.

Bit arrays (type ``X'' in FITS binary tables) are treated in IDL as byte arrays
with approximately 1/8th the number of elements.  Support for this is automatic
when reading binary tables.  Columns can be defined as type ``X'' when writing
binary tables if the BIT keyword is passed to FXBADDCOL giving the number of
bits, and the data array is of type byte.  Dimension information is ignored for
bit arrays, since the dimensions apply to the bits, and not to the bytes that
IDL processes.

Logical arrays (type ``L'' in FITS binary tables) are treated in IDL as byte
arrays.  Support for this is automatic when reading binary tables.  Columns can
be defined as type ``L'' when writing binary tables if the /LOGICAL keyword is
passed to FXBADDCOL, and the data array is of type byte.

\section{Virtual Columns}

It is possible to treat keywords in binary table headers as if they were
columns in the table, with the same value replicated for every row.  This
virtual column convention allows the user to have a unified view in a table
regardless of whether the information is stored in a table column and thus
capable of varying from row to row, or stored in the header and thus the same
for every row.

To use the virtual column convention, the user must call FXBREAD with the
/VIRTUAL keyword, and must also reference the desired information by name
rather than by column number.  FXBREAD will then look first for a column with
that name.  If it doesn't find one, it then looks for a keyword with that name
in the header.

\section{Associated routines}

The remaining routines are mainly used internally by the other routines
mentioned above.
\begin{quote}
\begin{description}
\item[FXHCLEAN:]
Remove obsolete keywords---called by FXHMAKE, FXHBMAKE.
\item[FXPARPOS:]
Find position in FITS header---called by FXADDPAR.
\item[FXBFINDLUN:]
Find LUN in FXBINTABLE---called by FXBCREATE, FXBOPEN.
\item[FXBPARSE:]
Parse binary table header---called by FXBCREATE, FXBOPEN.
\item[FXBTFORM:]
Parse TFORM column descriptor---called by FXBPARSE.
\item[FXHREAD:]
Read FITS header---called by FXBOPEN.
\item[FXFINDEND:]
Find the last FITS record---called by FXBCREATE.
\item[WHERENAN:]
Find points equal to IEEE NaN---called by FXBREAD.
\item[BOOST\_ARRAY:]
Resize array, and append another array.
\item[STORE\_ARRAY:]
Resize array, and insert another array.
\item[DETABIFY:]
Removes tabs from strings.
\item[PRODUCT:]
Calculates total product of all elements of an array.
\item[FXTPIO\_READ:]
Reads a file from a tape---called from FXTAPEREAD.
\item[FXTPIO\_WRITE:]
Writes a file to a tape---called from FXTAPEWRITE.
\end{description}
\end{quote}

\section{Implementation notes}

The routines in this directory also make use internally of other routines from
the SDAS, FITS, and MISC directories from the Astronomy User's Library.  In
some cases these files are distributed along with the routines described here.

The file ``fxbintable.pro'' is an include file containing the definition of the
IDL common block FXBINTABLE.  This file must be in one of the directories
pointed to by the IDL search path parameter !PATH\@.  Normally, this is ensured
by keeping this file in the same directory with the IDL procedures found here.

\end{document}