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:
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]'
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='*'
The design of this task is based on the fdiff task in the ftools package.