Subject: OGIP/93-013 - A list of standard strings for HE missions,instruments & filters.

From: "Ian M George, Code 668, NASA/GSFC, USA (Usque ad mortem bibendum)" <[email-masked]>
Date: Mon, 7 Feb 94 17:21 EST

HEA FITS gurus

At a recent OGIP FITS Working Group (OFWG) meeting, the panel made a 
preliminary recommendation ("p15.1") that a set of standard strings be 
employed to specify the mission, instrument (+sub-instrument) and filter 
in use in a given FITS dataset. In most cases these strings would of course be 
used in conjuncture with the TELESCOP, INSTRUME & FILTER keywords.

(The start of) a list of such standard strings has been constructed by 
George & Angelini, based upon comments received from within the OGIP & SAO.
This is available in the form of an OGIP Memo from anonymous ftp on 
legacy.gsfc.nasa.gov as

	caldb/docs/memos/ogip_93_013.ps			(Postscript)

We would welcome any comments or additions from the community - especially 
if the proposed strings will cause insurmountable problems to existing s/w.
We hope that most members of the High Energy community agree that it 
would be highly desirable if such a list of standards were adopted 
community-wide as soon as possible. As usual, comments of community-wide
interest should be posted to HEAFITS.

regards
Ian M George      	([email-masked])
Lorella Angelini  	([email-masked])

HEASARC NASA/GSFC

---

From: Jeff Bloch <[email-masked]>
Date: Mon, 7 Feb 94 19:53 EST

We are in the process of thinking about FITS data file formats for data
from our ALEXIS satellite. We would like to propose a set of keywords for
the six EUV/ultrasoft x-ray telescopes on our satellite. The detectors and
filters are fixed for each of the telesopes. The questions we have are:

1. What is the maximum number of characters to be considered for each keyword?

2. How should we weight considerations of description vs. itemized labeling?
   For example:  four telescopes have Al/Si/C filters. Should they all
   have a keyword like "Al/Si/C", or should they have their filter ID number
   as the keyword, such as "03479 #1", or some hybrid of the two, which would
   make a longer keyword? Part of the problem here is that at the project
   level thus far we make general distinctions between the two filter types
   we have ("AL/SI/C" and "LEX/TI/B") but at some point a user of the
   data will care about the individual calibration curves for each filter.
   The problem is simplified to some extent because each telescope has a
   single filter that will never change.

3. The question about filter names in 2 above applies to detectors. ALEXIS
   detectors have serial numbers such as "AF02", but also have unique
   photocathode materials. Two telescope detectors have MgFl photocathodes,
   and four have NaBr photocathodes. In this case it might be more tractable
   to have hybrid names, i.e. "AF01/MGFL".

4. Should we stick to upper case only?

--------------------------------------------------------------------------
Jeffrey Bloch					Office:     (505) 665-2568
Astrophysics and Radiation Measurements Group	ALEXIS Soc: (505) 665-5975
Los Alamos National Laboratory			FAX:	    (505) 665-4414
Mail Stop D436					e-mail:	    [email-masked]
Los Alamos, NM 87545
**** Goodbye SST-9 ---> Hello NIS-2 (A rose by any other name????)*******
--------------------------------------------------------------------------

---

From: "Ian M George, Code 668, NASA/GSFC, USA (Usque ad mortem bibendum)" <[email-masked]>
Date: Mon, 7 Feb 94 21:09 EST

Jeff Bloch ([email-masked]) asked a number of questions in his HEAFITS 
post with respect to keyword values for the ALEXIS satellite. The following 
'answers' are from a personal point-of-view, and do not necessarily reflect 
the view of the whole OGIP:

Jeff writes:
 > 1. What is the maximum number of characters to be considered for each keyword
 >
