---

12.3.11.6 FITS tables ¶

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.

Function:
void
gal_fits_tab_size (fitsfile *fitsptr, size_t *nrows, size_t *ncols) ¶

Read the number of rows and columns in the table within CFITSIO’s fitsptr.

Function:
int
gal_fits_tab_format (fitsfile *fitsptr) ¶

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_AFITS or 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.

Function:
gal_data_t *
gal_fits_tab_info (char *filename, char *hdu, size_t *numcols, size_t *numrows, int *tableformat, char *hdu_option_name) ¶

Store the information of each column in hdu of filename into 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 numrows points to. The format of the table (e.g., FITS binary or ASCII table) will be put in tableformat (macros defined in Table input output (table.h)). For more on hdu_option_name see the description of gal_array_read in Array input output.

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 array or 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)).

Function:
gal_data_t *
gal_fits_tab_read (char *filename, char *hdu, size_t numrows, gal_data_t *colinfo, gal_list_sizet_t *indexll, size_t numthreads, size_t minmapsize, int quietmmap, char *hdu_option_name) ¶

Read the columns given in the list indexll from a FITS table (in filename and HDU/extension hdu) into the returned linked list of data structures, see List of size_t and List of gal_data_t. For more on hdu_option_name see the description of gal_array_read in Array input output.

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 minmapsize and quietmmap, see the description under the same name in Generic data container (gal_data_t).

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).

Function:
void
gal_fits_tab_write (gal_data_t *cols, gal_list_str_t *comments, int tableformat, char *filename, char *extname, gal_fits_list_key_t *keywords, int freekeys) ¶

Write the list of datasets in cols (see List of gal_data_t) as separate columns in a FITS table in filename. If filename already exists then this function will write the table as a new extension called extname, after all existing ones. The format of the table (ASCII or binary) may be specified with the tableformat (see 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.

In case your table needs metadata keywords, you can use the listkeys and freekeys. For more on these, see the description of gal_fits_key_write_in_ptr.

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).