Files

Free Functions

open

pyfits.core.open(name, mode='copyonwrite', memmap=False, classExtensions={}, **parms)

Factory function to open a FITS file and return an HDUList object.

Parameters :  

name : file path, file object or file-like object

File to be opened.

mode : str

Open mode, ‘copyonwrite’ (default), ‘readonly’, ‘update’, ‘append’, or ‘ostream’.

If name is a file object that is already opened, mode must match the mode the file was opened with, copyonwrite (rb), readonly (rb), update (rb+), append (ab+), ostream (w)).

memmap : bool

Is memory mapping to be used?

classExtensions : dict

A dictionary that maps pyfits classes to extensions of those classes. When present in the dictionary, the extension class will be constructed in place of the pyfits class.

parms : dict

optional keyword arguments, possible values are:

• uint : bool

  Interpret signed integer data where BZERO is the central value and BSCALE == 1 as unsigned integer data. For example, int16 data with BZERO = 32768 and BSCALE = 1 would be treated as uint16 data.

  Note, for backward compatibility, the kwarg uint16 may be used instead. The kwarg was renamed when support was added for integers of any size.

• ignore_missing_end : bool

  Do not issue an exception when opening a file that is missing an END card in the last header.

• checksum : bool

  If True, verifies that both DATASUM and CHECKSUM card values (when present in the HDU header) match the header and data of all HDU’s in the file.

• disable_image_compression : bool

  If True, treates compressed image HDU’s like normal binary table HDU’s.

• do_not_scale_image_data : bool

  If True, image data is not scaled using BSCALE/BZERO values when read.

Returns :  

hdulist : an HDUList object

HDUList containing all of the header data units in the file.

getdata

pyfits.core.getdata(filename, *ext, **extkeys)

Get the data from an extension of a FITS file (and optionally the header).

Parameters :  

filename : file path, file object, or file like object

File to get data from. If opened, mode must be one of the following rb, rb+, or ab+.

classExtensions : dict, optional

A dictionary that maps pyfits classes to extensions of those classes. When present in the dictionary, the extension class will be constructed in place of the pyfits class.

ext :

The rest of the arguments are for extension specification. They are flexible and are best illustrated by examples.

No extra arguments implies the primary header:

>>> getdata('in.fits')

By extension number:

>>> getdata('in.fits', 0)    # the primary header
>>> getdata('in.fits', 2)    # the second extension
>>> getdata('in.fits', ext=2) # the second extension

By name, i.e., EXTNAME value (if unique):

>>> getdata('in.fits', 'sci')
>>> getdata('in.fits', extname='sci') # equivalent

Note EXTNAME values are not case sensitive

By combination of EXTNAME and EXTVER`` as separate arguments or as a tuple:

>>> getdata('in.fits', 'sci', 2) # EXTNAME='SCI' & EXTVER=2
>>> getdata('in.fits', extname='sci', extver=2) # equivalent
>>> getdata('in.fits', ('sci', 2)) # equivalent

Ambiguous or conflicting specifications will raise an exception:

>>> getdata('in.fits', ext=('sci',1), extname='err', extver=2)

lower, upper : bool, optional

If lower or upper are True, the field names in the returned data object will be converted to lower or upper case, respectively.

view : ndarray view class, optional

When given, the data will be turned wrapped in the given view class, by calling:

data.view(view)

Returns :  

array : array, record array or groups data object

Type depends on the type of the extension being referenced.

If the optional keyword header is set to True, this function will return a (data, header) tuple.

getheader

pyfits.core.getheader(filename, *ext, **extkeys)

Get the header from an extension of a FITS file.

Parameters :  

filename : file path, file object, or file like object

File to get header from. If an opened file object, its mode must be one of the following rb, rb+, or ab+).

classExtensions : optional

A dictionary that maps pyfits classes to extensions of those classes. When present in the dictionary, the extension class will be constructed in place of the pyfits class.

ext :

The rest of the arguments are for extension specification. getdata for explanations/examples.

Returns :  

header : Header object

getval

pyfits.core.getval(filename, key, *ext, **extkeys)

Get a keyword’s value from a header in a FITS file.

Parameters :  

filename : file path, file object, or file like object

Name of the FITS file, or file object (if opened, mode must be one of the following rb, rb+, or ab+).

key : str

keyword name

classExtensions : (optional)

A dictionary that maps pyfits classes to extensions of those classes. When present in the dictionary, the extension class will be constructed in place of the pyfits class.

ext :

The rest of the arguments are for extension specification. See getdata for explanations/examples.

Returns :  

keyword value : string, integer, or float

setval

pyfits.core.setval(filename, key, value='', comment=None, before=None, after=None, savecomment=False, *ext, **extkeys)

Set a keyword’s value from a header in a FITS file.

If the keyword already exists, it’s value/comment will be updated. If it does not exist, a new card will be created and it will be placed before or after the specified location. If no before or after is specified, it will be appended at the end.

When updating more than one keyword in a file, this convenience function is a much less efficient approach compared with opening the file for update, modifying the header, and closing the file.

Parameters :  

filename : file path, file object, or file like object

Name of the FITS file, or file object If opened, mode must be update (rb+). An opened file object or GzipFile object will be closed upon return.

