NAME

ftcreate - Create a FITS table extension from ASCII files describing the format and content of the table.

USAGE

ftcreate cdfile datafile outfile

DESCRIPTION

This task creates a new FITS file containing a table extension (either ASCII or binary) by reading two ASCII format files containing (1) a description of the table column formats and (2) the data contents of the table. Optionally, a third ASCII file may be specified (with the headfile parameter) which lists additional keywords to be added to the header of the FITS table. Options are provided to skip a specified number of rows at the beginning of the data file and to process only a specified number of rows in the data file. By default all the rows will be processed and written to the FITS table. The data file may be read either in free format (default) or fixed format.

PARAMETERS

cdfile = "" [filename]
The name of the input column description file. This is a free-format ASCII text file containing one line for each column (up to 999 columns) in the FITS table to be created. Each line contains up to 5 values (tokens) specifying the attributes of the particular column: column name, datatype, units, column starting position, and column width. Every line must have a column name and a data type token; the other three tokens are optional. Column names and units are case sensitive, but the data types are not.

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.

datafile = "" [filename]
The name of the input ASCII formatted data file which is to be processed and copied to the FITS table. If datafile="-", the data will be read from STDIN. Any blank lines or lines beginning with '#' in the data file will be ignored. The file may be in either fixed or free format. The data file will be read in free format unless the column starting position and width have been specified for every column (see the 'cdfile' parameter description).

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.

outfile [filename]
The name of the output FITS file. The FITS file will have an empty primary array followed by an ASCII or binary table extension (as specified by the 'tbltype' parameter).

headfile [filename]
The name of the optional file of header keywords. Each line of this file defines one keyword, except that blank lines and lines beginning with # will be ignored. Each line should usually contain three tokens: (1) the KEYNAME,(2) the VALUE, and (3) the COMMENT string and must adhere to the following format rules:

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.

(tbltype = "binary")
Type of FITS table extension: binary or ASCII.

(nskip = 0)
Number of rows at the beginning of the data template file to skip inclusive of any blank rows or rows beginning with '#'.

(nrows = 0)
No. of rows in the data template file to read inclusive of any blank rows or rows beginning with '#'. If nrows = 0 (the default) then the entire table will be read.

(morehdr = 0)
Reserve space in the FITS header for this many more keywords to be added at a later time. One can always add more keywords to a FITS file, but it is more efficient to reserve space for them in advance, rather than having to create more space later on.

(extname = "")
Name for the output FITS extension, i.e., the value written to the EXTNAME keyword.

(anull = "")
The string to be used to represent undefined data values in any column of an ASCII table. If this parameter is not set to a blank (default) then the appropriate TNULLn keyword will be added to the FITS file header for all the columns. This parameter should only be defined if the data actually contains undefined values (represented by "INDEF" character string).

(inull = 0)
The value to be used to represent undefined data values in any integer column (data type = B, I, or J) in an output FITS binary table. If this parameter is not set to a zero (default) then the appropriate TNULLn keyword will be added to the FITS file header for all the integer columns. This parameter should only be defined if the data actually contains undefined values (represented by "INDEF" character string).

(clobber = NO) [boolean]
If the output file already exists, then setting "clobber = yes" will cause it to be overwritten.

(chatter = 1) [integer, 0 - 5]
Controls the amount of informative text written to standard output. Setting chatter = 5 will produce detailed diagnostic output, otherwise this task normally does not write any output.

(history = NO) [boolean]
If history = YES, then a set of HISTORY keywords will be written to the header of the output file to record the value of all the ftcopy task parameters that were used to produce the output file.

EXAMPLES

1. Create a FITS file called 'outtab.fits' with a binary table extension from a column description file called 'coldesc.lis', a free-format data file called 'data.lis' and a header file called 'keywords.lis'.

     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


SEE ALSO

binfilter, calc_express, ftcopy, ftlist, ftemplate.

The design of this task is based on the fcreate task in the ftools package.

LAST MODIFIED

March 2006