NAME

ftmerge - Merge (append) rows from multiple input tables into a single output table.

USAGE

ftmerge infile1,infile2 outfile

DESCRIPTION

This task merges 2 or more separate FITS tables that have an identical set of columns by concatenating all the rows from each input table into one output FITS table. The first FITS table in the input list is copied verbatim to the output file (including all header keywords and any preceding and following HDUs in the file), then the rows from the subsequent input tables are appended to the output table. All the input tables (or the virtual tables, if the file filtering syntax is used), must have the same number of columns, in the same order, as in the first input file. The number of rows in the output table will be equal to the sum of the number of rows in all the input tables or virtual tables.

The output table header will be identical to the first input table header, except for the value of the NAXIS2 keyword that specifies the number of rows in the table. In some cases, the values of some of the header keywords will no longer be valid (e.g., the total time range spanned by the records in the table) and should be subsequently updated.

There are other similar table-combining tasks to consider. ftmeld is similar to ftmerge in that it appends rows of input tables, but it allows much more flexibility (columns of the input files may not agree or be in the same order, for example). However, ftmerge is faster and more efficient than ftmeld. The tasks >ftpaste and ftjoin can combine two tables in a column-wise fashion, i.e. appending columns instead of rows.

PARAMETERS

infile [filename]
List of filenames, and optional extension names or numbers, of the input tables to be merged. This may be a comma-delimited list of names, or the name of a text file containing a list of file names, one per line, preceded by an '@' character. If an explicit extension is not specified after each file name then the first 'interesting' table in the file that is not a GTI (good time interval) table will be merged into the output table. Each table may be further filtered using the CFITSIO virtual file syntax enclosed in square brackets as shown in some of 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).

(columns = '*') [string]
Optional list of columns to be merged (or excluded from the merge). This may be a comma-delimited list of columns, or the name of a text file containing a list of columns, one per line, preceded by an '@' character. The names of columns to be excluded should be preceded by a minus sign. By default all the columns in the input tables will be merged. This parameter may be used to apply a virtual column filter to every input table. For example, specifying columns = 'Time,X,Y' will have the same effect as specifying the '[col Time;X;Y]' virtual file filter to each input table. Wildcards ('*' to match any string and '?' to match a single character) may be used in the list of column names.

(insertrow = 0) [integer]
Optional row number in the first input table after which the other tables will be inserted. If insertrow exceeds the number of rows in the first table, any additional rows will be filled with zeros.

(lastkey = ' ') [string]
Optional list of keywords in the last input file to be updated or added to the output file. This may be a comma-delimited list of keywords, or the name of a text file containing a list of keywords, one per line, preceded by an '@' character. If the specified key exists, its value will be updated; if not, a new keyword will be written.

(copyall = YES) [boolean]
If copyall = YES (the default) then all 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. Note that if an explicit extension name or number is not specified in the infile name, and if copyall = NO, then the first 'interesting' HDU in the input file will be copied (i.e., the first image HDU that has a positive NAXIS value, or the first table that is not a GTI (good time interval) extension).

(skipbadfiles = NO) [boolean]
If this parameter is set to "YES", then any FITS tables in the input list that cannot be opened will be ignored, and processing will continue with the next file in the list. If set to the default value of "NO", then ftmerge will instead exit with an error condition at that point.

(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 table to record the value of all the ftmerge 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. Merge a table1 and table2 into the output table. The first table HDU in the input files that is not a GTI (Good Time Interval) table will be merged in this case, since no explicit extension names or number are specified.

      ftmerge  table1.fits,table2.fits  output.fits
2. Same as the previous example, except the EVENTS extension is explicitly specified as the name of the HDUs to be merged.

      ftmerge  'table1.fits[events],table2.fits[events]'  output.fits
3. Merge a list of tables as given in the text file 'files.list' into the output table. The filename, followed by the extension name enclosed in square brackets, should be listed one per row in the text file.

      ftmerge  @files.list  output.fits

      where the contents of the files.list file is:

            table1.fits[events]
            table2.fits[events]
            table3.fits[events]
            table4.fits[events]
4. Apply column filters to the input tables. In this case, the output table will contain only the 3 column 'TIME', 'X', and 'Y'.

      ftmerge  'table1.fits[col time;x;y],table2.fits[col time;x;y]'
              output.fits
5. Same as the previous example, except this time the column filter is specified with 'columns' parameter which is applied to all the input tables.

      ftmerge  table1.fits,table2.fits  output.fits  columns='time,x,y'
6. Same as the previous example, except this time the column filter excludes the 'time' column from the output table. All the other columns in the input files are copied to the output table.

      ftmerge  table1.fits,table2.fits  output.fits  columns='-time'
7. In this example, a row filter ('PI > 12') is applied to both input tables to create virtual tables that only contain the rows that satisfy this condition. The output table will then only contain the rows from the input tables that have a PI column value greater than 12.

      ftmerge 'tab1.fits[events][PI > 12],tab2.fits[events][PI > 12]'
               output.fits

SEE ALSO

ftmeld, ftcopy, ftpaste, ftjoin, ftappend, filenames, colfilter, rowfilter,

fv, the interactive FITS file editor, can also be used to cut and paste rows from one table to another.

The design of this task is based on the FTOOLS fmerge task and the CXC dmmerge task.

LAST MODIFIED

May 2002