.... formally I believe the limit is 68 characters (plus a ' at each end).
There has been a proposal posted to FITSBITS (many months ago) by Pence & Rots 
suggesting a syntax for a continuation character/keywords for FITS cards
(Perhaps one of this guys could comment on and/or explode the proposal again).
Nevertheless, I would *hope* that the values of the TELESCOP, INSTRUME and 
FILTER keywords would be strings substantially shorter than this (!) 
 >   single filter that will never change.
.... This is a subject close to my heart, being related to calibration. 
Itemized labelling is obviously very useful prior to launch, but is rather 
cumbersome as soon as the flight filters at bolted onto the instrument. In 
this case I *think* would favour a method whereby during instrument 
calibration a hybrid scheme was used (eg FILTER = 'Al/Si/C 03479 #1'), but 
with the instrument team ID number silently dropped after launch. Thus 
user-software for "detector X" would automatically know (have hardwired 
somehow) that the filter calibration curve appropriate to 'Al/Si/C 03479 #1'
should be used. This isn't really so bad since I assume that the filter 
cal curve for 'Al/Si/C 03479 #1' would be delivered as being appropriate to 
INSTRUME = 'Detector X' anyhow.
It should be noted here that the OGIP/93-013 document is primarily aimed 
at the post-launch/data-analysis s/w phase rather than the grd-cal phase of 
a given instrument. 
 >    to have hybrid names, i.e. "AF01/MGFL".
.... Given there ought to be no ambiguity as to which photocathode material 
a given detector has after launch, I dont really see the need for a hybrid 
name - but I again assume that the appropriate calibration files 
(detector efficiencies etc etc) will be re-labeled with the appropriate 
detector string prior to delivery to users/data-analysis s/w. However I have 
absolutely no objections to a hybrid name if it makes everything clearer.
 > 4. Should we stick to upper case only?
.... No, not if you prefer not to. Personally I'm very much in favour of 
NOT mixing cases in a given string, simply because it makes it so much 
easier to describe the string over the phone ! However, in the memo there 
are a few times where cases are mixed (mostly associated with the symbols 
for elements with filters). The primary concern is to make the string as 
similar as possible to the string/acronym/appreviation that (most) users
use for the quantity.

... As a final summary on the strings to be used post-launch, I think that it
*must* be highly desireable that users receive science dataset & (access to) 
calibration files which use the same naming convention for the TELESCOP, 
INSTRUME, DETNAM & FILTER keywords. The details of the precise syntax used 
for these is kinda secondary, but should be as user-friendly (obvious) as 
possible.

Regards
Ian

PS: Jeff, let me know if you have further questions; and (if you wish) I'll be 
    happy to include the values you finally decide on for ALEXIS within 
    the memo.

---

From: "Jonathan McDowell" <[email-masked]>
Date: Tue, 8 Feb 94 08:27 EST

To follow up on Ian's comments on Jeff's Alexis questions:

  2 (Filter keywords): This *is* a tricky one. On Einstein we only
had one filter of each type so there was no need to distinguish
between, say, several Al filters. I take Ian's point that post-launch
there is no absolute need to distinguish as long as the detector
is also specified, but I think I would come down on the side of
being explicit: either "Al-Si-C 03479 #1", or better, establish
a simpler official post-launch naming scheme of "Al/Si/C-1" for
telescope AF01, etc. with a separate calibration file giving the
correspondence between the as-flown filter Al/Si/C-1 and the
actual serial number 03479 #1. This will make it clear to the
user that different calibrations are needed for filters
Al/Si/C-1 and Al/Si/C-2. (The point of having such a file
is that for a yet-to-fly mission such as AXAF we can change the
filter just before launch and only have one place to change the mapping.)

  3 (Detectors): I agree with Ian that the extra spec is not necessary.
I think this sort of information is best stuck in a small calibration
file (even if it is also hardcoded in the s/w system): a little table
giving       Detector   Photocathode  Another-Quantity
             AF01       MgFl          Magenta   ...
             AF02     ...

  4:  We stuck to upper case for these strings for Einstein
because it retained the antiquarian flavor of the mission :-)
I would suggest that case-*sensitivity* be unimportant where
possible, so don't
have distinct detector names AF02 and Af02 referring to different
detectors, but these days (/pace/ Ian) we're using email more than
the phone so we might as well use the extra clarity gained by
mixed case. This is particularly true for chemical element combinations
such as MgFl. (e.g. is the CU filter a carbon-uranium compound or
a copper filter?) 

To echo Ian's disclaimer, these are my prejudices and not official
AXAF Science Center opinions.

   - Jonathan McDowell

---

From: "BARRY M. SCHLESINGER" <[email-masked]>
Date: Tue, 8 Feb 94 12:20 EST

> 1. What is the maximum number of characters to be considered for each keyword?

