          Add a keyword to a crate given a name and a value.

set_key(crate, keyname, value, unit=None, desc=None)

Argument
Description
crate
A Crate object such as a TABLECrate or IMAGECrate
keyname
The key name (case insensitive).
value
The value for the key; it can be a string, integer, floating-point number, or a boolean. If a keyword contains an invalid value - such as np.nan - then Crates will produce a warning when the crate is written out - such as "Unable to write key 'foo' to block. Invalid key value." - and the key will not be written out.
unit
The units of the keyword, as a string. This is optional.
desc
The description of the keyword. This is optional and may be trunctated when written out to disk.

Create, or replace, a keyword in the header of the crate. If the unit argument is not None then it is a string listing the units of the key. If desc is not None then it is used as the description of the key. If the keyword already exists, then set unit="" and desc="" to clear out the previous settings, otherwise they will be retained.

Only the crate is changed; the input file is unaffected. The write_file command can be used to save the modified crate to a file.

The add_key routine can be used to create a keyword from a CrateKey object.

The unit field can contain any text, but it is best to follow one of the standards, such as Specification of Physical Units within OGIP FITS files and Units in the Virtual Obervatory.

>>> cr = read_file("evt2.fits")
>>> set_key(cr, 'TIMEDEL', 0.00285, unit='s')

Create a new key named "TIMEDEL" with a value of 0.00285 and units of seconds, then add it to the crate.

from pycrates import *
cr = read_file('in.fits')
x = cr.get_column('x')
z = cr.get_column('z')
set_key(cr, 'XMEAN', x.mean(), unit=x.unit)
set_key(cr, 'ZMAX', z.values.max(), unit=z.unit, desc='Max of Z')
set_key(cr, 'CONV', True)
cr.write('out.fits', clobber=True)

Here we add the XMEAN and ZMAX keywords to a crate, the first with the mean of the x array and the second with the maximumn value of the z column. Since we want to copy over any unit field from the column to the keywords we use the get_column method of the crate to return a CrateData object for each column, rather than get_colvals just to return the column data. The CONV keyword is set to True before the file is written out to out.fits.

See the bug pages on the CIAO website for an up-to-date listing of known bugs.

December 2023