Subject: triple precision keywords

From: pence at heawk1.gsfc.nasa.gov (William Pence)
Date: Wed, 30 Sep 1992 17:15:10 GMT

Here at the HEASARC we often need to express keyword values which have
more significant figures than can be stored in a double precision
number.  I have a proposal to handle this, but it may make it difficult
for other data systems to read the value, so I would like some
comments from others before we implement such a system.

A common example of this problem is the Modified Julian Date
which has a value something like 48043.8797453703700742
Currently, we  express this number as 2 separate
keywords, one representing the integer value, and another with the
double precision fractional value, for example:

MJDI    =                48043  /  integer portion of MJD
MJDF    = 8.797453703700742E-1  /  fractional portion of MJD

This however has several disadvantages:
	- it requires 2 keywords = 160 bytes to express the value
	- it clutters up the header with extra keywords which makes it
          more difficult for people to read
        - it makes it more difficult to adopt clear and concise keyword names
          since the last character in the name must be reserved to indicate 
          whether it is the integer or fractional part.
        - it requires that the reading and writing programs make 2 subroutine
          calls to get or put the data.

In principle there is no reason that this information could not all
be expressed in a single keyword value, like:

MJD     =      48043.8797453703700742 /  MJD

The only difficultly with this is that there has been no convenient way
to read or write values in this format, so I have proposed to add (in
fact they are already written) 2 new routines to the FITSIO subroutine
library to solve this problem.  

The new subroutines are:
    ftpkyt    - to write a keyword consisting of an integer + fraction
    ftgkyt    - to read the integer an fractional parts of a keyword value

Both routines have the same arguements:

call ftpkyt(iunit,keyword,intval,dval,comment,status)
          iunit (integer)  - the fortran unit number of the FITS file
          keyword (C*8)    - the name of the keyword to read or write
          intval (I*4)     - the integer part of the keyword value
          dval (R*8)       - the fractional part of the keyword value
          comm (C*48)      - the comment string
          status (I*4) - returned error status

The intval, dval, and comm parameters are input parameters to the ftpkyt 
routine, and output parameters in the ftgkyt routine.

The ftpkyt routine will write a new keyword in f28.16 fixed point format
which consists of an integer plus a double precision fraction.

The ftgkyt routine will read any numeric keyword value (it is not restricted
just to the special keywords written by ftpkyt) and returns the integer and fractional parts in separate subroutine parameters.

This proposal is, I believe, completely compatible with the FITS standard
and any FITS reader should be able to read keywords with this format
however the reader may not perserve all the precision unless is does
some special processing.  This does not worry me too much however since
any software that needs to use the full precision of this keyword is
bound to be highly specialized, hence it is not asking too much to require 
that the software to be able to handle this type of keyword.

The bigger issue that I see is how can the content of this keyword 
be preserved when the FITS file is read into another data system.  For
example, if a FITS image containing a keyword of this type was read and
converted to an IRAF format image file, then I would assume that the
IRAF FITS reader would not choke on this type of keyword, but that it
probably would not preserve the approximately 26 decimal places of precision
in the value.

Can anyone please comment whether keywords in this format would present
problems for their favorite data analysis system.  And if so, are these problems
severe enough that we should not attempt to use this keyword format
in our files?

-Bill Pence
pence at tetra.gsfc.nasa.gov
HEASARC::PENCE