Executable Scripts¶
PyFITS installs a couple of useful utility programs on your system that are built with PyFITS.
fitsinfo¶
fitsinfo is a command-line script based on PyFITS for
printing a summary of the HDUs in one or more FITS files(s) to the
standard output.
Example usage of fitsinfo:
Print a summary of the HDUs in a FITS file:
$ fitsinfo filename.fits Filename: filename.fits No. Name Type Cards Dimensions Format 0 PRIMARY PrimaryHDU 138 () 1 SCI ImageHDU 61 (800, 800) int16 2 SCI ImageHDU 61 (800, 800) int16 3 SCI ImageHDU 61 (800, 800) int16 4 SCI ImageHDU 61 (800, 800) int16
Print a summary of HDUs of all the FITS files in the current directory:
$ fitsinfo *.fits
fitsheader¶
fitsheader is a command line script based on pyfits for printing the
header(s) of one or more FITS file(s) to the standard output in a human-
readable format.
Example uses of fitsheader:
Print the header of all the HDUs of a .fits file:
$ fitsheader filename.fits
Print the header of the third and fifth HDU extension:
$ fitsheader --extension 3 --extension 5 filename.fits
Print the header of a named extension, e.g. select the HDU containing keywords EXTNAME=’SCI’ and EXTVER=‘2’:
$ fitsheader --extension "SCI,2" filename.fits
Print only specific keywords:
$ fitsheader --keyword BITPIX --keyword NAXIS filename.fits
Print keywords NAXIS, NAXIS1, NAXIS2, etc using a wildcard:
$ fitsheader --keyword NAXIS* filename.fits
Note that compressed images (HDUs of type
CompImageHDU) really have two headers: a real
BINTABLE header to describe the compressed data, and a fake IMAGE header
representing the image that was compressed. PyFITS returns the latter by
default. You must supply the --compressed option if you require the real
header that describes the compression.
With PyFITS installed, please run fitsheader --help to see the full usage
documentation.
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:
Verify and update checksums, tolerating non-standard checksums, updating to standard checksum:
$ fitscheck --checksum either --write *.fits
Write new checksums, even if existing checksums are bad or missing:
$ fitscheck --write --force *.fits
Verify standard checksums and FITS compliance without changing the files:
$ fitscheck --compliance *.fits
Verify original nonstandard checksums only:
$ fitscheck --checksum nonstandard *.fits
Only check and fix compliance problems, ignoring checksums:
$ fitscheck --checksum none --compliance --write *.fits
Verify standard interoperable checksums:
$ fitscheck *.fits
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 a 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
'ABCDEF ' and 'ABCDEF' are considered equivalent.
--no-ignore-blank-cards
Don't ignore entirely blank cards in headers.
Normally fitsdiff does not consider blank cards when
comparing headers, but this will ensure that even
blank cards match up.
--exact Report ALL differences, overriding command-line
options and FITSDIFF_SETTINGS.
--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 on the command-line.
--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 command-line 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 command-
line unless the --exact option is specified. The FITSDIFF_SETTINGS
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.