Subject: Coordinate keywords for Vector Column

From: pence at tetra.gsfc.nasa.gov (William Pence)
Date: Fri, 14 May 93 14:21:33 EDT

A Proposal for Coordinate Keywords Describing Vector Columns in Binary Tables

             Arnold Rots, William Pence, and Lorella Angelini
                            NASA/GSFC
                           14 May 1993

The format of FITS binary table extensions allows columns of a table to
consist of a vector of elements which may be grouped into a
multidimensional array using the TDIMnnn keyword.  By analogy with FITS
images in a primary array or IMAGE extension, there is a need to be
able to describe the world coordinate system of each axis of a
multidimensional array.  

In the document "Representations of Celestial Coordinates in FITS" by
Eric Greisen and Mark Calabretta, the following set of keywords have
been defined to represent the coordinate information in a FITS image:

	CTYPEm
	CRVALm
	CRPIXm
	CDi_j

For multidimensional arrays within binary tables, we propose the
following set of analogous keywords:

 	mCTYPnnn  - (character string) name or label for the axis
	mCRVLnnn  - (real) physical value of the reference pixel
	mCRPXnnn  - (real) reference pixel for the axis.  By definition,
                    the first pixel on each axis is centered on 1.0 
                    and ranges from 0.5 to 1.5.
	i_jCDnnn  - (real) coordinate transformation matrix value

In addition we propose the following new keyword:

	mCUNInnn  - (character string) physical units of the axis

The following conventions apply to this proposal:

- 'nnn' is an integer column number identifying the
column of the table to which the keyword applies.

- 'm' is an integer in the range 1 - 9, inclusive, identifying the
dimension of the multidimensional array to which the keyword applies.
This convention only supports up to 9 dimensions, but this could
be extended to 35 dimensions, if necessary, by allowing 'm' to be in 
the range 1 - 9, A - Z.

- 'i' and 'j' are integers defining the matrix element within
the 2-dimensional coordinate transformation matrix.  Refer
to the document "Representations of Celestial Coordinates in FITS"
by Eric Greisen and Mark Calabretta for a complete description
of this matrix.

Example FITS binary table header using this convention:

XTENSION= 'BINTABLE'           / binary table extension                         
BITPIX  =                    8 / 8-bit bytes                                    
NAXIS   =                    2 / 2-dimensional binary table                     
NAXIS1  =                  328 / width of table in bytes                        
NAXIS2  =                    8 / number of records                              
PCOUNT  =                    0 / size of special data area                      
GCOUNT  =                    1 / one data group (required keyword)              
TFIELDS =                    2 / number of fields in each row                   
TTYPE1  = 'OBJECT  '           / Name of the observed object                   
TFORM1  = '8A      '           / data format of the field: ASCII Character      
TTYPE2  = 'RATE    '           / Observe flux count rate                           TFORM2  = '80E     '           / data format of the field: 4 byte real      
TUNIT2  = 'counts/s'           / units of the RATE values
EXTNAME = 'RATEFILE'           / name of the extension

TDIM2   = '(8,10)  '           / vector is a 2-dimensional array

1CTYP2  = 'ENERGY  '           / first axis is ENERGY
2CTYP2  = 'TIME    '           / second axis is TIME
1CRVL2  =                  2.5 / ref. value of 1st axis=2.5
2CRVL2  =                  0.0 / ref. value of 2nd axis=0.0
1CRPX2  =                  1.0 / ref. pixel of 1st axis=1.0 (center of 1st bin)
2CRPX2  =                  1.0 / ref. pixel of 2nd axis=1.0 (center of 1st bin)
1_1CD2  =                  0.1 / delta between pixels in 1st axis is 0.1
2_2CD2  =                  4.0 / delta between pixels in 2nd axis is 4.0
1CUNI2  = 'keV     '           / 1st axis has units of 1000 electron volts
2CUNI2  = 's       '           / 2nd axis has units of seconds
END

In the above example, the second column of the table contains a
2-dimensional array containing the value of the observed count rate
from the source in 8 different energy bins each measured at 10
different times. The lowest energy bin is centered on 2.5 keV, and
there is a 0.1 keV energy difference between the bins.  Each row of the
array represents a different time, starting at relative time 0 with a 4
second time difference between rows.

---

From: thompson at serts.gsfc.nasa.gov (William Thompson)
Date: 17 May 93 21:26:41 GMT

