ftinsert HEADAS ftinsert help file

NAME

ftinsert - Insert a HDU from one file into a second FITS file.

USAGE

ftinsert inhdu[ext][filters] infile[ext] outfile

DESCRIPTION

Insert a copy of the input HDU into a copy of a 2nd FITS file, immediately after (or, optionally, before) the specified HDU in the 2nd file. The input HDU may be modified with optional filtering specifiers before it is inserted. Neither input file is modified by this operation, and instead the merged HDUs get copied to the specified output file.

PARAMETERS

inhdu [filename]: File name and extension name or number (enclosed in square brackets) of the HDU to be copied and inserted into the other file (e.g., 'file.fits[0]' or file.fits[events]'). If an extension is not specified, then the primary array will be inserted (and converted to an IMAGE extension if necessary). Optional filtering operations can be specified as part of the HDU file name (also enclosed in square brackets) to modify the input HDU on the fly, as shown in the examples.
infile [filename]: File name and extension name or number (enclosed in square brackets) of the FITS file into which the HDU is to be inserted (e.g., 'file.fits[0]' or 'file.fits[events]'). A copy of this file will be made (the original file is not be modified) and the HDU pointed to by 'inhdu' will be inserted after or before the specified extension, depending on the value of the `after' parameter. If `inhdu' is to be inserted at the beginning of the output file, then the primary array of `infile' will be converted into an IMAGE extension, and the HDU from `inhdu' will be inserted before it. If the HDU from 'inhdu' is a table extension, then a small dummy primary array will be created and inserted before the table HDU.
outfile [filename]: Name of the output FITS file for the merged set of HDUs.
(after = YES) [boolean]: If the value of `after' is YES, then the HDU specified by `inhdu' will be inserted AFTER the HDU specified by `infile'. If the value is NO, then the `inhdu' HDU is inserted BEFORE the `infile' HDU.
(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 copied HDU to record the value of all the ftinsert 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. Insert a copy of the GTI extension in file1.fits into a copy of file2.fits, following the EVENTS extension. The merged HDUs are written to the file out.fits.

      ftinsert 'file1.fits[GTI]' 'file2.fits[EVENTS]' out.fits

2. Insert a copy of the 3rd extension in the file1.fits into a copy of file2.fits, following the primary array. The merged HDUs are written to the file out.fits.

      ftinsert 'file1.fits[3]' file2.fits out.fits

3. Insert the primary array from file1.fits at the beginning of a copy of file2.fits. The original primary array of file2.fits will be converted into an IMAGE extension.

      ftinsert file1.fits file2.fits out.fits after=NO

4. Create a virtual 2-D FITS image by binning the X and Y columns (with a bin size = 30) in the EVENTS table extension of file1.fits, and then insert that virtual image onto a copy of file2.fits following the 4th extension.

      ftinsert 'file1.fits[events][bin (X,Y)=30]' 'file2.fits[4]'
                out.fits

LAST MODIFIED