FITS is a very well-established format for storage of astronomical table or image data (see https://fits.gsfc.nasa.gov/). This writer stores tables in a FITS file consisting of two HDUs (Header+Data Units): a Primary HDU as required by the FITS standard, and a single extension of type BINTABLE containing the table data.
There are a few variants of this format:
fits-basic, but columns containing variable-length numeric array data are stored using the
Qformats where appropriate, rather than padding smaller arrays to the size of the largest. This can make for more compact storage of variable-length array-valued column data but may also result in tables less suitable for streaming.
fits-basic, but it will rearrange and rename columns as required to follow the convention, and it will fail if the table does not contain the required HEALPix metadata (
fits-plus; in general you don't need to worry about this, it just gives you some hidden benefits over
A private convention is used where required to support encoding of tables with more than 999 columns (not possible in standard FITS); this was discussed on the FITSBITS mailing list in July 2017 in the thread BINTABLE convention for >999 columns. If software unaware of this convention (e.g. CFITSIO) is used to read such tables, it will only see the first 998 columns written as intended, plus a column 999 containing an undescribed byte buffer.
The handler behaviour may be modified by specifying
one or more comma-separated name=value configuration options
in parentheses after the handler name, e.g.
The following options are available:
date = true|false
Multiple tables may be written to a single output file using this format.
If no output format is explicitly chosen,
writing to a filename with
the extension "
.fits" or "
.fts" (case insensitive)
fits-plus format for output.
The handler classes for these formats are
To write the FITS header for the table extension, certain things
need to be known which may not be available from the
object being written; in particular the number of rows and the
size of any variable-sized arrays (including variable-length strings)
in the table. This may necessitate two passes through the data to
do the write.
To fix the value of the
TNULLn magic value for
a given column on output, set the value of the
auxiliary metadata value, e.g.:
colInfo.setAuxDatum(new DescribedValue(Tables.NULL_VALUE_INFO, new Integer(-99)));
Writing columns containing (scalar or array) unsigned byte values
TFORMnn = 'B') cannot be done simply by providing
byte data to write, since the java byte type is signed.
To do it, you must provide a column of java
(16-bit) integers, and set the value of the
auxiliary metadata item to
colInfo.setAuxDatum(new DescribedValue(Tables.UBYTE_FLAG_INFO, Boolean.TRUE));
Writing columns containing (scalar or array) unsigned long values
cannot be done straightforwardly, since, like FITS, the Java long
type is signed.
Instead, you can provide a column of java
giving the integer representation of the numbers required,
and set the value of the
auxiliary metadata item to the string representation of the offset 2**63,
colInfo.setAuxDatum(new DescribedValue(BintableStarTable.LONGOFF_INFO, "9223372036854775808263"));This will result in the values being written, where in range, with FITS headers
TFORMnn = 'K',
TZEROnn = '9223372036854775808263'. The same mechanism can be used for other long offsets if required (though not for other integer types).
See the "Binary Table Extension" section of the FITS standard for more details of the FITS BINTABLE format. These handler can write tables with more than the BINTABLE limit of 999 columns, as discussed in Section 3.8.2.
There is some support for the semi-standard
If some of the
HPX_*_INFO metadata items defined by the class
HealpixTableInfo are present
in the output table's parameter list,
the corresponding HEALPix-specific FITS headers will be written
on a best-efforts basis into the output BINTABLE HDU.
This may or may not be good enough to make that FITS file readable by
external HEALPix-FITS-aware applications; one of the requirements
of the convention is that the HEALPix pixel index, if present,
appears in the first column of the table under the name "
An alternative is to use the handler
which tries harder to write tables using the HEALPix convention.
This will fail unless the required
items mentioned above are present, and will reorder and rename
columns as required for maximum compatibility.
For column-oriented FITS output, see Section 3.7.2.