>	i_jCDnnn  - (real) coordinate transformation matrix value

		(rest deleted)

Since you obviously intend to use the TDIM keyword, why don't you use the same
structure for the other keywords.  A long time ago I had proposed the following
keywords to be used in conjuction with TDIM.

	New keyword	Standard FITS equivalent

	TDESCnnn	CTYPEmmm
	TROTAnnn	CROTAmmm
	TRPIXnnn	CRPIXmmm
	TRVALnnn	CRVALmmm
	TDELTnnn	CDELTmmm

These keywords would have the same format as the TDIM keyword, since there is a
one-to-one relationship between them.

Thus your example under my system would look like

TTYPE2  = 'RATE    '           / Observe flux count rate
TFORM2  = '80E     '           / data format of the field: 4 byte real      

TDIM2   = '(8,10)  '           / vector is a 2-dimensional array
TDESC2  = '(ENERGY,TIME)'      / Axes are energy versus time
TRVAL2  = '(2.5,0.0)'          / ref. value for each axis for reference pixel
TRPIX2  = '(1.0,1.0)'          / ref. pix. of each axis=1.0 (center of 1st bin)
TDELT2	= '(0.1,4.0)'          / delta between pixels along each axis.
END

(This does assume that the names of the dimensions don't themselves contain
commas.)

My FITS reading software (written in IDL) uses the same subroutine to parse
these extra keywords as it uses for the TDIM keyword itself.  One additional
variation I allowed for was that a particular column might not have more than
one dimension, in which case there would be no TDIM keyword for that column.
In that case, I treat the '(' and ')' characters as optional, and the TDESC,
etc. keywords would have a single value, although still of type string, e.g.

TTYPE3  = 'VOLTAGE '           / voltages used for each energy
TFORM3  = '8E      '           / 8 voltage points corresponding to 8 energy pts
TDESC3  = 'ENERGY  '           / voltages are a function of energy
TRVAL3  = '2.5     '           / energy starts at 2.5 keV
TRPIX3  = '1.0     '           / ref. pixel is center of 1st bin
TDELT3  = '0.1     '           / energy points are 0.1 keV apart

>	mCUNInnn  - (character string) physical units of the axis

Well, at the time I didn't propose any equivalent keyword, but I think that
it's a good idea.  I would propose the following 

TCUNI2  = '(keV,s) '           / axes have units of 1000 eV vs seconds
TCUNI3  = 'keV     '           / energy is in 1000 eV

My proposal is similarly limited to about 7-9 axes, simply because of the
limited length of the character string.  If strings can be continued on the
next line, as also recently proposed, then my scheme doesn't have any limits in
terms of the number of dimensions that can be supported.

One thing that my proposal doesn't address is incorporating the new CD matrix
scheme into binary tables.  This is simply because this didn't exist at the
time I came up with this scheme, or else was being distributed through some
mechanism I don't have access too.  I would, however, propose the following:

	TiiiCnnn ='(CDiii001,CDiii002,...)'

where iii represents the dimension representing a complete row in the
transformation matrix.  Thus, in the example shown above one could have

T1C2    = '(0.1,0.0)'          / First row in transformation matrix
T2C2    = '(0.0,4.0)'          / Second row in transformation matrix

We have been baselining using TDESC, etc. for the data that will come down from
the SOHO satellite (launch in 1995).  Of course one always prefers ones own
scheme, but we would like to maintain compatibility with the rest of the FITS
community.  My personal feeling is that if one is going to use a keyword like
TDIM, then the keywords associated with it should be organized in the same way.
I think this is less confusing to the user.

Bill Thompson

---

From: "Clive Page, Leicester University, UK" <CGP at STARLINK.LEICESTER.AC.UK>
Date: Tue, 18 May 93 14:37 GMT

One disadvantage with the Rots/Pence/Angelini proposal that occurs to me
is that it requires some FITS keywords to start with a digit.  Although
the FITS Standard does allow this (or indeed a keyword starting with a
hyphen), it is not something that I have come across before.  Indeed I
had to look up the Standard to check that it really was permitted
(see section 5.1.2.1). Problems are quite likely to arise with FITS
readers that convert FITS files into other formats, these readers tend
to convert FITS keywords into variable (or parameter) names, and names
starting with a digit are not often permitted in these systems.  It
seems a pity to cause problems with existing software if it can be
avoided. 

Bill Thompson's proposal doesn't have this problem, and to me it also 
seems a bit neater and simpler.

Clive Page