GNU Astronomy Utilities


Previous: , Up: FITS files   [Contents][Index]


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

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

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

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. If the necessary space for each column is larger than minmapsize, don’t keep it in the RAM, but in a file in the HDD/SSD, 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 indexs 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)

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

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


Previous: , Up: FITS files   [Contents][Index]