Tables are one of the common formats of data that is stored in FITS files. Only one table may be stored in each FITS HDU/extension, but each table column must be viewed as a different dataset (with its own name, units and numeric data type for example). The only constraint of the column datasets in a table is that they must be one-dimensional and have the same number of elements as the other columns. The functions described here can be used to get the information of, read, or write columns into FITS tables.
Read the number of rows and columns in the table within CFITSIO’s
Return the format of the FITS table contained in CFITSIO’s
fitsptr. Recall that FITS tables can be in binary or ASCII
formats. This function will return
GAL_TABLE_FORMAT_BFITS (defined in Table input output (table.h)). If the
fitsptr is not a table, this function will abort the program with an
error message informing the user of the problem.
Store the information of each column in
an array of data structures with
numcols elements (one data
structure for each column) see Arrays of datasets. The total number
of rows in the table is also put into the memory that
to. The format of the table (e.g., FITS binary or ASCII table) will be put
tableformat (macros defined in Table input output (table.h)).
This function is just for column information. Therefore it only stores
meta-data like column name, units and comments. No actual data (contents of
the columns for example, the
dsize elements) will be
allocated by this function. This is a low-level function particular to
reading tables in FITS format. To be generic, it is recommended to use
gal_table_info which will allow getting information from a variety
of table formats based on the filename (see Table input output (table.h)).
Each column will be read independently, therefore they will be read in
numthreads CPU threads to greatly speed up the reading when there are many columns and rows.
However, this only happens if CFITSIO was configured with --enable-reentrant.
This test has been done at Gnuastro’s configuration time; if so,
GAL_CONFIG_HAVE_FITS_IS_REENTRANT will have a value of 1, otherwise, it will have a value of 0.
For more on this macro, see Configuration information (config.h)).
If the necessary space for each column is larger than
minmapsize, do not keep it in the RAM, but in a file in the HDD/SSD.
For more on
quietmmap, see the description under the same name in Generic data container (
Each column will have
numrows rows and
colinfo contains any further information about the columns (returned by
gal_fits_tab_info, described above).
Note that this is a low-level function, so the output data linked list is the inverse of the input indexes linked list.
It is recommended to use
gal_table_read for generic reading of tables, see Table input output (table.h).
Write the list of datasets in
cols (see List of
separate columns in a FITS table in
already exists then this function will write the table as a new extension
extname, after all existing ones. The format of the table
(ASCII or binary) may be specified with the
Table input output (table.h)). If
comments!=NULL, each node of the list
of strings will be written as a
COMMENT keywords in the output FITS
file (see List of strings.
This is a low-level function for tables. It is recommended to use
gal_table_write for generic writing of tables in a variety of
formats, see Table input output (table.h).