key : str

keyword name

value : str, int, float

Keyword value, default = “”

comment : str

Keyword comment, default = None

before : str, int

name of the keyword, or index of the Card before which the new card will be placed. The argument before takes precedence over after if both specified. default=`None`.

after : str, int

name of the keyword, or index of the Card after which the new card will be placed. default=`None`.

savecomment : bool

when True, preserve the current comment for an existing keyword. The argument savecomment takes precedence over comment if both specified. If comment is not specified then the current comment will automatically be preserved. default=`False`

classExtensions : dict, optional

A dictionary that maps pyfits classes to extensions of those classes. When present in the dictionary, the extension class will be constructed in place of the pyfits class.

ext :

The rest of the arguments are for extension specification. See getdata for explanations/examples.

delval

pyfits.core.delval(filename, key, *ext, **extkeys)

Delete all instances of keyword from a header in a FITS file.

Parameters :  

filename : file path, file object, or file like object

Name of the FITS file, or file object If opened, mode must be update (rb+). An opened file object or GzipFile object will be closed upon return.

key : str, int

Keyword name or index

classExtensions : optional

A dictionary that maps pyfits classes to extensions of those classes. When present in the dictionary, the extension class will be constructed in place of the pyfits class.

ext :

The rest of the arguments are for extension specification. See getdata for explanations/examples.

writeto

pyfits.core.writeto(filename, data, header=None, **keys)

Create a new FITS file using the supplied data/header.

Parameters :  

filename : file path, file object, or file like object

File to write to. If opened, must be opened for append (ab+).

data : array, record array, or groups data object

data to write to the new file

header : Header object, optional

the header associated with data. If None, a header of the appropriate type is created for the supplied data. This argument is optional.

classExtensions : dict, optional

A dictionary that maps pyfits classes to extensions of those classes. When present in the dictionary, the extension class will be constructed in place of the pyfits class.

clobber : bool, optional

If True, and if filename already exists, it will overwrite the file. Default is False.

checksum : bool, optional

If True, adds both DATASUM and CHECKSUM cards to the headers of all HDU’s written to the file.

append

pyfits.core.append(filename, data, header=None, classExtensions={}, checksum=False, verify=True, **keys)

Append the header/data to FITS file if filename exists, create if not.

If only data is supplied, a minimal header is created.

Parameters :  

filename : file path, file object, or file like object

File to write to. If opened, must be opened for update (rb+) unless it is a new file, then it must be opened for append (ab+). A file or GzipFile object opened for update will be closed after return.

data : array, table, or group data object

the new data used for appending

header : Header object, optional

The header associated with data. If None, an appropriate header will be created for the data object supplied.

classExtensions : dictionary, optional

A dictionary that maps pyfits classes to extensions of those classes. When present in the dictionary, the extension class will be constructed in place of the pyfits class.

checksum : bool, optional

When True adds both DATASUM and CHECKSUM cards to the header of the HDU when written to the file.

verify: bool, optional (True) :

When True, the existing FITS file will be read in to verify it for correctness before appending. When False, content is simply appended to the end of the file. Setting verify to False can be much faster.

update

pyfits.core.update(filename, data, *ext, **extkeys)

Update the specified extension with the input data/header.

Parameters :  

filename : file path, file object, or file like object

File to update. If opened, mode must be update (rb+). An opened file object or GzipFile object will be closed upon return.

data : array, table, or group data object

the new data used for updating

classExtensions : dict, optional

A dictionary that maps pyfits classes to extensions of those classes. When present in the dictionary, the extension class will be constructed in place of the pyfits class.

ext :

The rest of the arguments are flexible: the 3rd argument can be the header associated with the data. If the 3rd argument is not a Header, it (and other positional arguments) are assumed to be the extension specification(s). Header and extension specs can also be keyword arguments. For example:

>>> update(file, dat, hdr, 'sci')  # update the 'sci' extension
>>> update(file, dat, 3)  # update the 3rd extension
>>> update(file, dat, hdr, 3)  # update the 3rd extension
>>> update(file, dat, 'sci', 2)  # update the 2nd SCI extension
>>> update(file, dat, 3, header=hdr)  # update the 3rd extension
>>> update(file, dat, header=hdr, ext=5)  # update the 5th extension

info

pyfits.core.info(filename, classExtensions={}, **parms)

Print the summary information on a FITS file.

This includes the name, type, length of header, data shape and type for each extension.

Parameters :  

filename : file path, file object, or file like object

FITS file to obtain info from. If opened, mode must be one of the following: rb, rb+, or ab+.

classExtensions : dict, optional

A dictionary that maps pyfits classes to extensions of those classes. When present in the dictionary, the extension class will be constructed in place of the pyfits class.

parms : optional keyword arguments

• uint : bool

  Interpret signed integer data where BZERO is the central value and BSCALE == 1 as unsigned integer data. For example, int16 data with BZERO = 32768 and BSCALE = 1 would be treated as uint16 data.

  Note, for backward compatibility, the kwarg uint16 may be used instead. The kwarg was renamed when support was added for integers of any size.

• ignore_missing_end : bool

  Do not issue an exception when opening a file that is missing an END card in the last header. Default is True.