FITS HEADER INHERITANCE CONVENTION

                     Nelson Zarate, NOAO
	             Perry Greenfield, STScI

                     March 2007

INTRODUCTION

There are many instances of FITS data files where the same set of 
keywords (e.g. 'TELESCOP' or 'INSTRUME') are repeated with the same value
in every extension of a multi-extension FITS file.  In cases where there
are a large number of repeated keywords and/or a large number of
extensions in the file, the amount of file space occupied by the
duplicated keywords can become significant.  Duplicating the same keyword
in every extension header may also be undesirable if the value needs to
be modified, and thus every instance of the keyword would need to checked
for consistency.  This INHERIT keyword convention was developed to
address these issues by allowing the extensions in a FITS file to
implicitly inherit the keywords in the primary header; this prevents 
needless repetition of keywords in each extension header and provides a
mechanism for software  to easily access keywords that are shared between
different extensions.  In principle, the convention allows one to build
software that requires the user to ask only once for the value of a
specific keyword for a given extension (rather than explicitly doing two
keyword lookups, one for the extension and one for the primary header).
By using this convention software can treat the primary and extension
headers as effectively one logical header.

This convention was developed in 1995 and was extensively used in FITS
files produced at the STScI for data sets from the later generation
instruments on the Hubble Space Telescope, including STIS, NICMOS, and
ACS. Software support for this convention has been built into the IRAF
FITS Image kernel (Zarate & Greenfield 1996). This convention continues
to be used in various data sets produced by NOAO.

IMPLEMENTATION DETAILS

The INHERIT keyword in an extension header shall have a logical value of
T or F to indicate whether or not the current extension should inherit
the keywords in the primary header of the FITS file.  The INHERIT keyword
shall be defined in the extension header immediately after the mandatory
keywords.  It is recommended that this inherit convention be used only in
FITS files that have a null primary array (e.g., with NAXIS = 0) to avoid
possible confusion if array-specific keywords  (e.g., BSCALE and BZERO)
were to be inherited.

If INHERIT=F, the keywords from the primary header should not be
inherited. If the INHERIT keyword is not present, nothing should be
inferred about whether the inherit convention should apply or not
because the FITS standard says nothing regarding the relationship of
keywords in the primary header to those in an extension.  Specific 
FITS data sets may have their own implicit inheritance relationships
and nothing about the inherit convention is meant to affect any such
existing schemes.

When an application reads an extension header with INHERIT = T, it should
merge the keywords in the current extension with the primary header
keywords, with the exclusion of the mandatory keywords, and any COMMENT,
HISTORY, and blank keywords in the primary header. If the same keyword is
present in both the primary header and the extension header, the value in
the extension header shall take precedence. If an application modifies the
value of an inherited keyword in an extension, the value of that keyword
in the primary header is not affected (i.e., the application must
explicitly change the value of the primary header keyword if that is
desired). 

PRACTICAL CONSIDERATIONS

One disadvantage to using this convention is that it may be hard to
preserve the separation of the primary and extension header keywords in
software. If general utilities use the same libraries for keyword access
and merging (and there are many good reasons to do so), then copying an
extension HDU will automatically include all primary header keywords in
the resulting HDU (as might be done using IRAF's imcopy task). The value
of the INHERIT keyword should be set to F in the output HDU (i.e.,
inheritance turns itself off on propagation).  If the purpose of using
the inherit convention is to prevent the needless repetition of keywords
in extensions, this will effectively be negated if the FITS file is
propagated through a single processing operation, unless the software
takes special care to disable the automatic inheritance and propagates
the  primary header and extension header separately.  The convenience of
not requiring two keyword lookups has been transferred to an
inconvenience of trying to preserve the separation in the face of
automatic merging of the two. 

Another drawback is that users may become confused when adding or
modifying keywords to files with this convention. If the keywords have
become inadvertently duplicated (i.e., are present in both the primary
and extension headers) and the user modifies the primary keyword, they
are surprised that no change in the keyword value has taken place
(because the extension value takes precedence).  Users may also become
confused if they use a mixture of software tools, some of which show the
inherited keywords in the extension header and others that do not
support the inherit convention.  Potential future users of this
convention should carefully consider whether the benefits outweigh 
the disadvantages in their particular situation.

REFERENCES

Zarate, N & Greenfield, P 1996, "A FITS Image Extension Kernel for IRAF"
Astronomy Data Analysis Software and Systems V, ASP Conference Series,
Vol. 101