ftdiff HEADAS help file

NAME

ftdiff - Display differences between 2 FITS files.

USAGE

ftdiff file1 file2

DESCRIPTION

'ftdiff' compares the 2 input files and reports any differences in the header keywords or image or table data elements. Various options are available to control the level of checking.

If extension names and numbers are not given for both files, the program will compare all the HDUs. If an extension name or number is given in one of the file but not the other, then ftdiff will only compare that single HDU in both files.

The header keywords in the 2 HDUs are first sorted alphabetically and then the values are compared. The order of the keywords in the header is not significant. The commentary keywords (HISTORY, COMMENT, and keywords with a blank name), and the CHECKSUM and DATE keywords are ignored during the comparison. Users can specify additional keywords to be excluded by supplying a list of names as the value of the "exclude" parameter. This list can be either a string which consists of the keyword names separated by commas, or the name of an ASCII file preceded with an '@' character. In the latter case, each keyword name should be listed on a separate line in the file.

The '*', '?', and '#' wild card characters may be used when specifying the names of the keywords to be excluded from the comparison, with the following interpretation:

For example, 'NAXIS*' will exclude 'NAXIS', 'NAXIS1', and 'NAXIS2', whereas 'NAXIS#' will only exclude the numbered NAXIS keywords and not the NAXIS keyword itself. The comparison of header keyword values can be turned off completely by entering '*' for the value of the exclude parameter.

Users can choose whether to compare keywords (excluding TFORMn and TDISPn) as numerical values by setting the cmpnum parameter to "YES". If the cmpnum parameter is set to "NO", then they will be compared as literal strings. For example, if cmpnum = NO, then the program will interpret 1.0E+02 and 100.0 as different values even though they have the same numerical values. If the 2 values differ by less than the value of the 'tolerance' parameter (default value = 0) then they will be considered to be equal.

To quickly determine if the image or table data units of the 2 files are identical, run ftdiff with the 'caldsum' parameter set to 'YES' and the 'cmpdata' parameter set to 'NO'. This will compare the checksum values for the 2 data units and report a warning if they differ. To determine exactly which image pixels or table columns are different, run ftdiff with cmpdata = YES. This is more time consuming then just comparing the checksums, but will clearly identify any differences between the 2 files.

Numerical quantities are flagged as different when their arithmetic difference exceeds a certain threshold. Users can supply both an absolute and relative threshold using the "tolerance" and "reltol" parameters. For quantities x1 and x2 from file1 and file2, values which satisfy this expression:

   |x1 - x2| > tolerance + |x1|*reltol

are considered to be different. A relative tolerance may be appropriate if there is a large dynamic range in values. By using both an absolute and relative tolerance, users can also guard against the case when x1 is near zero. The default tolerances are '0', indicating that an exact match is required.

Virtual file filters may be applied to the input files to compare only parts of the data. A column filter may be applied to both files to compare a subset of the table columns, as in this example which only compares the X and Y column values:

   ftdiff 'file1.fit[events][col X;Y]' 'file2.fit[events][col X;Y]'

Similarly, one can just compare selected rows in the table, as in this example which only compares the first 10 rows:

   ftdiff 'file1.fit[events][#row < 11]' 'file2.fit[events][#row < 11]'

The image subsection filters may be used to compare small areas of 2-dimensional images, as in:

   ftdiff  'img1.fit[10:15,30:35]'  'img2.fit[10:15,30:35]'

PARAMETERS

infile1 [filename]: File name of the the first FITS file, followed by an optional extension name or number enclosed in square brackets.
infile2 [filename]: File name of the the second FITS file, followed by an optional extension name or number enclosed in square brackets.
(exclude ="") [string]: A comma separated list of keywords to ignore during the file comparisons. Alternatively, the name of an ASCII file many be entered preceded by an '@' character, where the file contains the list of excluded keywords, one per line. The '*', '?', and '#' wild card characters may be used in the keyword names.
(cmpnum = yes) [boolean]: If set to YES, then the keyword values will be compared numerically, otherwise the value strings will be compared literally.
(tolerance = 0.) [double]: Numerical tolerance. If the values in the 2 files differ by this amount or less then they will be considered to have the same value.
(reltol = 0.) [double]: Relative numerical tolerance. If the values in the 2 files differ fractionally by this amount or less then they will be considered to have the same value.
(caldsum = yes) [boolean]: Should data checksums be computed and compared if the DATASUM keyword does not exist?
(cmpdata = yes) [boolean]: Should the data units be compared datum by datum (for images and tables)?
(hdumaxdiff = 256) [integer]: Maximum number of differences allowed in a HDU (including keywords and data). If the number of differences in a HDU exceeds this value then a warning message will be printed out and the comparison test will be terminated for this HDU. If hdumaxdiff is non-positive (i.e. negative or 0), all differences will be displayed and counted for output in the numdiffs parameter.
(numdiffs) [output integer]: Returns the number of found differences, up to but not exceeding hdumaxdiff, unless hdumaxdiff is less than or equal to 0, in which case all differences will be counted and reported.
(chatter = 1) [integer]: Controls the verbosity level of the output. Currently this parameter has no effect.

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. Display the differences between file1 and file2, allowing a tolerance of 0.0001 between the values in the 2 files.

      ftdiff file1 file2 tolerance=0.0001

2. Display the differences between the EVENTS extensions in file1 and file2. Any other extensions in the file will be ignored.

      ftdiff 'file1[events]' 'file2[events]'

3. Display the differences in only the X and Y columns in the EVENTS extensions in the 2 files.

      ftdiff 'file1[events][col X;Y]' 'file2[events][col X;Y]'

4. As above, but only compare the first 100 rows of the table

      ftdiff 'file1[events][col X;Y][#row < 101]' 
                'file2[events][col X;Y][#row < 101]'

5. Display the differences between file1 and file2 but ignore the keywords KEY2, KEY31 and KEY32.

      ftdiff file1 file2 exclude="KEY2,KEY3*"

6. Same as the previous example, except that the list of keywords to exclude is contained in an ASCII file called 'keys.txt'.

      ftdiff file1 file2 exclude="@keys.txt"

7. Same as the previous example, except that all keywords are excluded from the comparison.

      ftdiff file1 file2 exclude='*'

LAST MODIFIED