set_key

Context: crates

Synopsis

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

Syntax

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

Description

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.

Units

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.

Examples

Example 1

>>> 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.

Example 2

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.

Bugs

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

Refer to the CIAO bug pages for an up-to-date listing of known issues.