It is not clear from the context whether the question is about the
keyword or the value.  The *keyword* is eight characters, with
trailing blanks to fill if necessary, and may be composed only of
upper case letters, numbers, hyphen, and underscore.  The rules for 
the *value* were basically covered by Ian George's comments. Some 
additional considerations are related to the next question.  

>    make a longer keyword? ... 

The first FITS paper specified, for the benefit of primitive computers
and FITS readers, that "Originators of FITS tapes may generate longer
strings, but should not expect recipients to decode more than the
first eight characters."  This rule has been interpreted since to mean
that information required (by the software) to read the data must be
available in the first eight characters of a string value.  This
restriction does not apply to values used only for the scientific
interpretation of the data.  In addition, FITS readers with the
eight-character limitation are not as prevalent as they may once have
been.  Nevertheless it is a good practice, though not required, to
provide meaningful and unique information in the first eight
characters of a string value. 

Also, one consideration that is not a FITS issue, and is not covered
by the FITS standard, needs to be noted. The ANSI standard for ASCII 
recommends against the use of the "#" character (hexadecimal 23) for 
international exchange unless there is agreement between sender and
recipient as to its meaning, as this character, along with nine
others, has been set aside as a national character and the meaning may
change from country to country.  It is probably wise to avoid such
characters in the values of keywords. 

> 4. Should we stick to upper case only?

I would agree with a number of the points made by Ian George and 
Jonathan McDowell.  I think that it is usually better not to mix cases 
in a string, but that it is more important that the case structure of
a standard name, such as a unit or chemical element, be properly
reproduced.  Specifically, I would concur with Jonathan's points about
not having separate detector names AF02 and Af02, and about describing
a chemical name as 'MgFl   '. 

				Barry Schlesinger
				NSSDC/NOST FITS Support Office

---

From: "BARRY M. SCHLESINGER" <[email-masked]>
Date: Wed, 23 Feb 94 12:46 EST

I have gone through the proposed OGIP standard strings and have the 
following questions and comments.

The formsats given for the keyword=value statements appear to be
missing blanks.  A keyword of fewer than eight characters must be
filled with trailing blanks. There must be a space between the "=" and
the quote beginning the characters value.  Also, the recommended form
for character string values is that they be at least eight characters,
with trailing blanks, if necessary.  While this format is not required
for optional character values, it should be followed unless there is a
compelling reasong not to.  A sample keyword=value statement would be
as follows: 
DETNAM  = 'SDB     ' 
			
Because of portability issues, underscore is preferable to hyphen.  
Hyphens are standard for some FITS usages for historical reasons, but 
the recommendation now is to use underscore rather than hyphen if 
possible.

On page 6, there is a note that all strings in subsequent sections are 
to be considerered case sensitive.  What is meant by this statement?
Because some machines, such as the VAX, cannot recognize case, no
value required by the software to read the data should be case
sensitive.  However, both upper and lower case may be used in values
needed only for the scientific interpretation of the data by the human
reader, and, in fact, should be used where their availability on
systems that recognize case will make the meaning clearer, as in units
or the names of elements.  So perhaps what is intended here is that
case is significant in understanding the meaning of the values. 

Having two meanings for the values of IPC or SSS for INSTRUME for 
EINSTEIN can be confusing. The two non-recommended definitions should 
not be allowed, unless they are there to grandfather in existing files. 
If that is the reason, then the usages should be allowed but 
deprecated -- designated as permissible for existing data sets but not 
to be used in the future.

Since data sets have been produced for a number of the experiments
included, are the designated keyword values (names) for the different
missions, instruments, detectors, and filters consistent with current 
usage by the experimental groups?  In the same context, I note that 
indexing is inconsistent from usage to usage, sometimes starting at 0, 
sometimes at 1, sometimes at other values.  Does this indexing reflect 
that used in by the teams in referring to their instrument?  Normally, 
indexing should be consistent, beginning with 1, but the actual 
designations given by the experimenters would override such a 
principle.

				Barry Schlesinger
				NOST FITS Support Office

---

From: "Jonathan McDowell" <[email-masked]>
Date: Wed, 23 Feb 94 13:23 EST

I don't understand Barry's claim that the VAX cannot recognize case.
The fact that the operating system does not recognize case is irrelevant,
as programs such as FITS readers running on a VAX (or any Fortran or
C program for that matter) are perfectly capable of distinguishing case.

   - Jonathan