(documentation written by Vicki Laidler and JC Hsu)
Functional interface in PyFITS (0.9.8)
These functions can be divided into three groups: reading, writing,
and getting information.
All arguments may be specified using keyword/argument syntax; if they
are so specified, the order in which they are provided is
irrelevant. For convenience, most functions will also accept all
arguments as positional arguments.
Keyword syntax is strongly recommended when specifying the extension
in any but the simplest cases.
Specifying the FITS extension
-----------------------------
All the read and write functions support a flexible means of
specifying the desired FITS extension, for user convenience. The
IRAF style of specifying the extension as part of the filename
(eg, 'myfile.fits[2]') will be supported in a future version, but
is not yet available.
Using the ext keyword:
---------------------
The ext keyword may be used to specify the extension by number, by
name, or as a tuple specifying name and extension version:
getdata('myfile.fits', ext=1) - extension number
getdata('myfile.fits', ext='sci') - extension name
getdata('myfile.fits', ext=('sci',2)) - extension name and version
Using the extname keyword:
-------------------------
The extname keyword may be used to specify the extension by name.
getdata('myfiles.fits',extname='sci')
Using the extver keyword
------------------------
The extver keyword may be used along to specify the extension
version, when there are multiple versions of extensions with the
same name.
getdata('myfile.fits',extname='sci',extver=2)
Specifying the extension without the keyword syntax
--------------------------------------------------
For convenience, use of the keyword syntax is not required, and
the extension may be specified as a positional argument only.
getdata('myfile.fits',2)
getdata('myfile.fits','sci')
getdata('myfile.fits',('sci',2))
Omitting the extension specification:
------------------------------------
If no extension is specified, the primary HDU will be used.
Handling ambiguity:
-------------------
Any ambiguity in specifying the extension will raise an
exception. This includes conflicting keyword specifications, as
well as insufficient specification to uniquely identify the
extension.
Read functions:
getdata(filename, [ext], [extname], [extver], [header=True])
------------------------------------------------------------
This function returns the data, and optionally the header, of the
input file's specified extension. Image data is returned as a
numarray array object; table data is returned as a recarray
object. Header data is returned as a PyFITS data object.
If the keyword argument "header" is provided and set to true, it
will return a tuple containing the data and header. Otherwise, it
returns only the data.
getdata also provides special convenience behavior for the case
where no extension is specified. If no data is found in the
primary HDU, it will default to the first extension HDU and
return its data. Only if the first extension also contains no
data will it raise an exception.
If the header keyword is set to true, and no extension is
specified, and there is no data in the primary HDU, the
header and data objects returned will both be taken from the
first extension.
If the specified extension has no data, an IndexError will be raised.
Examples:
#return data in primary HDU if present; if not, returns data in 1st
#extension
d=getdata('myfile.fits')
#return data and header in science extension
d,h=getdata('myfile.fits',ext='sci',header=True)
#returns data in 2nd extension
d=getdata('myfile.fits',ext=2)
getheader(filename, [ext], [extname], [extver])
-----------------------------------------------
This function returns the header of input file's specified extension
as a PyFITS header object.
Example:
#return primary header
h=getheader('myfile.fits')
#return header from 2nd extension
h=getheader('myfile.fits',ext=2)
getval(filename, keyword, [ext], [extname], [extver]
----------------------------------------------------
This function returns the value of the keyword in input file's
specified extension. The value is returned in a variable of the
correct type. Keyword specification is case-insensitive.
If no such keyword is found in the specified extension, an
exception is raised.
If a COMMENT or HISTORY keyword is specified, and multiple
COMMENTs or HISTORY records exist, the function returns the first
encountered.
Examples:
#Get value of NAXIS keyword from primary header.
ndim=getval('myfile.fits','naxis') #Returns an integer.
#Get value of exposure time from first extension header.
exptime=getval('myfile.fits','exptime',1) #Returns a float
Write functions:
----------------
Note that these functions do not permit you to specify the extension
name or extension version for a new extension through the keyword
arguments. These values must be set in the header object before
calling the write functions.
writeto(filename, data, header)
-------------------------------
This function creates a new output FITS file by using the input
header and data. The data must be a numarray or record array. The
header must be a PyFITS header object. writeto() will raise an
exception if the specified filename already exists.
If the header is not a primary HDU header, the output file will
have an empty primary HDU (with the minimal required header) and
the input header/data will be in the first extension.
append(filename, data, header)
------------------------------
This function appends the header/data as a new extension if the
specified file exists. If it does not exist, it creates a new FITS
file with the specified name.
update(filename, data, header, [ext], [extname], [extver]
---------------------------------------------------------
This function updates an existing FITS file extension with the
input header/data. If no such extension exists, it will raise an
exception.
Informational function:
----------------------
info(filename)
--------------
This function prints a summary of the information contained in the
FITS file to STDOUT, one line per HDU. For each HDU, the extension
number, name, and type are printed, along with the number of cards
(lines) in the header and the dimensions and type of the data (if
present). Similar to the IRAF task tables.fitsio.catfits.
Example:
pyfits.info('myfile.fits') #List info about the file.
Additional examples demonstrating extension specifications:
------------------------------------------------------------
h=getheader('input.fits') # the default extension (=0) i.e. primary HDU
h=getheader('input.fits', 0) # the primary HDU
d=getdata('input.fits', 2) # the second extension
d=getdata('input.fits', 'sci') # the HDU with EXTNAME='sci' (if there is only 1)
# the HDU with EXTNAME='sci' and EXTVER=2
h=getheader('input.fits', 'sci', 2)
h=getheader('input.fits', ('sci', 2)) # same
d=getdata('input.fits', ext=2) # the second extension
d=getdata('input.fits', extname='sci') # the 'sci' extension, if there is only 1
# the HDU with EXTNAME='sci' and EXTVER=2
d,h=getdata('input.fits', extname='sci', extver=2,header=True)
# ambiguous specifications will raise an exception
h=getheader('input.fits', ext=('sci',1), extname='err', extver=2) # don't do this
