GNU Astronomy Utilities


Next: , Previous: , Up: Gnuastro library   [Contents][Index]


10.3.11 Table input output (table.h)

Tables are a collection of one dimensional datasets that are packed together into one file. They are the single most common format to store high-level (processed) information, hence they play a very important role in Gnuastro. For a more thorough introduction, please see Gnuastro’s Table. Gnuastro’s Table program, and all the other programs that can read from and write into tables, use the functions of this section. For a simple demonstration of using the constructs introduced here, see Library demo - reading and writing table columns.

Currently only plain text (see Gnuastro text table format) and FITS tables are supported by Gnuastro. However, the low-level table infra-structure is written such that for other formats are also possible and in future releases more formats will be supported, please let us know your priorities so they get higher priorities.

Macro: GAL_TABLE_DEF_WIDTH_STR
Macro: GAL_TABLE_DEF_WIDTH_INT
Macro: GAL_TABLE_DEF_WIDTH_LINT
Macro: GAL_TABLE_DEF_WIDTH_FLT
Macro: GAL_TABLE_DEF_WIDTH_DBL
Macro: GAL_TABLE_DEF_PRECISION_INT
Macro: GAL_TABLE_DEF_PRECISION_FLT
Macro: GAL_TABLE_DEF_PRECISION_DBL

The default width and precision for generic types to use in writing numeric types into a text file (plain text and FITS ASCII tables). When the dataset doesn’t have any pre-set width and precision (see disp_width and disp_precision in Generic data container (gal_data_t)) these will be directly used in C’s printf command to write the number as a string.

Macro: GAL_TABLE_DISPLAY_FMT_STRING
Macro: GAL_TABLE_DISPLAY_FMT_DECIMAL
Macro: GAL_TABLE_DISPLAY_FMT_UDECIMAL
Macro: GAL_TABLE_DISPLAY_FMT_OCTAL
Macro: GAL_TABLE_DISPLAY_FMT_HEX
Macro: GAL_TABLE_DISPLAY_FMT_FLOAT
Macro: GAL_TABLE_DISPLAY_FMT_EXP
Macro: GAL_TABLE_DISPLAY_FMT_GENERAL

The display format used in C’s printf to display data of different types. The _STRING and _DECIMAL are unique for printing strings and signed integers, they are mainly here for completeness. However, unsigned integers and floating points can be displayed in multiple formats:

Unsigned integer

For unsigned integers, it is possible to choose from _UDECIMAL (unsigned decimal), _OCTAL (octal notation, for example 125 in decimal will be displayed as 175), and _HEX (hexadecimal notation, for example 125 in decimal will be displayed as 7D).

Floating point

For floating point, it is possible to display the number in _FLOAT (floating point, for example 1500.345), _EXP (exponential, for example 1.500345e+03), or _GENERAL which is the best of the two for the given number.

Macro: GAL_TABLE_FORMAT_INVALID
Macro: GAL_TABLE_FORMAT_TXT
Macro: GAL_TABLE_FORMAT_AFITS
Macro: GAL_TABLE_FORMAT_BFITS

All the current acceptable table formats to Gnuastro. The AFITS and BFITS represent FITS ASCII tables and FITS Binary tables. You can use these anywhere you see the tableformat variable.

Macro: GAL_TABLE_SEARCH_INVALID
Macro: GAL_TABLE_SEARCH_NAME
Macro: GAL_TABLE_SEARCH_UNIT
Macro: GAL_TABLE_SEARCH_COMMENT

When the desired column is not a number, these values determine if the string to match, or regular expression to search, be in the name, units or comments of the column meta data. These values should be used for the searchin variables of the functions.

Function:
gal_data_t *
gal_table_info (char *filename, char *hdu, size_t *numcols, size_t *numrows, int *tableformat)

Store the information of each column in a table (either as a text file or as a FITS table) into an array of data structures with numcols structures (one data structure for each column). The number of rows is stored in the space that numrows points to. The format of the table (e.g., ascii text file, or FITS binary or ASCII table) will be put in tableformat (macros defined above). If the filename is not a FITS file, then hdu will not be used (can be NULL).

Note that other than the character strings (column name, units and comments), nothing in the data structure(s) will be allocated by this function for the actual data (e.g., the ‘array’ or ‘dsize’ elements). This function is just for column information (meta-data), not column contents.

Function:
void
gal_table_print_info (gal_data_t *allcols, size_t numcols, size_t numrows)

This program will print the column information for all the columns (output of gal_table_info). The output is in the same format as this command with Gnuastro Table program (see Table):

$ asttable --info table.fits
Function:
gal_data_t *
gal_table_read (char *filename, char *hdu, gal_list_str_t *cols, int searchin, int ignorecase, int minmapsize)

Read the specified columns in a text file (named filename) into a linked list of data structures. If the file is FITS, then hdu will also be used, otherwise, hdu is ignored.

The information to search for columns should be specified by the cols list of strings (see List of strings). The string in each node of the list may be a number, an exact match to a column name, or a regular expression (in GNU AWK format) enclosed in / /. The searchin value must be one of the macros defined above. If cols is NULL, then this function will read the full table.

The output is an individually allocated list of datasets (see List of gal_data_t) with the same order of the cols list. Note that one column node in the cols list might give multiple columns (for example from regular expressions), in this case, the order of output columns that correspond to that one input, are in order of the table (which column was read first). So the first requested column is the first popped data structure and so on.

Function:
void
gal_table_comments_add_intro (gal_list_str_t **comments, char *program_string, time_t *rawtime)

Add some basic information to the list of comments. This basic information includes the following information

Function:
void
gal_table_write (gal_data_t *cols, gal_list_str_t *comments, int tableformat, char *filename, int dontdelete)

Write the cols list of datasets into a table in filename (see List of gal_data_t). The format of the table can be determined with tableformat that accepts the macros defined above. If comments!=NULL, then the list of comments will also be printed into the output table. When the output table is a plain text file, each node’s string will be printed after a # (so it can be considered as a comment). If filename already exists and dontdelete is not zero, this function will abort the program with an error.

Function:
void
gal_table_write_log (gal_data_t *logll, char *program_string, time_t *rawtime, gal_list_str_t *comments, char *filename, int dontdelete, int quiet)

Write the logll list of datasets into a table in filename (see List of gal_data_t). This function is just a wrapper around gal_table_comments_add_intro and gal_table_write (see above). If quiet is non-zero, this function will print a message saying that the filename has been created.


Next: , Previous: , Up: Gnuastro library   [Contents][Index]