CDS.headStuff2 tofits

tofits (1)     Transform a set of documented files into FITS.     (Mar-1997)


Syntax
tofits [–v] [–z|Z] [–u[1|2]] [–fih] [–noh] [–nodata] [–m max_records] [–d data_directory] [–i description_file] [–h SIMPLEheader_file] [–o output_file] [–w[.fih]] [[–t table_structure] input_file...]

Description
The tofits command translates a set of files described according to the CDS Standards (see the Standards for Astronomical Catalogues document) into FITS tables.

The result may consist of either plain FITS files (bulk files including data description and the corresponding values), or of only the headers, i.e. the description of the data as plain ascii files; the latter files are normally named *.fih files.

The creation of the plain FITS files follows the following algorithm:

  • With the –fih option, from a set of FITS headers files (*.fih files) and of data files as follows:
    1. the basic FITS header (on top of all tables) is specified via the –h option; its default name is SIMPLE.fih
    2. for each table, the TABLE header and the data file, files named file.fih and file.
    The complete FITS creation for a set of n tables therefore requires 2n+1 files, the data tables plus n+1 *.fih files.
  • Without the –fih option, the Documentation File (ReadMe) (see also anafile(1)) is used to generate the missing *.fih files. A full FITS generation may if necessary be driven by a special shell script stored in a file named .MakeFITS.

Note that some files (e.g. tex files, HTML, postscript files) are not converted to FITS.

Options
Without any option, tofits uses the ReadMe file and the data files in the current directory and transforms all files described in ReadMe into a single FITS file displayed on the terminal.

–d data_directory    indicates the directory containing the relevant files (data files, *.fih files, the ReadMe if not specified by the –i option). The default data_directory is the current directory.

–fih    tells that no ReadMe file is required, all descriptions do exist as *.fih files; the top header is named SIMPLE.fih, unless another name is specified via the –h option.

–h SIMPLEheader_file    provides an alternative name to SIMPLE.fih (see option –fih)

–help    displays a detailed help.

–i description_file    provides the non-standard (Intro or ReadMe) name of the Description file;

–m max_records    asks to limit the generated FITS file to the specified number of records. By default, all records are converted to FITS.

–nodata    asks to generate only FITS headers (similar to *.fih files); the data files are ignored.

–noh    asks not to generate the top (SIMPLE) header; this option is especially useful to append a new FITS table to an existing FITS data set.

–o output_file    designates the file replacing the default stdout (terminal). The usage of a disk file allows to rewrite the actual number of records (the NAXIS2 parameter), when the number of records stored in the ReadMe is not correct (e.g. with the –t option). Note that this option is not compatible with the compression.

–t table_structure    indicates that the next file argument designates a data file which contains data structured like table_structure (for instance an excerpt of a table). table_structure is therefore a name which must exist in one of the Byte-by-byte Description ... section in the ReadMe file.
A value of - for table_structure asks to stop this behaviour.

–u    allows to select how to write the comments related to the units: the –u1 option comments each unit with its SI (Système International) value, while –u2 option comments each unit with both litteral and SI counterpart.

–v    is a verbose option.

–w.fit    asks to write a new file for each FITS table; with this option, there are as many FITS files generated as data files, each being a complete FITS file including the top header, a table header and the corresponding data. The names of the files generated this way have a .fit extension.

–w.fih    asks to write a new file for each table header (generation of *.fih files). The names of the files generated this way have a .fih extension.

–Z    compresses the resulting files with the standard Unix compress(1) routine. The output cannot be put in a file (incompatible with –o option)

–z    compresses the resulting files with the gzip(1) utility. The output cannot be put in a file (incompatible with –o option)

Files
The file... specified on the command line represent the files which should be converted to FITS. If a file was preceded by a –t option, file is assumed to have the same structure as the –t table_structure argument ( stands for the standard input).

The default is to convert all described files, i.e. all files included in the File Summary section of the ReadMe file, with the exception of the non-convertable files.

A dash or a dollar sign $ as a file name asks to stop the conversion; this is useful if one wants to generate only the top header, as in

tofits -nodata -i DescriptionFile - > SIMPLE.fih

Note that if the file argument is a directory, it has the same effect as it were preceded by the–d flag.

Non-converted files
The extension of filenames is used to decide that a file should not be converted into FITS. Files with names ending by .fih, .fis, .tex, .dvi, .ps, .pdf, .doc, .sty, .htm, .html, .tar and .tgz are not converted.

.MakeFITS script
When a .MakeFITS file exists, it is called from tofits (via the Bourne shell /bin/sh) to generate all FITS files: this can be executed only when tofits is called without any file argument.

This script may use (and change) the following numeric environment variables which are set by tofits before calling .MakeFITS:

  • toFITSd=0   to generate only the headers (option –nodata)
  • toFITSh=0   to skip the SIMPLE header (option –noh)
  • toFITSm=1   to use the FILEMARK extension (which separates two FITS files)
  • toFITSr=1   is the recursivity count, incremented each time tofits is called.

The .MakeFITS script may (recursively) call tofits .

Returned Status
The tofits command returns 0 in case of success, and non-zero when errors are found.

Examples
  • Convert the files in current directory which are documented in the standard way:
    tofits > catalog.fits
  • Convert the files of catalogue I/219 into a single compressed FITS file:
    tofits -z /ftp/cats/I/219 > 1219.fgz
  • Extract the correlation coefficients (indicated by the CORR string) from the Hipparcos catalogue stored on a CD-ROM (the description file is named tofits.dat, the correlation coefficients table is described by h_dm_cor.dat):
    grep CORR /cd/cats/hip_dm_c.dat \
    | tofits -i /cd/fits/tofits.dat -t h_dm_cor.dat -o h_dm_cor.fit

See also
anafile(1) compress(1) gzip(1) ``Standards for Astronomical Catalogues''
/srv/httpd/Pages/catstd/tofits.htx