The column name token is a character string which is written to the FITS file as the value of the appropriate TTYPEn keyword. The FITS standard recommends that only letters, digits, and underscore be used in this field. Each column of the table should have a unique name.
The datatype token must conform to the FITS rules for the TFORM keyword for ASCII and binary tables, whichever is being created. The legal datatypes for FITS binary table extensions are:
rL - logical
rAw- character string of unit length w, and total width r
rX - On/Off bits
rB - unsigned 8-bit byte
rI - 16-bit integer
rJ - 32-bit integer
rK - 64-bit integer
rE - single precision floating point
rD - double precision floating point
rC - single precision complex value
rM - double precision complex value
where r is an optional numerical value giving the number of
elements in a vector column. Multi-dimensional arrays can be
produced by including a TDIMn keyword in the optional header
file (see below).
In the case of X columns, the maximum supported vector length depends on the compiler: in environments where the size of a C 'long' variable is 4 bytes, then the maximum vector length is 32; in environments where the 'long' variable is 8 bytes long, then the maximum vector length is 64. In both cases the value that is given in the data file should be the unsigned decimal or hex integer that has the equivalent binary bit pattern. For example, to set only the first bit in an 8X column, the binary value is 10000000 which is equivalent to decimal 128 or hex 0xA0. To set all 8 bits, the input value should be decimal 255 or hex 0xFF.
For strings, r is the full character width of the column (assumed 1 if not present) and w is the width of each element, so the number of elements is r/w. Without w, the column is treated as a single string of length r. This task supports up to a total of 999 elements per row. Note that variable length arrays are not currently supported by this task.
For FITS ASCII table extensions, the following formats are allowed:
Aw - character string,
Iw - integer
Fw.d - single precision, fixed decimal point
Ew.d - single precision, exponential notation
Dw.d - double precision, exponential notation
where 'w' is an integer specifying the width of the FITS table
field, and 'd' is the number of decimal digits to be
displayed. Vector columns and complex values are not allowed
in ASCII table extensions.
The units token is an optional character string that is written to the FITS file as the value of the appropriate TUNITn keyword; if it contains embedded spaces, then the whole token should be enclosed in quote characters. The value of NONE may be specified as a place holder (required if the following column position and width token are specified).
The column position and width tokens are optional integers which specify how to read the input data file using fixed format. These give the starting position of the column (beginning at 1) and the width of the column in the data file. For vector columns, the starting position points to the first element of the column and the width is that for each individual element; the elements must thus be consecutive and uniformly spaced within the data file. This also applies to complex number pairs. If position and width tokens are not specified for ALL the columns then the data file will be read in free format.
For fixed format data files each line of the data file corresponds to one row of the FITS table. Each line must contain a data value for every column of the table (and every element in a vector column) in the same order as given in the cdfile. Each line of the text file may be up to 30000 characters long and can contain a maximum of 999 data values per line. If there are more than 999 data values in each row of the table (e.g., if there are large vector columns in a binary table) then the values must be wrapped around on multiple lines of the data file using the free format described below.
For free format data files, each line of data may contain up to 999 data values; the data values for a single row of a FITS table may be wrapped around onto multiple rows of the ASCII template file, or multiple FITS table rows may be present on a single row of the template file. Ftcreate will continue reading values from subsequent rows until it reachs the end of the ASCII data file, or until 'nrows' lines of data have been read. If there is only a partial row of data at the end of the data file it will be ignored. Each line of the text file may be up to 30000 characters long and can contain a maximum of 999 data values per line.
Logical datatypes are represented by the letters T and F (or t and f). The datatype of numerical columns does not have to correspond to the datatype of the FITS column (e.g., integer vs. real) because this task will perform implicit datatype conversion if required. ASCII string data values may be enclosed in single quotes, but this is only required if the string contains embedded blanks. To include a single quote in the string, use two single quotes in a row. On/Off bits datatypes are represented by integer. The integer may be in decimal, octal(leading 0) or hexadecimal (leading 0x or 0X).
Any undefined elements in the input data file should be signified by the string 'INDEF' (with or without the quotes). These elements are represented in a floating point column in a FITS binary table with the IEEE Not-a-Number (NaN) value. If undefined values need to be written to integer columns in a binary table, or to any column in an ASCII table, then the the 'inull' or 'anull' parameters must also be defined.
The KEYNAME token must begin in columns 1-8 and be a maximum of 8 characters long. If the first 8 characters of the line are blank then the remainder of the line is considered to be a FITS comment (with a blank keyword name). A legal FITS keyword name may only contain the characters A-Z, 0-9, and '-' (minus sign) and '_' (underscore). This task will automatically convert any lowercase characters to uppercase in the FITS file. If KEYNAME = 'COMMENT' or 'HISTORY' then the remainder of the line is considered to be a FITS COMMENT or HISTORY record, respectively.
The VALUE token must be separated from the KEYNAME token by one or more spaces and/or an '=' character. The datatype of the VALUE token (numeric, logical, or character string) is automatically determined and the output FITS header record is formatted accordingly. Logical keyword values are represented by a T or F (not enclosed in quotes). The value token may be forced to be interpreted as a string (e.g. if it is a string of numeric digits) by enclosing it in single quotes.
The COMMENT token is optional, but if present must be separated from the VALUE token by at least one blank space. A leading '/' character may be used to mark the beginning of the comment field, otherwise the comment field begins with the first non-blank character following the value token.
ft> ftcreate coldesc.lis data.lis outtab.fits headfile=keywords.lis
The column description file (coldesc.lis) could contain:
name 12A
ra E degrees
dec E degrees
rank B
flag 8X
The data file (data.lis) could contain:
'Alpha Boot' 15.345 -12.346 3 0Xa9
Vega 123.225 39.245 7 031
'RR Lyrae' 34.46788 -36.9 1 12
The optional header file (keywords.lis) could contain:
INSTRUME ROSAT / name of instrument
OBS-DATE 2002-10-28 date of the observation
observer 'I. Newton' principle investigator
tempdet 98.6 / temperature of the detector
history This file was created with the ftools ftcreate task
2. Create a 100-row table with no columns in an output file called 'empty.fits'.
ft> ftcreate /dev/null /dev/null empty.fits nrows=100
3. Create a sine wave output file 'sine.fits' by piping example number 2 above to ftcopy.
ft> ftcreate /dev/null /dev/null - nrows=100 | \
ftcopy '-[col X=#ROW*0.1 + 10; Y = 12*COS(X);]' sine.fits
4. Create an output file 'random.fits' consisting of random points on the sky by piping example number 2 above to ftcopy. This example creates a table with 2 columns, "RA", and "Dec" which are filled with random coordinates on the sky. In addition, the TUNITn header keywords are written for each column.
ft> ftcreate /dev/null /dev/null - nrows=100 | \
ftcopy '-[col RA=random()*360.0;#TUNIT#="deg"; \
DEC=random()*180.-90.;#TUNIT#="deg"]' random.fits
The design of this task is based on the fcreate task in the ftools package.