ftpaste HEADAS help file

NAME

ftpaste - Merge columns from 2 input tables into a single table.

USAGE

ftpaste infile[ext][filters] pastefile[ext][filters] outfile

DESCRIPTION

ftpaste combines two tables in a column-wise fashion to make a new table. Columns from the first table are matched, by row number, with columns from the second table, and the resulting set of combined columns is saved in the output file.

ftpaste creates a new table containing a copy of the columns and header keywords from the first input table, plus the columns from the second pastefile table. This task is analogous to the Unix 'paste' command. By default, all the columns from both the input table and the paste table are copied to the output table, but a column filter may be specified for one or both tables to only copy a subset of the columns. For example, if the input file is given as 'file.fit[events][col X;Y]', then only the X and Y columns from that table will be copied to the output file.

The input table (or the virtual input table if a column filter or other type of filter is applied to the file) is first copied verbatim to the output file. If the 'copyall' parameter = YES then any other HDUs in the input file are also copied to the output file. Then the columns in the pastefile table (or virtual pastefile table if it is filtered) are copied and appended to the output table. Any standard keywords that are directly related to the columns (e.g., TUNITn, TDISPn, or any of the world coordinate system keywords for the columns) are also copied to the output table.

If the paste table contains more rows than the first input table, then only the number of rows in the input table will be copied. If the paste table contains fewer rows than the input table, then the remaining rows in the output table will be set to zero (or blank if the column contains ASCII strings).

Note that use of a column filter on the input table or paste table normally requires that the resulting virtual table be constructed entirely in memory before it is copied to the output file. This operation may fail if the virtual file is too large to fit in the available memory. In this case, it may be necessary to construct physical files containing only the desired columns to be copied by deleting the unwanted columns from a copy of the input and paste files using the ftcopy task. Alternatively, one may force the virtual file to be constructed on disk, not in memory, by specifying an explicit temporary output file (e.g., 'file.fit(tempfile.fit)[events][col -PI]').

There are other similar table-combining tasks to consider. ftjoin is similar to ftpaste in that it combines two tables in a column-wise fashion, but any arbitrary matching expression can be used to match columns. ftmerge and ftmeld can be used to append table rows; ftmeld is more flexible in doing so, but ftmerge is faster and more efficient.

While

PARAMETERS

infile [filename]: Input file name and optional extension name or number enclosed in square brackets of the first table to be copied (e.g., file.fits[events]'). If an explicit extension name or number is not specified, then the first table HDU in the file that is not a 'Good Time Interval' (GTI) table will be used. Additional filter specifiers can be appended to the file name, also enclosed in square brackets, to limit the number of columns and/or rows to be copied, as shown in the examples. The output table will contain a copy of all the columns and all the keywords in the input table.
pastefile [filename]: Paste file name and optional extension name or number in square brackets of the table containing the column(s) to be appended to the copy of the input file file. If an explicit extension name or number is not specified, then the first table HDU in the file that is not a 'Good Time Interval' (GTI) table will be used. Additional filter specifiers can be appended to the paste file name, also enclosed in square brackets, to limit the number of columns and/or rows to be copied, as shown in the examples.
outfile [filename]: Output file name. Precede it with an exclamation point, !, (or \! on the Unix command line), to overwrite a preexisting file with the same name (or set the 'clobber' parameter to YES). This file will contain a copy of the table in the input file plus the columns in the paste file.
(copyall = YES) [boolean]: If copyall = YES (the default) then any other HDUs in the input file will also be copied, without modification, to the output file. If copyall = NO, then only the single HDU specified by infile will be copied to the output file.
(clobber = NO) [boolean]: If outfile 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 table to record the value of all the ftpaste task parameters that were used to produce the output file.

EXAMPLES

Note that when commands are issued on the Unix command line, strings containing special characters such as '[' or ']' must be enclosed in single or double quotes.

1. Copy all the columns from the input events table and all the columns from the table in the 3rd extension in the paste file to the output file. Any other HDUs in the input file will also be copied to the output file.

      ftpaste 'infile.fits[events]' 'paste.fits[3]' output.fits

2. Create an output table that contains a copy of all the columns in the input events table except the X and Y columns, then append the X and Y columns from the paste file to the output file. Any other HDUs in the input file are not copied to the output file. HISTORY keywords that record the value of all the ftpaste parameters will also be written to the output table header.

      ftpaste 'infile.fits[events][col -X;-Y]' 'paste.fits[events][col X;Y]'
        output.fits copyall=NO history=YES

3. Copy only the X and Y columns in the 2 input event tables to the output table. The X and Y columns from the first input table are renamed X1 and Y1, and the X and Y columns from the paste table are renamed X2 and Y2. Note that FITS tables should never contain 2 columns with the same name.

      ftpaste 'infile.fits[events][col X1==X;Y1==Y]'
        'paste.fits[events][col X2==X;Y2==Y]' output.fits

4. This example is similar to the previous one except that any other columns in the first input table, in addition to the X and Y columns, are also copied to the output table. This is accomplished by specifying '*' as one of the column names; this wild card matches every column, thus forcing every column that is not specifically deleted to be retained in the virtual table.

      ftpaste 'infile.fits[events][col X1==X; Y1==Y; *]'
        'paste.fits[events][col X2==X;Y2==Y]' output.fits

5. This example is similar to the previous one except that only the columns whose names end with 'raw' are copied, in addition to the renamed X and Y columns.

      ftpaste 'infile.fits[events][col X1==X; Y1==Y; *raw]'
        'paste.fits[events][col X2==X;Y2==Y]' output.fits

6. This example is similar to the previous ones except that only the first 500 rows in the input (and paste) table are copied to the output table.

      ftpaste 'infile.fits[events][col X1==X;Y1==Y; *raw][#row <= 500]'
        'paste.fits[events][col X2==X;Y2==Y]' output.fits

7. In this example, the first table HDU in infile.fits is copied to the output file, then the 'PHAcoor' column is appended to the output file containing values that are calculated on the fly as a function of the PHA column in the paste table.

      ftpaste infile.fits 'paste.fits[events][col PHAcoor=PHA*1.2]' output.fits

LAST MODIFIED