Subject: SAX LEGSPC FITS keywords

From: [email-masked]
Date: Thu, 3 Mar 94 08:26 EST

We are at work to define the structure and keywords for the
FITS data files for the SAX Low Energy Scintillation Proportional
Counter (LEGSPC) experiment. I have placed a draft document describing
the proposed FITS keywords and file structure for the raw data in our
anonymous ftp machine (astro.estec.esa.nl) in the file
pub/SAX/leda_0002.ps. Being a 15 page document I felt it was more
appropriate to make it available in this way rather than fill every
mailbox on heafits with it! We would like our file formats to be
compatible (insofar as possible) with the (proposed) FITS standards. I
would be grateful to any of the FITS gurus out there for any comments
they would want to make on the document.

		Fabio Favata

--
    Fabio Favata
    Astrophysics Division, European Space Agency
    P.O. Box 299, 2200 AG, Noordwijk, The Netherlands
    Tel. +31-1719-84665, Fax. +31-1719-84690
    Internet: [email-masked]
       Noi fummo i Gattopardi, i Leoni...

---

From: pence@tetra (William Pence)
Date: Fri, 4 Mar 94 16:43 EST

>pub/SAX/leda_0002.ps....

I've had a quick look at this document and am pleased to see that
SAX is attempting to adopt many of the same conventions previously
used in the ROSAT and ASCA FITS files. This should make it much
easier for multimission analysis software like Xspec to read the
SAX data once it is available.  Here are a few detailed comments.
Some of these comments reflect that fact that the current ROSAT data
format has changed somewhat from the format used as a model here.

Primary Header keywords:
------------------------

The SEQ_PI keyword should more properly be called OBSERVER.  There
is already another OBSERVER keyword that should be changed to something
else.

Can you add a DATAMODE keyword?  Is this what SETUPID is used for?

I think RDF_VERS and RDF_DATE keywords are obsolete and can be deleted.

The PROC_SYS and PROC_VER keywords can perhaps be replaced by the
CREATOR keyword to give the name and version number of the program that
generated the FITS file.

Binary Table header keywords - general comments
----------------------------

In general, it would be good to repeat the important keywords
from the primary array in each extension, such as TELESCOP and INSTRUME.
The philosophy within the OGIP has been to make each extension
relatively independent,  so that software does not have to read
the primary array header to get important pieces of information.

Time related keywords
---------------------

Defining the exact time of events within the data is of course very
important, and several more keywords need to be provided to 
describe what the times in the TIME column really represent.  
It will probably take a couple iterations to get these keywords
all right (or at least the way the OGIP timing experts here would
prefer) but as a start,  the following keywords should probably
be included:

MJDREF  - the zeropoint of the spacecraft clock, in MJD days
TSTART  - the start time of the observation in spacecraft clock seconds
TSTOP   - the stop time of the observation
TELAPSE  - = TSTOP-TSTART
ONTIME   - the actual amount of time observed (e.g. sum of all the good time 
           intervals)
TIMEUNIT - time unit of the TSTART and TSTOP keywords (presumably = 's')
TIMESYS  - time system used  

There are a few other timing related keywords that we would probably like
to see added, but I'll leave that to the timing experts to sort out,
once you know exactly what your time values represent.

Misc comments
-------------

It would save space, and look neater, to delete all the TUNITn = 'None'
keywords.  They don't serve any real purpose.

The standard unit for seconds is 's' not 'seconds'.

It would save space, and clarify the meaning of the column names
to put all the comments about the various detector flags, etc, into the
comment field of the appropriate TTYPEn keyword.

It would be useful for software to provide all the conversion scale
factors as keywords, not just as comments.  One could even give these
as TSCALn keywords so that FITS readers would automatically read the
scaled physical value, and not just the telemetry value, but this
can be confusing if users don't know the data is being scaled by the
FITS reader.

In the raw events table, is there a reason for not defining
all the columns except TIME as 'B' (byte) instead of 'I' (I*2)?
This would cut the size of the table nearly in half.

What do the RAW_X and RAW_Y keywords mean?

---

From: [email-masked]
Date: Sat, 5 Mar 94 11:39 EST

William Pence wrote:
.I've had a quick look at this document and am pleased to see that
.SAX is attempting to adopt many of the same conventions previously
.used in the ROSAT and ASCA FITS files. This should make it much
.easier for multimission analysis software like Xspec to read the
.SAX data once it is available.  Here are a few detailed comments.

	Just to avoid any misunderstanding, the FITS keywords I've
circulated are planned be used, for the moment, for the in-house
processing of SAX LEGSPC data by the ESA/ESTEC team (who built the
instrument). What the other SAX instrument groups will do in terms of
data processing and data formats, and in what format will GOs receive
their SAX data are at the moment still subject to discussion.

	Thanks for the comments, I will give them a thought and answer
to your questions.

		Fabio Favata

---

From: [email-masked]
Date: Tue, 8 Mar 94 09:33 EST

following Bill Pence comments, here are some new questions. I hope
this discussion is of general enough interest. Should it be moved to
"private e-mail" please let me know.

.Can you add a DATAMODE keyword?  Is this what SETUPID is used for?

	I don't see any problem. We got DATAMODE from the ROSAT FITS.
Does it mean that SETUPID is obsolete?

.What do the RAW_X and RAW_Y keywords mean?

	Raw detector coordinates, that is, not corrected in any way.
