diff options
Diffstat (limited to 'funtools/doc/pod/funmerge.pod')
-rw-r--r-- | funtools/doc/pod/funmerge.pod | 122 |
1 files changed, 122 insertions, 0 deletions
diff --git a/funtools/doc/pod/funmerge.pod b/funtools/doc/pod/funmerge.pod new file mode 100644 index 0000000..0cb9216 --- /dev/null +++ b/funtools/doc/pod/funmerge.pod @@ -0,0 +1,122 @@ +=pod + +=head1 NAME + + + +B<funmerge - merge one or more Funtools table files> + + + +=head1 SYNOPSIS + + + + + +funmerge [-w|-x] -f [colname] <iname1> <iname2> ... <oname> + + + + + +=head1 OPTIONS + + + + + + -f # output a column specifying file from which this event came + -w # adjust position values using WCS info + -x # adjust position values using WCS info and save old values + + + + +=head1 DESCRIPTION + + + + +B<funmerge> merges FITS data from one or more +FITS Binary Table files +or raw event files. + +The first argument to the program specifies the first input FITS table +or raw event file. If "stdin" is specified, data are read from the +standard input. Use Funtools Bracket +Notation to specify FITS extensions and row filters. Subsequent +arguments specify additional event files and tables to merge. (NB: Stdin +cannot not be used for any of these additional input file arguments.) +The last argument is the output FITS file. The columns in each input table +must be identical. + + +If an input file begins with the '@' character, it is processed as an +include file, i.e., as a text file containing event file names (as +well as blank lines and/or comment lines starting with the '#' sign). +If standard input is specified as an include file ('@stdin'), then +file names are read from the standard input until EOF (^D). Event +files and include files can be mixed on a command line. + + +Rows from each table are written sequentially to the output +file. If the switch B<-f [colname]> is specified on the command +line, an additional column is added to each row containing the number +of the file from which that row was taken (starting from one). In +this case, the corresponding file names are stored in the header +parameters having the prefix B<FUNFIL>, i.e., FUNFIL01, +FUNFIL02, etc. + + +Using the B<-w> switch (or B<-x> switch as described +below), B<funmerge> also can adjust the position column values +using the WCS information in each file. (By position columns, we mean +the columns that the table is binned on, i.e., those columns defined +by the B<bincols=> switch, or (X,Y) by default.) To perform WCS +alignment, the WCS of the first file is taken as the base WCS. Each +position in subsequent files is adjusted by first converting it to the +sky coordinate in its own WCS coordinate system, then by converting +this sky position to the sky position of the base WCS, and finally +converting back to a pixel position in the base system. Note that in +order to perform WCS alignment, the appropriate WCS and TLMIN/TLMAX +keywords must already exist in each FITS file. + +When performing WCS alignment, you can save the original positions in +the output file by using the B<-x> (for "xtra") switch instead +of the B<-w> switch (i.e., using this switch also implies using +B<-w>) The old positions are saved in columns having the same +name as the original positional columns, with the added prefix "OLD_". + +Examples: + + +Merge two tables, and preserve the originating file number for +each row in the column called "FILE" (along with the corresponding +file name in the header): + + [sh] funmerge -f "FILE" test.ev test2.ev merge.ev + + + +Merge two tables with WCS alignment, saving the old position values in +2 additional columns: + + [sh] funmerge -x test.ev test2.ev merge.ev + + + +This program only works on raw event files and binary tables. We have +not yet implemented image and array merging. + + + + +=head1 SEE ALSO + + + +See funtools(n) for a list of Funtools help pages + + +=cut |