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 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 reading and writing their input/output tables. 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 (ASCII and binary) tables are supported by Gnuastro. However, the low-level table infra-structure is written such that accommodating other formats is also possible and in future releases more formats will hopefully be supported. Please don’t hesitate to suggest your favorite format so it can be implemented when possible.
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_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.
The display format used in C’s
printf to display data of different
_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:
For unsigned integers, it is possible to choose from
_OCTAL (octal notation, for example
in decimal will be displayed as
notation, for example
125 in decimal will be displayed as
For floating point, it is possible to display the number in
(floating point, for example
_GENERAL which is the best of
the two for the given number.
All the current acceptable table formats to Gnuastro. The
BFITS represent FITS ASCII tables and FITS Binary tables. You can
use these anywhere you see the
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.
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
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
hdu will not be used (can be
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.
This program will print the column information for all the columns (output
gal_table_info). The output is in the same format as this command
with Gnuastro Table program (see Table):
$ asttable --info table.fits
Read the specified columns in a text file (named
filename) into a
linked list of data structures. If the file is FITS, then
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.
colmatch!=NULL, it is assumed to be an array that has at least the
same number of elements as nodes in the
cols list. The number of
columns that matched each input column will be stored in each element.
Add some basic information to the list of
comments. This basic
information includes the following information
COMMITin Output headers).
time_tis C’s calendar time format defined in time.h). You can calculate the time in this format with the following expressions:
time_t rawtime; time(&rawtime);
program_string. If it is
NULL, this line is ignored.
cols (a list of datasets, see List of
gal_data_t) into a
table stored in
filename. The format of the table can be determined
tableformat that accepts the macros defined above. When
filename==NULL, the column information will be printed on the
standard output (command-line).
comments!=NULL, the list of comments (see List of strings)
will also be printed into the output table. When the output table is a
plain text file, every node of
comments will be printed after a
# (so it can be considered as a comment) and in FITS table they will
If a file named
filename already exists, the operation depends on
the type of output. When
filename is a FITS file, the table will be
added as a new extension after all existing extensions. If
is a plain text file, this function will abort with an error.
filename is a FITS file, the table extension will have the name
filename==NULL (columns are
printed in the standard output), the dataset metadata will also printed in
the standard output. When printing to the standard output, the column
information can be piped into another program for further processing and
thus the meta-data (lines starting with a
#) must be ignored. In
such cases, you only print the column values by passing
logll list of datasets into a table in
(see List of
gal_data_t). This function is just a wrapper around
quiet is non-zero, this function will print a message
saying that the
filename has been created.