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