Table Of Contents

Previous topic

FITS Header Schemas

Next topic

Miscellaneous Features

This Page

Executable Scripts

PyFITS installs a couple of useful utility programs on your system that are built with PyFITS.

fitscheck

fitscheck is a command line script based on pyfits for verifying and updating the CHECKSUM and DATASUM keywords of .fits files. fitscheck can also detect and often fix other FITS standards violations. fitscheck facilitates re-writing the non-standard checksums originally generated by pyfits with standard checksums which will interoperate with CFITSIO.

fitscheck will refuse to write new checksums if the checksum keywords are missing or their values are bad. Use --force to write new checksums regardless of whether or not they currently exist or pass. Use --ignore-missing to tolerate missing checksum keywords without comment.

Example uses of fitscheck:

  1. Verify and update checksums, tolerating non-standard checksums, updating to standard checksum:

    $ fitscheck --checksum either --write *.fits
    
  2. Write new checksums, even if existing checksums are bad or missing:

    $ fitscheck --write --force *.fits
    
  3. Verify standard checksums and FITS compliance without changing the files:

    $ fitscheck --compliance *.fits
    
  4. Verify original nonstandard checksums only:

    $ fitscheck --checksum nonstandard *.fits
    
  5. Only check and fix compliance problems, ignoring checksums:

    $ fitscheck --checksum none --compliance --write *.fits
    
  6. Verify standard interoperable checksums:

    $ fitscheck *.fits
    
  7. Delete checksum keywords:

    $ fitscheck --checksum none --write *.fits
    
Usage: fitscheck [options] <.fits files...>

        .e.g. fitscheck example.fits

        Verifies and optionally re-writes the CHECKSUM and DATASUM keywords
        for a .fits file.
        Optionally detects and fixes FITS standard compliance problems.

Options:
  -h, --help            show this help message and exit
  -k [standard | nonstandard | either | none], --checksum=[standard | nonstandard | either | none]
                        Choose FITS checksum mode or none.  Defaults standard.
  -w, --write           Write out file checksums and/or FITS compliance fixes.
  -f, --force           Do file update even if original checksum was bad.
  -c, --compliance      Do FITS compliance checking; fix if possible.
  -i, --ignore-missing  Ignore missing checksums.
  -v, --verbose         Generate extra output.

fitsdiff

fitsdiff provides a thin command-line wrapper around the FITSDiff interface–it outputs the report from a FITSDiff of two FITS files, and like common diff-like commands returns a 0 status code if no differences were found, and 1 if differences were found:

Usage
=====
  Compare two FITS image files and report the differences in header keywords and
data.

    fitsdiff [options] filename1 filename2

where filename1 filename2 are the two files to be compared.  They may also be
wild cards, in such cases, they must be enclosed by double or single quotes, or
they may 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 "*.fits" "/machine/data1"

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

Options
=======
--help, -h              show this help message and exit
--quiet, -q             Produce no output and just return a status code.
--num-diffs=INTEGER, -n INTEGER
                        Max number of data differences (image pixel or table
                        element) to report per extension (default 10).
--difference-tolerance=NUMBER, -d NUMBER
                        The relative tolerance for comparison of two numbers,
                        specifically two floating point numbers.  This applies
                        to data in both images and tables, and to floating
                        point keyword values in headers (default 0.0).
--no-ignore-blanks, -b  Don't ignore trailing blanks (whitespace) in string
                        values.  Otherwise trailing blanks both in header
                        keywords/values and in table column values) are not
                        treated as significant i.e. without this option 'ABC
                        ' and 'ABC' are considered equivalent.
--no-ignore-blank-cards
                        Don't ignore entirey blank cards in headers.  Normally
                        fitsdiff does not consider blank cards when comparing
                        headers, but this will ensure that even blank cards
                        match up.
--output-file=FILE, -o FILE
                        Output results to this file; otherwise results are
                        printed to stdout.

Header Comparison Options
-------------------------
--ignore-keywords=KEYWORDS, -k KEYWORDS
                        Comma-separated list of keywords not to be compared.
                        Keywords may contain wildcard patterns.  To exclude
                        all keywords, use "*"; make sure to have double or
                        single quotes around the asterisk.
--ignore-comments=KEYWORDS, -c KEYWORDS
                        Comma-separated list of keywords whose comments will
                        not be compared.  Wildcards may be used as with
                        --ignore-keywords.

Table Comparison Options
------------------------
--ignore-fields=COLUMNS, -f COLUMNS
                        Comma-separated list of fields (i.e. columns) not to
                        be compared.  All columns may be excluded using "*" as
                        with --ignore-keywords.

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 -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.