Subject: keyword units

From: pence at tetra.gsfc.nasa.gov (William Pence)
Date: Mon, 14 Jul 1997 11:19:16 -0400

The following convention for encoding the physical units of FITS
keyword values was recently developed during discussions about the data
products for some future missions.  We would appreciate any comments
about this proposal or on any other conventions that may already exist
for encoding keyword units.

     Two routines for reading or writing keyword units using this
convention have already been implemented in the latest version of the
CFITSIO library (V1.25) on a trial basis.  Assuming that the response
is favorable, a corresponding pair of subroutines will be added in the
next release of the Fortran FITSIO library.

-----------------------------------------------------------------------

             Proposed Convention for FITS Keyword Units

                      William Pence (HEASARC)
                      Jonathan McDowell (ASC)
                      Clive Page  (Leicester)

                          14 July 1997

One deficiency of the current FITS Standard is that it does not define
a specific convention for recording the physical units of a keyword
value.  The TUNITn keyword can be used to specify the physical units of
the values in a table column, but there is no comparable convention for
keyword values.  The comment field of the keyword is often used for
this purpose, but the units are usually not specified in a well defined
format that FITS readers can easily recognize and extract.

To solve this deficiency, we propose a convention in which the keyword
units are enclosed in square brackets as the first token in the keyword
comment field; more specifically, the opening square bracket should
immediately follow the slash '/' comment field delimiter and a single
space character.  The following examples illustrate keywords that use
this convention:

1234567890123456789012345678901234567890123456789012345678901234567890123456789
EXPOSURE=               1800.0 / [s] elapsed exposure time
V_HELIO =                16.23 / [km s**(-1)] heliocentric velocity
LAMBDA  =                5400. / [angstrom] central wavelength
FLUX    = 4.9033487787637465E-30 / [J/cm**2/s] average flux

In general, the units named in the IAU(1988) Style Guide are
recommended, with the main exception that the preferred unit for angle
is 'deg' for degrees.

This convention is optional and does not preclude other conventions.

-----------------------------------------------------------------------

---

From: Peter Teuben <teuben at astro.umd.edu>
Date: Mon, 14 Jul 1997 22:32:58 -0400

> next release of the Fortran FITSIO library.

Novel idea! 

Comments/wonderings:

 1) Would it not be useful to add a keyword to "version" this 
	convention. In case it ever gets upgraded/modified? 
	Should it also not be a comment? But it could also 
	be a real keyword, in which case CFITSIO and others
	can more easily make (ab)use of it.

 2) What kind of convention is used for the convention of how
    to "express" the formulae of the units? It sounds like you
    are using a fortran convention (** for power), but with
    a blank for multiplication. Can the notation be rigourously
    written down or is there room for confusion?

	[sorry, I still don't have my copy of the IAU style guide,
	and the answer may be in that. Isn't there a web page on
	this by now?]

 3) what is the convention when something is e.g. log(flux),
    is it 
	[log(J/cm**2/s)]
    where we all understand this is 10-based log, and not something
    else?

- peter

---

From: Peter Bunclark <psb at ast.cam.ac.uk>
Date: Tue, 15 Jul 1997 10:37:29 +0100

One of the heated internal debates we had recently at the RGO was about
whether
keyword units should be SI units; we ended up putting the telescope
focus in
metres, whereas mm is far more natural.

A general point is, I think referring to the IAU style-guide is a `cop
out', 
having read the FITS Users Guide I did just that, and the style guide is
targeted
at something completely different, ie published papers.  A
machine-readable 
standard has to be far tighter.

In the example I just mentioned of telescope focus, SI units are pretty
silly in
fact, so I would welcome an official blessing on being able to use
`engineering units'.

There should be a table of combination units, eg [km s**(-1)], which
have to be strictly adhered to to make parsing easy.  So if your
velocity is standard, then your FLUX would have to be in units
of [J cm**(-2) s**(-1)]

And finally, I leave you with this thought:

DATE-OBS=          1997-07-15   / [UTC] today's date.

Peter.

---

From: pence at tetra.gsfc.nasa.gov (William Pence)
Date: Tue, 15 Jul 1997 12:25:10 -0400

Regarding the recently proposed convention for keyword units,

> 	can more easily make (ab)use of it.

One problem with a "version" keyword is that there is no rule
requiring all the keywords in a header to use the same convention.  In
cases were keywords are copied from one file to another, one could end
up with headers whose keywords use a mixture of conventions for
encoding the units string thus making a version keyword meaningless.

Both Peter Teuben and Peter Bunclark also commented on the units
strings themselves, and questioned whether SI units should be strictly
enforced, and whether there should be formal rules for constructing
compound units (such as [m/s] vs. [m s**(-1)] ).  Strictly speaking,
these questions are beyond the scope of the currently proposed
convention, in which we are simply proposing that the units string, in
whatever units or format, is enclosed in square brackets as the first
token of the comment field.

But in answer to these types of questions, several years ago the
HEASARC (also know as OGIP) FITS Working Group adopted some conventions
for specifying physical units that are documented in a memo that is
available on the Web at

legacy.gsfc.nasa.gov/docs/heasarc/ofwg/docs/summary/ogip_93_001_summary.html

This memo attempts to offer a compromise in line with the IAU
recommendations, but also allows units that are especially convenient
in astronomical applications such as deg, angstron, yr, arcsec, and
arcmin.  Prefixes (generally in powers of 3) are allowed as in: mm
(millimeter), km (kilometer), Mm (Megameter), and even Ym (yottameter =
10**24 meters).  Finally, rules for constructing compound units are
discussed, including complicated expressions involving mathematical
operations like log, ln, or sin.  Fortunately, these complicated cases
are rarely used, if at all.

The topic of units strings is probably too controversial for this memo
to be adopted as a standard, but still it should serve as a useful
starting point for other groups who are trying to establish standard
conventions for unit strings.

-Bill Pence

---

From: Lucio Chiappetti <lucio at ifctr.mi.cnr.it>
Date: Mon, 28 Jul 1997 10:14:44 +0200

On Tue, 15 Jul 1997, Peter Bunclark wrote:

> whether keyword units should be SI units; we ended up putting the telescope
> focus in metres, whereas mm is far more natural.

  Uh ?
  Aren't all decimal divider and multiplier prefixes (milli micro kilo mega
  etc.) part of SI  *AS WELL AS* the "main" units ?

  Thus "feet" or "parsecs" would not be SI, but m, km, mm etc, will !

----------------------------------------------------------------------------
Lucio Chiappetti - IFCTR/CNR - via Bassini 15 - I-20133 Milano (Italy)      
For more info : http://www.ifctr.mi.cnr.it/~lucio/personal.html             
----------------------------------------------------------------------------