ftabcopy HEADAS help file

NAME

ftabcopy -- Copy specified columns and rows from a FITS table to a new FITS table.

USAGE

        ftabcopy infile[ext#] outfile columns rows

DESCRIPTION

This task will create a new FITS file (with a binary or ASCII table extension) containing a subset of the columns and rows in an existing FITS table extension. The desired column names are given as a column name template. Row ranges could also be given and there could be as much as 15 ranges at present. By default it is '-' which is all rows of the input file. Also, it copies the following WCS related keywords: TLMIN, TLMAX, TCTYP, TCRCL, TCDLT, TCRPX, TCROT, and TCRVL.

PARAMETERS

infile [filename]: Name of the FITS table extension (including optional extension number in square brackets) from which the columns are to be copied.
outfile [filename]: Name of the new FITS file to contain the copied columns. By default, the output file will consist of a null primary array followed by an ASCII or binary table extension, depending on the type of input file extension. If preceded by !, an existing file of the same name is overwritten.
columns [string]: List of column names in the order to be copied from the input FITS table into the new FITS file. The names are case sensitive. The column names should be separated by commas or white space. Instead of directly listing all the column names, one may specify the name of an ASCII file (preceded by the "@" character) containing all of the column names to be copied, one name per line in the file. The flcol task may be used to generate a column name template which may then be edited for input to this task. If the first non-white character in the column template is the negation character (-), the new FITS file will contain all the columns in the input file that are NOT listed in the column template.
rows [string]: List of row ranges separated by comma (,) to be copied from input file. At most 15 ranges can be accomodated at present. By default all rows are copied.
(outtype = SAME) [string]: Specify the type of output extension - ASCII or BINARY. If outtype is SAME, the output extension type will be the same as the input extension type.
(inull = -999) [integer]: Value to use for NULL in integer columns for ASCII->BINARY translation. Used only if the defined NULL is illegal or undefined.
(snull = "UNDEF") [string]: Value to use for NULL in column in BINARY->ASCII translation. Used only if the defined NULL is illegal or undefined.
(unique = no) [boolean]: Eliminate duplicate rows from the output FITS file? If 'unique' is set to "yes", only one of each set of duplicate rows is included in the output FITS table. All columns in the output FITS table must be identical for the row to be removed. String comparisons are case sensitive.
(copyprime = yes) [boolean]: If true, the primary header and array of the input file will be copied to the output file.
(copyall = no) [boolean]: Copy all other extensions (and the primary array) from input FITS file to the output FITS file? If true, the value of copyprime is ignored.
(copykeys = yes) [boolean]: Copy all the additional non-required keywords from the input FITS table header to the output table header? If false, then only the essential keywords needed to define the structure and WCS of the table columns will be copied.
(history=yes) [boolean]: When this parameter is true, FTABCOPY will add a history record to indicate that it acted on the file.
(clobber=no) [boolean]: If true, an existing file with the same name as the requested output file is overwritten.

EXAMPLES

1. Copy the name, mag, and color columns from the starcat.fits file:

          ft> ftabcopy starcat.fits starmag.fits name,mag,color

2. Copy all the columns except the 'error' column:

          ft> ftabcopy meas.fits nomeas.fits -error

3. Copy the rows 1-10, 35, 105 etc:

          ft> ftabcopy rows=1-10, 35, 105

NOTES

In the BINARY->ASCII translation, complex and logical data types, variable length arrays and vector columns are not supported. Bit and Byte columns are mapped to integer.

BUGS

NULLs in ASCII columns are not retained in either translation.