fcreate -- Create a FITS table extension from ASCII files describing the format and content of the table.
fcreate cdfile datafile outfile
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 (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.
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, but total width r rX - On/Off bits rB - unsigned 8-bit byte rI - 16-bit integer rJ - 32-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). 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 (in which column starting positions and column widths are specified in the column description file) 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. Any blank lines or lines beginning with '#' will be ignored. 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). Each line of the ASCII data file may be up to 30000 characters long and may contain up to 999 data values.
For free format data files, each line of data may contain any number of 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. Fcreate will continue reading values from subsequent rows until it reachs the end of the ASCII 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 ASCII data file may be up to 30000 characters long and may contain up to 999 data values.
Bit vector (nX) column data must be entered as the equivalent n-bit integer value. For example to set all 3 bits of a '3X' column one would enter the decimal value 7, and not an array of 3 1s.
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.
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 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.
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> fcreate 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 The data file (data.lis) could contain: 'Alpha Boot' 15.345 -12.346 3 Vega 123.225 39.245 7 'RR Lyrae' 34.46788 -36.9 1 The optional header file (keywords.lis) could contain: INSTRUME ROSAT / name of instrument OBS-DATE 23/08/92 date of the observation observer 'I. Newton' principle investigator tempdet 98.6 / temperature of the detector history This file was created with the ftools fcreate task
Variable length array columns are not currently supported by this task.
ftcreate, ftlist, fthedit