ftcopy HEADAS help file

NAME

ftcopy - copy a file, applying optional filters or transformations.

USAGE

ftcopy infile[ext][filters] outfile

DESCRIPTION

This seemingly simple program can apply complex filtering methods which transform the input file as it is copied. If the specified HDU in the input file contains an image, then ftcopy can:

copy a rectangular subset of the image
create a mirror image, by reversing the order of the pixels in one or more dimensions
convert an IRAF format image into a FITS image
convert a raw binary data array into a FITS image

If the specified input HDU is a table, then ftcopy can:

copy selected rows and columns to the output table
select rows in an event list that are located within a specified 'good time interval' and/or spatial region
calculate new table columns based on an arithmetic expression
create an n-dimensional image by binning (histogramming) the values in n columns

Additional information on the syntax for specifying the file filters is available in the following help files: filenames, imfilter, colfilter, rowfilter, binfilter. calc_express. The file filtering syntax is also explained in the CFITSIO User's Guide.

Note that use of a filters on the input file normally requires that the resulting virtual file 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. 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]').

PARAMETERS

infile [filename]: Input file name and optional extension name or number enclosed in square brackets of the HDU to be copied (e.g., 'file.fits[0]' or file.fits[events]'). Additional filter specifiers can be appended to the file name, also enclosed in square brackets, 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).
(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).
(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 specified HDU in the output file to record the value of all the ftcopy 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.

The following examples illustrate operations that can be performed on the input HDU if it is a primary array or image extension:

1. Copy a 100 X 100 pixel subset from a larger image.

      ftcopy 'image.fits[101:200, 101:200]' out.fits

2. Make a copy of the whole input image, reversing the pixels along the X axis. Do not copy any other HDUs in the input file.

      ftcopy 'image.fits[-*,*]' out.fits copyall=NO

3. Copy the odd numbered pixel from the 512 X 512 input image, creating a 256 X 256 output image

      ftcopy 'image.fits[1:512:2, 1:512:2]' out.fits

4. Convert an IRAF format image to a FITS image.

     ftcopy irafimage.imh outimage.fits

5. Convert a file containing an array of raw binary numbers into a FITS image. The data type and dimensions of the array are enclosed in square brackets following the file name. The first letter indicates the data type (b = 8-bit unsigned byte, i = 16-bit signed integer, u = 16-bit unsigned integer, j = 32-bit signed integer, r = 32-bit floating point, d = 64-bit double precision floating point). A second optional letter may be present to indicate the byte order in the array, where b = big endian (as on SUN workstations and Mac PCs) or l ('el') = little endian (as on IBM PCs). If omitted, the native byte order for the local machine is assumed. This is followed by a series of one or more integers separated by commas which define the size of each dimension of the raw array. Finally, a byte offset to the position of the first pixel in the raw file may be specified by separating it with a colon (':') from the last dimension value. This parameter may be used to skip over any header information in the file that preceeds the binary data.

      ftcopy 'raw.dat[i1000]'         - 1-D 1000 pixel integer*2 array

      ftcopy 'raw.dat[rb512,512]'     - 2-D big endian real*4 image

      ftcopy 'raw.dat[i512,512:2880]' - skip the first 2880 bytes

The following examples illustrate operations that can be performed on table HDUs

1. Filter an EVENTS table extension, copying only those rows that have a PI column value > 20.

      ftcopy 'infile.fits[EVENTS][PI > 20]' outfile.fits

2. Filter an EVENTS table extension, using the row filter expression that is given in the rowfilt.txt ASCII file.

      ftcopy 'infile.fits[EVENTS][@rowfilt.txt]' outfile.fits

3. Filter an EVENTS table extension using the GTI (good time interval) extension contained in the input file, or (in the 2nd case) a spatial region defined in the "pow.reg" ASCII file.

      ftcopy 'infile.fits[EVENTS][gtifilter()]' outfile.fits

      ftcopy 'infile.fits[EVENTS][regfilter("pow.reg")]' out.fits

4. Copy only the X, Y and Time columns from the input events extension to the output file.

      ftcopy 'infile.fits[3][col X; Y; Time]' outfile.fits

5. Copy all columns except the Time column from the input events extension to the output file. Only the first 100 rows of the table are copied.

      ftcopy 'infile.fits[3][col -Time][#row <101]' outfile.fits

6. Copy all the columns whose names begin with X or Y from the input events extension to the output file.

      ftcopy 'infile.fits[3][col X*; Y*]' outfile.fits

7. Copy the table in the 3rd extension of infile.fits, and create a new column called 'LogRate' that is equal to the logarithm of the 'Counts' column divided by the Exposure keyword (or column).

      ftcopy 'infile.fits[3][col LogRate = log10(Counts/Exposure)]'
        outfile.fits

8. Create a 2-D image (histogram) from the DETX and DETY columns of an EVENTS table, and write HISTORY keyword to the output file.

      ftcopy 'infile.fits[EVENTS][bin (DETX,DETY)=1:1024:16]' outfile.fits
        history=YES

9. Copy a FITS file from the HEASARC FTP site:

      ftcopy
        https://heasarc.gsfc.nasa.gov/FTP/rosat/data/pspc/images/fits/rp700350_im1.fits
        outfile.fits

10. Copy the first 100 rows of a vector array column "COUNTS" - but only elements 2 and 3 of the 1-D array - into two new scalar columns ("COUNT2" and "COUNT3") in an output table:

      ftcopy
        'infile.fits[2][col COUNT2=COUNTS[2], COUNT3=COUNTS[3]][#row < 101]'
        outfile.fits

LAST MODIFIED