NAME

fdiff -- display differences between pairs of fits file.


USAGE

        fdiff fitsfile1 fitsfile2 

DESCRIPTION

This task compares details of the headers of the two fitsfile. It also can tell whether the Data units are the same or not by examining the datasums, and optionally, testing datum-by-datum.

If extension names/numbers are not given for both files, the program will compare all the HDUs. If extension name/number is given in one of the file but not the other, the program will only test the specified HDU of the two files with the same hdu number.

Headers are compared keyword by keyword. The commentary keywords (HISTORY, COMMENT, and keywords with a blank name), "CHECKSUM" and "DATE" keywords are not considered. Users can also exclude additional keywords by supplying a list as the value of the "exclude" parameter. This list can be either a string which consists of the keywords separated by commas, or a filename of an ASCII file preceded with an @. For the ASCII list file, each keyword will occupy one line. If the pattern is followed by *, keywords which matched that pattern from beginning will be excluded. For example, the DATE means DATE but not "DATE-OBS". The "DATE*" means all the keywords "DATE", "DATE-OBS" and other DATExxxx but not "TSTDATE".

Users can choose whether to compare the numerical keywords as numerical values by setting the cmpnum parameter. If the cmpnum parameter is not set, they will be compared as strings. For example, if cmpnum is not set, the program will think the 1.0E2 and 100 are the different values in spite of the same numerical values.

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.

For the data units, the datasums are examined. The default datasum value is the value of DATASUM keyword. If it does not exist, the users can choose whether they want to calculate the datasum by setting the caldsum parameter. If it is set, the datasum will be calculated and used for comparison.

If the cmpdata parameter is set, the details of data in image arrays and tables are also compared.


PARAMETERS

file1 [string]
File name of the the first fitsfile.

file2 [string]
File name of the the second fitsfile.

(exclude = "") [string]
The list of excluded keywords.

(cmpnum = yes) [boolean]
For the numerical keywords, should we compare them as numerical values?

(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 we calculate the datasum if DATASUM keyword does not exist?

(cmpdata = yes) [boolean]
Should we compare the data Units (images and tables)?

(hdumaxdiff = 256) [integer]
Maximum number of differences can allowed in a HDU (including keywords and data). If the number of differences in a HDU exceeds the hdumaxdiff, a warning message will be printed out, and the comparison test will be terminated for this HDU.

(numdiffs) [integer]
Returns the total number of found differences.

(verbose = yes) [boolean]
Write informational message to screen.


EXAMPLES

1. Display the differences between file1 and file2

             ft> fdiff file1 file2 

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

             ft> fdiff file1 file2 exclude="KEY2,KEY3*"


BUGS

The current version skips the variable length vector columns.


SEE ALSO

ftdiff, ftlist, ftchecksum, fv

CATEGORY

Sep98 ftools.futils