FITSDIFF

This module serves as a large library of helpful file operations, both for I/O of files and to extract information about the files.

fitsdiff: Compare two FITS image files and report the differences

in header keywords and data.

License: http://www.stsci.edu/resources/software_hardware/pyraf/LICENSE

Usage:  

The basic use of this module has the following syntax:

fitsdiff.py [options] filename1 filename2

where filename1 filename2 are the two files to be compared. they can be wild cards, in such cases, they must be enclosed by double or single quotes. they can also be directory names: if both are directory names, all files in each of the directories will be included, if only one is directory name, then the directory name will be prefixed to the file name(s) specified by the other argument. for example:

fitsdiff.py "*.fits" "/machine/data1"

will compare all FITS files in the current directory to the corresponding files in the directory /machine/data1

Options are one or more of:

-c	(list of keywords) a list of keywords whose comments will not be compared. If want to exclude all keywords, use “*”, make sure to have double or single quotes around the asterisk. default = None
-k	(list of keywords) a list of keywords not to be compared. If want to exclude all keywords, use “*”, make sure to have double or single quotes around the asterisk. default = None
-f	(list of column names) a list of fields (i.e. columns) not to be compared. If want to exclude all columns, use “*”, make sure to have double or single quotes around the asterisk. default = None
-n	(non-negative integer) max number of different data (image pixel or table element) to report per extension, default = 10
-d	(non-negative number) relative difference level below which data are considered equal, this criterion only applies to floating point numbers, both data and keyword values, it does not apply to integers. default = 0.
-b	means trailing blanks in string values (both in header keywords and column values) are significant, i.e. ‘ABC ‘ and ‘ABC’ mean different things if this swithch is set.
-o	(output file name) output file name where the result goes
-h	print the help (this text)

If the two files are identical within the specified conditions, it will report “No difference is found.” If the value(s) of -c and -k takes the form '@filename‘, list is in the text file ‘filename’, and each line in that text file contains one keyword.

Example:  

fitsdiff.py -k filename,filtnam1 -n 5 -d 1.e-6 test1.fits test2

this command will compare files test1.fits and test2.fits, report maximum of 5 different pixels values per extension, only report data values larger than 1.e-6 relative to each other, and will neglect the different values of keywords FILENAME and FILTNAM1 (or their very existence).

fitsdiff commandline arguments can also be set using the environment variable FITSDIFF_SETTINGS. If the FITSDIFF_SETTINGS environment variable is present, each argument present will override the corresponding argument on the commandline. This environment variable exists to make it easier to change the behavior of fitsdiff on a global level, such as in a set of regression tests.

pytools.fitsdiff.attach_dir(dirname, list)

Attach a directory name to a list of file names

pytools.fitsdiff.compare_dim(im1, im2)

Compare the dimensions of two images

If the two images (extensions) have the same dimensions and are not zero, return the dimension as a list, i.e. [NAXIS, NAXIS1, NAXIS2,...]. Otherwise, return None.

pytools.fitsdiff.compare_img(img1, img2, delta, maxdiff, dim)

Compare the image data

pytools.fitsdiff.compare_keyword_comment(dict1, dict2, keywords_to_skip, name)

Compare header keywords’ comments

compare header keywords’ comments by using the comment dictionary, the comment(s) for each keyword is in the form of a list. Don’t do the comparison if the keyword is in the keywords_to_skip list.

pytools.fitsdiff.compare_keyword_value(dict1, dict2, keywords_to_skip, name, delta)

Compare header keyword values

compare header keywords’ values by using the value dictionary, the value(s) for each keyword is in the form of a list. Don’t do the comparison if the keyword is in the keywords_to_skip list.

pytools.fitsdiff.compare_table(img1, img2, delta, maxdiff, dim, xtension, field_excl_list)

Compare data in FITS tables

pytools.fitsdiff.diff_num(num1, num2, delta=0)

Compare two num/char-arrays

If their relative difference is larger than delta, returns a tuple of index arrays where there is difference. The number of elements in the tuple is the dimension of the images been compared. Each index array in the tuple is 1-D and its length is the number of differences found.

pytools.fitsdiff.diff_obj(obj1, obj2, delta=0)

Compare two objects

return 1 if they are different, for two floating numbers, if their relative difference is within delta, they are treated as same numbers.

pytools.fitsdiff.extra_keywords(dict1, dict2, name)

Pick out extra keywords between the two input dictionaries

each dictionary’s value is a list, this routine also works if the same keyword has different number of values in diffferent dictionary.

name is a 2-element tuple of files names corresponding to dictionaries dict1 and dict2.

pytools.fitsdiff.keyword_dict(header, neglect_blanks=1)

Build dictionaries of header keyword values and comments. Each dictionary item’s value list, so we can pick out keywords with duplicate entries, including COMMENT and HISTORY, and if they are out of order.

Input parameter, header, is a FITS HDU header.

Output is a 2-element tuple of dictionaries of keyword values and keyword comments respectively.

pytools.fitsdiff.list_parse(name_list)

Parse a name list (a string list, not a Python list)

including the case when the list is in a text file, each string value is in a different line

pytools.fitsdiff.open_and_read(filename)

Open and read in the whole FITS file

pytools.fitsdiff.parse_path(f1, f2)

Parse two input arguments and return two lists of file names

pytools.fitsdiff.row_parse(row, img)

Parse a row in a text table into a list of values

These value correspond to the fields (columns).