The majority of header functions were specifically developed for use with SOFIA data pipeline products, performing tasks that are frequently required.

General Use Header Functions

There are a few general use header functions:

get_key_value() is a very simple function that retrieves a keyword value from a FITS header and if it is a string, removes leading/trailing whitespace before converting it to uppercase. If the value cannot be retrieved, a default value is returned instead (default is the string, ‘UNKNOWN’):

from astropy.io import fits
from sofia_redux.toolkit.fits import get_key_value

header = fits.Header()
header['KEY1'] = '  this should be uppercase, no leading whitespace'
print("Original header value: %s" % repr(header['KEY1']))
print("Retrieved value: %s" % repr(get_key_value(header, 'KEY1')))
print("Value for KEY2 (not in header): %s" % get_key_value(header, 'KEY2'))

Output:

Original header value: '  this should be uppercase, no leading whitespace'
Retrieved value: 'THIS SHOULD BE UPPERCASE, NO LEADING WHITESPACE'
Value for KEY2 (not in header): UNKNOWN

hdinsert() acts as a more user friendly wrapper for astropy.io.fits.Header.insert(), inserting new FITS header keywords at a specified location. If the key already exists in the header, a new value and/or optional comment may be supplied.

from sofia_redux.toolkit.fits import hdinsert

header = fits.Header()
header['KEY1'] = 1, 'comment 1'
header['KEY2'] = 2, 'comment 2'
header['HISTORY'] = 'A history entry'
hdinsert(header, 'KEY3', 3, comment='new comment')
hdinsert(header, 'INSERTED', 2.5, refkey='KEY2', after=True)
hdinsert(header, 'KEY2', header['KEY2'], comment='Replaced comment')
header

Output:

KEY1    =                    1 / comment 1
KEY2    =                    2 / Replaced comment
INSERTED=                  2.5
KEY3    =                    3 / new comment
HISTORY A history entry

SOFIA Specific Header Functions

The SOFIA DPS pipeline distinguishes keywords and history entries found in the original raw data file from those added by the pipeline. The key ‘AAAAAAAA’ (eight A’s) separates original and pipeline keywords while ‘BBBBBBBB’ (eight B’s) separates original and pipeline history entries. These values are hard coded into the kref and href variables in the sofia_redux.toolkit.fits module where:

kref = 'AAAAAAAA'  # Keywords reference key marker
href = 'BBBBBBBB'  # HISTORY reference key marker

hdinsert() is used to place pipeline specific keywords in the correct partition by setting refkey=kref or refkey=href. In addition, add_history() and add_history_wrap() are wrappers for hdinsert(), adding history entries from the pipeline at the correct location. For example, here is an excerpt of a SOFIA header:

...
PIPEVERS= '2_0_0   '           / Pipeline version
PRODTYPE= 'drooped '           / Product type
AAAAAAAA= 'Keywords reference'
RN_HIGH = '2400.   '           / Read noise for high capacitance mode
RN_LOW  = '244.8   '           / Read noise for low capacitance mode
BETA_G  = '1.0     '           / Excess noise
JBCLEAN = 'MEDIAN  '           / Jail bar cleaning algorithm
MINDROOP= '0.0     '           / minimum value for droop correction
MAXDROOP= '65535.0 '           / maximum value for droop correction
NRODROOP= '16      '           / number of rows for droop correction
HISTORY keyword AOR_ID updated to NONE on Nov 27 01:23:02 2013 UTC
BBBBBBBB= 'History reference'
HISTORY keyword PLANID updated to NONE on Nov 27 01:23:02 2013 UTC
HISTORY keyword OBJECT updated to Alpha_Ori on Nov 27 01:23:02 2013 UTC
HISTORY keyword DITHER updated to F on Nov 27 01:23:02 2013 UTC
...
HISTORY Droop: Channel suppression correction factor 0.003500

And here is the behavior of hdinsert() and add_history_wrap():

from sofia_redux.toolkit.fits import kref, hdinsert, add_history_wrap

history_function = add_history_wrap('My pipeline step')
history_function(header, "Giving an example of add_history_wrap")
hdinsert(header, 'NEW_KEY', 'hello')
header

Output:

...
PIPEVERS= '2_0_0   '           / Pipeline version
PRODTYPE= 'drooped '           / Product type
AAAAAAAA= 'Keywords reference'
RN_HIGH = '2400.   '           / Read noise for high capacitance mode
RN_LOW  = '244.8   '           / Read noise for low capacitance mode
BETA_G  = '1.0     '           / Excess noise
JBCLEAN = 'MEDIAN  '           / Jail bar cleaning algorithm
MINDROOP= '0.0     '           / minimum value for droop correction
MAXDROOP= '65535.0 '           / maximum value for droop correction
NRODROOP= '16      '           / number of rows for droop correction
NEW_KEY = 'hello   '
HISTORY keyword AOR_ID updated to NONE on Nov 27 01:23:02 2013 UTC
BBBBBBBB= 'History reference'
HISTORY keyword PLANID updated to NONE on Nov 27 01:23:02 2013 UTC
HISTORY keyword OBJECT updated to Alpha_Ori on Nov 27 01:23:02 2013 UTC
HISTORY keyword DITHER updated to F on Nov 27 01:23:02 2013 UTC
...
HISTORY Droop: Channel suppression correction factor 0.003500
HISTORY My pipeline step: Giving an example of add_history_wrap