Subject: Relation of Primary Header keywords to FITS image extensions

From: perry at stsci.edu (Perry Greenfield)
Date: 29 Mar 1995 18:29:24 GMT

STScI is adopting FITS with image extensions as the disk data format to
be used with the two new instruments (STIS and NICMOS) that will be
installed in the next HST servicing mission. A question has arisen in the
implementation of this data format about the relation of the keywords in
The Primary Header Unit (PDU) to subsequent Extension Header Units (EDU).
We can see a reasonable need for two different interpretations, the first
being that all subsequent headers are independent of the PHU and thus PHU
keywords do not apply. The second interpretation would have the PHU keywords
apply to some or all subsequent headers; a keyword-value pair in the PHU
would be ignored only if it were superseded in the EHU (or would not make
sense by its nature, e.g., mandatory keywords). We propose to handle both
interpretations by means of a keyword in the primary header specifying which
interpretation applies. We are proposing a local convention which consists
of the following rules:

1) with no information to the contrary, the default interpretation is that
   the PHU keywords do not apply to EHU.

2) if the EHU contains the following keyword-value pair, it will inherit
   keyword-value pairs from the PHU as long as the same keyword is not
   specified in the EHU.

INHERIT =                    T / Primary hdr keywords apply to extension hdrs

3) a FITS file with extensions could contain a mixture of EHUs that inherit
   keywords and those that don't. This scheme makes no assumptions about
   extensions added later as would placing the INHERIT keyword in the PHU.

Has anyone already dealt with this problem? Are there any comments about this
scheme? It seems that the FITS standard does not address this issue directly.

Perry Greenfield

---

From: William Pence <pence at tetra.gsfc.nasa.gov>
Date: Thu, 30 Mar 1995 15:48:57 -0500

Perry Greenfield wrote:

> apply to some or all subsequent headers;
 ...
> scheme? It seems that the FITS standard does not address this issue directly.

The HEASARC has dealt with this problem and decided to treat each HDU
as an independent unit.  We do often include a summary of all the
globally applicable keywords in the primary array header, especially
when it contains no data, but this is mainly so that a program (and
humans) can quickly determine what type of file it is just by scanning
the primary array.  In general, however, we repeat all the relevant
keywords in every HDU and our software does not assume that the primary
array keywords also apply to the extensions.  There are a number of
reasons for this:

- It is much simpler when extracting or appending extensions from one
file to another.  If one copied an extension which had the INHERIT = T
keyword from one file to another, one would presumably also have to
first copy any non-duplicated  primary array keywords from the original
file into the extension before copying it.  Then one would have to
reset INHERIT = F because one could not assume that the keywords in the
new primary array now still apply to the copied extension.

- It is much simpler when software tries to read the value of a
particular keyword from an HDU.  Under this proposed new scheme, if the
software did not find the particular keyword in the extension header,
it would then need to check if the INHERIT = T keyword was present, and
if so, go back to the primary array and search for the keyword there.

- If a program modifies the value of a keyword, or writes a new
keyword, it is not always clear whether the keyword should be written
in the primary array or in the particular extension.  The programmer
would have to specify whether it was a global keyword, and hence should
be written in the primary array, or is a local keyword and should be
written to the extension.

- FITS often uses the absence of a keyword to imply a default value, so
one would have to be very careful that a keyword explicitly given in
the primary array doesn't inadvertently override the implied value in
the extension.  For example, an image extension might supply the set of
celestial coordinate keywords, but might omit the CROTAn keyword if
there was no image rotation (the absence of this keyword is taken to
mean that CROTAn = 0.0).  The image in the primary array, however,
might have a rotation term and hence would have the CROTAn keyword,
which would then be mistakenly inherited by the extension.

So, from a practical point of view I think that this INHERIT keyword
scheme would  make the software more complicated and more difficult to
write.  It would be much simpler and straightforward to just duplicate
the necessary keywords in every HDU.

Finally, there is also the backward compatibility argument that the
large body of existing FITS software would not support this INHERIT
convention and would likely not be able to directly process these FITS
files.  Our FTOOLS package, alone, contains more than 140 programs and
about a million lines of code.  In order to make use of this resource,
one would presumably have to run the STScI FITS files though a
preprocessor to physically copy the inherited keywords from the primary
array into each extension.  Rather than have to deal with this, I
suspect that the HST users would prefer to receive their data in a
generic FITS format that any software package could deal with
directly.

-Bill Pence
HEASARC/GSFC/NASA