Subject: HDUCLASn keywords (again)

From: pence at tetra.gsfc.nasa.gov (William Pence)
Date: Thu, 4 Nov 93 15:20:47 EST

A while ago we circulated a proposal for using a hierarchical
set of HDUCLASn keywords to identify the contents of a particular FITS
HDU (Header Data Unit).   This proposal was extensively debated within
the OGIP, resulting in a modified version which is attached below for
additional comments.  The main changes to the proposal are the addition
of the HDUCLASS, HDUDOC, and HDUVERS keywords that document the origin
and meaning of the HDUCLASn keyword structure used within that FITS file.
In a separate document (to be posted here shortly) we will list some
example values for the HDUCLASn keywords that we plan to use to describe
our data files.

We would appreciate any comments on this, preferably within the next 10
days.

-The OGIP FITS Working Group
-------------------------------------------------------------------------

        Proposed Keywords to Identify FITS File Formats

AUTHOR:

Office of Guest Investigator Programs FITS Working Group, NASA/GSFC

PROBLEM:

At the OGIP we have been developing general formats for
high-energy astrophysics data which can accomodate data from different
satellite observatories.  However, it is not sufficient to merely USE
one of the defined formats.  We need a way to TELL the reader (either
human or software) that we are in fact using a defined format, and to
identify the format being used.  The purpose of this proposal is to
describe our plans for providing this information.
    
PROPOSAL:   

We propose to use the following set of keywords to identify file
formats:
 
Keyword		Type		Comment
---------       ------          -------------------------------------------
HDUCLASS	string		General identifier of the institution that
                                defined this file format and the related 
                                HDUCLASn keyword values.

HDUDOC		string		Document (preferably published) that describes 	
				the format/classification used here

HDUVERS		string		version of the above document

HDUCLASn	string		classification of data in the file

EXAMPLE OF USAGE:

HDUCLASS = 'OGIP   ' /  Institution that defined this file format
HDUDOC   = 'Arnaud et al. 1993, Legacy 3, p 32.' / format reference 
HDUVERS = '1.0.0   ' / version number of this format
HDUCLAS1= 'SPECTRUM' / This is a spectral data format file
HDUCLAS2= 'BACKGROUND' / This is a background spectrum file

COMMENTS ON USAGE:

A)  HDUCLASn is an indexed keyword.  HDUCLAS1 should provide the general
data classification.  HDUCLAS2-n specify hierarchical subclasses within the 
general classification.  Such subclasses can specify either modifications to
the general classification or modifications to the data contained in
the file. 

B) The value of HDUVERS should have the form
X.Y.Z, where X, Y, and Z are integers, with the following
understanding:
	change in X: format has been completely redefined - software take note
	change in Y: bug fix or new keyword(s) added which may impact software
	change in Z: minor change, usually no impact on software

C) Designers of new FITS data files have the option of either adopting
a previously defined set of HDUCLASn keywords or defining a new set if
the data file does not fit into an existing format definition.  Should
it be necessary to define a new file format, the file designer(s)
should provide the values of HDUCLASS, HDUDOC, HDUVERS and HDUCLASn
keywords appropriate to that format if it is desired that the format be
adopted as a "standard".