[fitsbits] FITS 'keyword dictionaries'

[Joe Hourcle]

I don't know if this is considered on topic for this mailing list or
not.  If it isn't, I apologize, and would appreciate guidance on what
might be a better forum for this question.


I've been looking through the different ways that instrument teams in
solar physics document the meaning of their FITS headers, and there
doesn't seem to be a standard way to do it within our community.

In looking at the FITS website, there are example 'Keyword Dictionaries' :

	http://fits.gsfc.nasa.gov/fits_dictionary.html

As an example entry :

	NAME:         Time.date
	KEYWORD:      DATEOBS
	DEFAULT:      DATE-OBS
	INDEX:        none
	HDU:          primary & extension
	VALUE:        %s (date)
	UNITS:        
	COMMENT:      Date of observation
	EXAMPLE:      '05/04/87'
	DESCRIPTION:
	    Default date for the observation.  This keyword is generally not used
	    and is DATE-OBS keyword for the start of the exposure on the detector
	    is used.

I was wondering if this format is officially documented, or is it up to each
archive to generate however they see fit.

I say this, because I've seen some slight variances ... 'VALUE' may be a
format specification such as for sprintf ('%d'), with an optional comment
('%s (date)'), or an english word ('integer').  Or, the field 'DATATYPE'
is used in its place.


In looking through all of the keyword dictionaries I've found so far, the
possible fields include:

	KEYWORD
	NAME	     / ucd ?
	DEFAULT      / what to use if absent; a value (eg, 1.0) or another keyword
	INDEX        / value range of keyword index (eg, 'NAXISn' is 1-9)
	REFERENCE    / URL to documentation
	STATUS       / 'mandatory', 'reserved'
	HDU          / where it's valid, 'any', 'primary', 'table', 'extension', 'image'.
	VALUE        / format specification (%s) or 'string', 'integer', etc.
	DATATYPE     / 'string', 'integer', 'logical', 'real'.
	UNITS        / expected or suggested (assumed?) units for the value
	RANGE        / of the format '[min:max]', where max may be absent
	EXAMPLE      / example value
	COMMENT      / short description (to be used as default comment in FITS card)
	DESCRIPTION  / longer descriptive test

Slight variations or other similar formats:
	Units/Options / units *or* list of enumerations
	Option Flag   / 'Y'=optional, 'N'=required, 'C'=constant
 	Data Type     / Format specification; 'CHR', 'C20', 'I4', 'R4', etc.


....

The reason that I ask is that I'm trying to:

	1. Come up with recommendations for groups documenting their data
	2. Identify where two projects have incompatible definitions
	   for a given keyword.
	3. Use the resulting documentation to automatically generate
	    database structures to store the HDU, and associated
	    search interface

It's that last one that might be tricky, as I'd want to know if a
given keyword is a constant, enumeration, or infinitely variable; how
to expand coded values or bitmasks; etc.

It might be that there are other projects working on similar efforts,
but the only thing that I could find isn't directly related:

	Vocabularies in the Virtual Observatory
	http://www.ivoa.net/documents/latest/Vocabularies.html


-Joe

-----
Joe Hourcle
Programmer/Analyst
Solar Data Analysis Center
Goddard Space Flight Center