The stpyfits module is a wrapper around the pyfits module which extends pyfits to include additional features specific to STScI. Currently, these features only include the handling of Constant Data Value Arrays in FITS files. In the future, additional features may be added to stpyfits to support other STScI unique FITS file extensions.
The stpyfits module is part of the pytools package in IRAF, IRAFX, and IRAFDEV. It may be imported and used just like pyfits. In all respects, stpyfits will behave like pyfits except when dealing with FITS files that contain Constant Data Value Arrays. The stpyfits wrapper only supports numpy arrays. The importation of both pyfits and stpyfits in the same session is supported as long as the 'from pyfits import *' and 'from stpyfits import *' syntax is not used. When both modules are imported, accessing functions through the pyfits namespace (ie. pyfits.open()) will yield the standard pyfits functionality while accessing functions through the stpyfits namespace (ie. stpyfits.open()) will yield the new stpyfits functionality.
Details regarding the stpyfits module may be found at the following link:
http://stsdas.stsci.edu/pytools/stpyfits/epydoc
At STScI, a variation to the FITS file standard has been developed to allow image data quality extensions to contain data arrays whose elements are all the same value. When written to a FITS file, these constant data value array extensions contain only a header and no data. The use of these extensions can greatly reduce the size of a FITS file and the performance when accessing it. A constant data value array extension can be identified by the presence of a PIXVALUE keyword in the header. The value assigned to this keyword is the value of each element of the data array. Because the file contains no data for this extension, the NAXIS header keyword must be assigned the value of 0, and there cannot be any NAXISn keywords to define the shape of the intended data array. Instead, there are NPIXn keywords for each array axis that define the shape of the data array.
It is desirable that accessing a constant data value array extension in stpyfits be (for the most part) transparent to the user. Therefore, when the user reads the extension from the FITS file, the header (in memory) is transformed to appear like a normal header. The value of the NAXIS keyword is set to the number of axis in the data array and the NAXISn keywords, which define the shape of the array, are provided as cards that immediately follow the NAXIS card. The NPIXn keywords are removed from the header in order to keep the number of cards in the header the same. The PIXVALUE keyword will remain in the header as a flag to indicate the data array values and that this extension is a candidate to be written to the file as a constant data value array. If the user requests the data for the extension, the data array is constructed as usual, using the shape defined in the NAXIS and NAXISn header keywords. The actual data values are not, however, read from the FITS file. They are instead assigned to the array using the value associated with the PIXVALUE keyword.
When writing to a FITS file, a constant data value array extension will be identified by the presence of the PIXVALUE keyword in the header. Note that the header will contain the normal NAXIS and NAXISn keywords that define the shape of the array and will not contain any NPIXn keywords. Before writing, the data array is examined to ensure that it indeed contains a constant value and that the value matches PIXVALUE. If all is good, the header written to the file (but not the header in memory) is transformed by setting the NAXIS keyword value to zero and removing the NAXISn keywords. NPIXn keyword cards are added after the PIXVALUE keyword card to define the shape of the array. No data is written to the file. If the array values are constant but do not match the value assigned to the PIXVALUE keyword, the PIXVALUE keyword value (in both the header in memory and the header written to the file) is changed to the constant data value before writing it to the file. If the array values are not constant, the PIXVALUE keyword card is deleted from both headers and both header and data are written to the file without transformation.
Some examples follow. Extensions 2,3,5,6,8,9,11, and 12 of the sample file are constant data value array extensions.
>>> import pytools.stpyfits as stpyfits
>>> hdulist = stpyfits.open('tmp.fits')
>>> hdulist.info()
Filename: tmp.fits
No. Name Type Cards Dimensions Format
0 PRIMARY PrimaryHDU 199 () int16
1 SCI ImageHDU 113 (1062, 1044) int16
2 ERR ImageHDU 62 (1062, 1044) int16
3 DQ ImageHDU 45 (1062, 1044) int16
4 SCI ImageHDU 113 (1062, 1044) int16
5 ERR ImageHDU 62 (1062, 1044) int16
6 DQ ImageHDU 45 (1062, 1044) int16
7 SCI ImageHDU 113 (1062, 1044) int16
8 ERR ImageHDU 62 (1062, 1044) int16
9 DQ ImageHDU 45 (1062, 1044) int16
10 SCI ImageHDU 113 (1062, 1044) int16
11 ERR ImageHDU 62 (1062, 1044) int16
12 DQ ImageHDU 47 (1062, 1044) int16
>>> hd = stpyfits.getheader('tmp.fits',3)
>>> hd['NAXIS']
2
>>> hd['PIXVALUE']
0
>>> dat = stpyfits.getdata('tmp.fits', 3)
>>> print dat
[[0 0 0 ..., 0 0 0]
[0 0 0 ..., 0 0 0]
[0 0 0 ..., 0 0 0]
...,
[0 0 0 ..., 0 0 0]
[0 0 0 ..., 0 0 0]
[0 0 0 ..., 0 0 0]]
>>> dat = dat + 2
>>> stpyfits.update('tmp.fits',dat,hd,ext=3) #Update the file with a new constant data value
>>> hd = stpyfits.getheader('tmp.fits',3)
>>> hd['PIXVALUE']
2
>>> dat = stpyfits.getdata('tmp.fits', 3)
>>> print dat
[[2 2 2 ..., 2 2 2]
[2 2 2 ..., 2 2 2]
[2 2 2 ..., 2 2 2]
...,
[2 2 2 ..., 2 2 2]
[2 2 2 ..., 2 2 2]
[2 2 2 ..., 2 2 2]]
>>> dat[2,2] = 0 #Make the data non-constant
>>> stpyfits.update('tmp.fits',dat,hd,ext=3)
>>> hd = stpyfits.getheader('tmp.fits',3)
>>> try:
... hd['PIXVALUE']
... except KeyError, e:
... print e
...
"Keyword 'PIXVALUE' not found."
>>> dat = stpyfits.getdata('tmp.fits', 3)
>>> print dat
[[2 2 2 ..., 2 2 2]
[2 2 2 ..., 2 2 2]
[2 2 0 ..., 2 2 2]
...,
[2 2 2 ..., 2 2 2]
[2 2 2 ..., 2 2 2]
[2 2 2 ..., 2 2 2]]
James Taylor, jtaylor2@stsci.edu