Again from ROSAT FITS files. Are they obsolete, too?

		fabio

---

From: [email-masked] (Mike Corcoran)
Date: Tue, 8 Mar 94 09:45 EST

> From [email-masked] Tue Mar  8 09:38:01 1994
> Date: Tue, 8 Mar 94 09:34 EST
> Sender: [email-masked] (listserv server)
> Reply-To: [email-masked]
> Originator: [email-masked]
> Sender: [email-masked]
> From: [email-masked]
> To: [email-masked]
> Subject: Re: SAX LEGSPC FITS keywords 
> X-Listprocessor-Version: 6.0 -- ListProcessor by Anastasios Kotsikonas
> Content-Length: 772
> 

Actually, in the RDF BASIC file for the ROSAT PSPC, we have the following 2 keywords:

 RAWX    =                    F / RAW X coordinates not supplied                 
 RAWY    =                    F / RAW Y coordinates not supplied  

As to SETUPID, that was a keyword needed for processing the WFC data
and is not really used for the X-ray data.

Mike Corcoran
HEASARC
Goddard Space Flight Center
Greenbelt, MD 20771
[email-masked]
HEASRC::CORCORAN

---

From: "BARRY M. SCHLESINGER" <[email-masked]>
Date: Tue, 8 Mar 94 11:18 EST

I would just like to note my particular concurrence with certain of 
the points made by Bill Pence.  Failure to mention others doesn't mean 
disagreement; it just means that I see them as issues of specific 
dataset design rather than as general FITS issues.

> comment field of the appropriate TTYPEn keyword.

In point of fact, the current comments for TTYPEn and TUNITn aren't 
very useful.  All they do is repeat the definition for the keyword.  
This type of redundant comment should be replaced with something 
meaningful.  When comments such as "/physical units of column 4" 
appeared in the binary tables proposal, they were serving the purpose 
of telling what the keyword is supposed to mean as part of the process 
of describing the format.  But in an actual data table, they don't 
provide any information and take up space that could be better used, 
for example, as

TTYPE37 = 'Norm_InterrHandler' / Normal Input Interrupt Handler 

I understand that certain FITS writers put these generic 
"label for field n" comments in automatically. They should be
regarded as fill values, to be replaced when there is any real
information, not as reasonable comments for a data file. 

> can be confusing if users don't know the data is being scaled by the

In fact, this case is no different from the primary data array or an ASCII 
table.  Users should know how their reader works, in particular 
whether they retrieve raw values from the file or automatically scale
to get physical values.  If the TSCALn were used, then the TUNITn
would be the appropriate way of giving the real physical units.  For
example 

TTYPE31 = 'Cell Pressure'
TUNIT31 = 'mbar'
TZERO31 =                  0.0
TSCAL31 =                  4.7                 

The telemetry values would still be available in the file.  What are 
most users expected to want, the physical values or the telemetry values?
If they're going to want physical values, scaling is the natural way 
to provide them.

					Barry Schlesinger
					NOST FITS Support Office

---

From: [email-masked] (Maureen Conroy)
Date: Thu, 10 Mar 94 21:37 EST

----------
X-Sun-Data-Type: text
X-Sun-Data-Description: text
X-Sun-Data-Name: text
X-Sun-Content-Lines: 1

----------
X-Sun-Data-Type: default
X-Sun-Data-Description: default
X-Sun-Data-Name: comments.wu
X-Sun-Content-Lines: 38

Fabio,
	I have reviewed your file templates briefly as well,
and will add a few comments.  I think you have a fairly old
version of ROSAT/RDF data.  There is a more recent version
in the PROS/FTP area, but you may need to get the MOST recent
version from HEASRC.
	(sao-ftp.harvard.edu	
		pub/pros_2_3/rosfits/* )

	1)  An issue for PROS compatibility are the new keyword
conventions:
	TLMINnn
	TLMAXnn
(or previously TALENnn)
	which gives the 'legal' minimum and maximum value for that
data column.  PROS uses these values to convert the EVENT list into
an IMAGE array.  (They can be entered by hand, but might as well 
include them in the file.)

	2)  ROSAT has moved the OBIB1....OBIE4 information to its
own EXTENSION 
	EXTNAME	OBITABLE
you can see this is the latest samples.  These enumerated keywords
quickly become unwieldly when NUM_OBIS gets large.

	3)  The RAW_X and RAW_Y keywords are special artifacts from
ROSAT processing and you can drop them.  They were created because
of the inconsistency between ROSAT/HRI and ROSAT/PSPC data sets
where HRI INCLUDES RAWX/RAWY data columns and PSPC does NOT.

	4)  I concur with previous comments concerning 'OBSERVER' -
it needs to be a string.  The important header keywords should
appear in each extension header.  Extensions and primary arrays
are often treated as distinct files.

					-- Maureen Conroy
					   SAO

---

From: [email-masked]
Date: Mon, 21 Mar 94 12:21 EST

Thanx to all who provided lots of comments. I would just like
to ask a couple of additional question, before I actually update our
formats. What is the current status, in terms of cross-compatibility,
of the latest FITS format for ROSAT data and for ASCA data? Can they
both (the ROSAT format Maureen has pointed me to and the ASCA formats
available from HEASARC) be assumed to be "final", or are there
upcoming changes?

		fabio