NOTICE:
This Legacy journal article was published in Volume 4, February 1994, and has not been updated since publication. Please use the search facility above to find regularly-updated information about this topic elsewhere on the HEASARC site.

The Role & Initial Recommendations
of the OGIP FITS Working Group

Ian M. George

HEASARC

OFWG Report 93_001 Last Update: 1993 Aug 28

Summary

The role of the OGIP FITS Working Group (OFWG) is described, along with summaries of its initial set of recommendations, and references to the full text of recommendations not included in this document. The effects of these recommendations upon previously published OGIP FITS formats are also noted.

It is intended that regular updates to this article will be published in subsequent issues of Legacy.

1 Introduction

By the summer of 1993, the large number of people working on FITS file format definitions within the OGIP led to a clear need to both 'regulate' this process, and to formally document FITS keyword etc. conventions of OGIP-wide interest. The OGIP FITS Working Group (OFWG; formerly known as the OGIP FITS Standard Panel) was therefore set up to to ensure new FITS definitions firstly did not violate any preexisting FITS standards/conventions, and secondly wherever possible to ensure all the immediate (and medium-term future) needs of the OGIP could be fulfilled.

1.1 Role of the OFWG

The OFWG is comprised of at least one member from each group within the OGIP (see below), and has final say in the accepted standard for keywords and other FITS-related issues within the OGIP. Panel meetings are held as often as necessary, but at least once per month, and are open to all (although only panel members are able to vote). Non-controversial issues, can also be decided through an electronic vote at the discretion on the chair.

The OFWG recognizes that many of the issues tackled are likely to be of interest to the wider FITS community, and that there should be adequate opportunity for community discussion before the OFWG makes a final decision. Indeed, the panel considers one of the prime roles of the OGIP/HEASARC to be the promotion of format standards in the High Energy community. Thus the OFWG follows a 2-stage voting procedure on submitted proposals. Assuming a proposal is considered acceptable, a preliminary OFWG recommendation is made, and this decision (along with the proposal) is announced to the community via the HEAFITS and/or FITSBITS e-mail exploder (as appropriate). At least a 2-week period is then allowed for community feedback. Once the level of feedback from the community has died down, the OFWG then dicusses this feedback, and takes a second vote usually resulting in a full OFWG recommendation. Assuming the (possibly revised) proposal is considered mature/useful, this full recommendation of the OFWG is again announced to the community via the HEAFITS and/or FITSBITS e-mail exploder.

1.2 Present Panel Members

At the time of writing, the OFWG consists of: B. Pence (HEASARC, chair), L. Angelini (HEASARC), M. Corcoran (R0SAT), K. Mukai (ASCA), I. M. George (HEASARC, secretary), T. McGlynn (GR0), and A. Rots (XTE).

2 Summary of Recommendations

For clarity, each full recommendation of the OFWG is given a sequential reference number. However, full recommendations are occasionally overturned by subsequent OFWG meetings. Below we list only those full recommendations which are still valid. The impact of these recommendations upon formats, etc. previously published in Legacy are discussed in Section 3.

Recommendation R1

On the use of underscores and hyphens in FITS keywords and column names
(Vote: 1993 Jun 30)

The OFWG recommends the use of underscores ('_') and strongly discourages the use of hyphens ('-'), as punctuation-type characters in FITS keyword names and in FITS table column names (i.e., in the value field of the TTYPEnnn keywords, where nnn is the BINTABLE column number). It is hoped that this recommendation will eliminate needless debate over which character to use when creating new keyword names and reduce confusion and errors on the part of software developers and users when entering keyword names.

The only exceptions to this recommendation are:

R1.e1 when there is already a well established precedent for using a hyphen (e.g., in the 'DATE-OBS' keyword)

R1.e2 when the hyphen is specifically used to represent a minus (negation) sign.

Recommendation R3

On standard RA & DEC keywords giving the position of the observed object, the telescope pointing, and the spacecraft axes
(Vote: 1993 Jun 30)

R3.A) Reference Frame keywords

The OFWG recommends both the following keywords are mandatory if one or more pairs of keywords specifying RA and dec (as defined in B) are given.

RADECSYS - a string denoting the stellar reference frame in use
e.g. values: 'FK4','FK5' etc.
EQUINOX - a real giving the date (in decimal years) of the Besselian epoch or Julian epoch appropriate for the specified RADECSYS.
The OSFP further recommends that the value of this keyword is restricted be either
EQUINOX = 1950.0 (for RADECSYS = 'FK4'),or
EQUINOX = 2000.0 (for RADECSYS = 'FKs')
with the latter strongly recommended for all new datasets.

R3.B) The RA and dec coordinates

In all cases listed below, the values of keywords are reals expressed in decimal degrees. Obviously only those keyword pairs considered necessary need be specified. However, the values of ALL such keyword pairs MUST be given in the same reference frame as specified by the values of the RADECSYS and EQUINOX keywords (see A).

i) The Positions of astronomical objects/sources

The OFWG recommends the position of a source is given using the keywords:

RA_OBJ
DEC_OBJ

ii) The Pointing Direction of the Instrument.

The OFWG recommends the pointing direction of the instrument is given using the keywords:

RA_PNT
DEC_PNT

where
- in the case of imaging instruments, the values of these keywords give the direction of the optical axis of the instrument (after all boresighting corrections etc. have been applied).
- in the case of non-imaging instrumentation, the values of these keywords give the direction of some other (instrument-specific) vector. It is anticipated that in most cases this will be the direction of maximum instrument sensitivity.

For instruments with <100% stable pointing accuracy, the above pair of keywords should be the mean values during the observation.

iii) The orientation of the Spacecraft

The OFWG recommends the orientation of the spacecraft (or telescope platform) is given by the specification of any/all of the following keyword pairs:

RA_SCX
DEC_SCX
RA_SCY
DEC_SCY
RA_SCZ
DEC_SCZ

giving the orientation of the spacecraft X-, Y- and Z-axes, respectively. For instruments with <100% stable pointing accuracy, the above pairs of keywords should be the mean values during the observation.

Recommendation R4

On the use of the CATIDn FITS keywords to contain (source) catalog identifications
(Vote: 1993 Aug 04)

The OFWG recommends that source identifications be coded using the following character keywords:

CATIDn.
where n is an integer 'index' in the range 1-9.

It should be stressed that the CATIDn keyword augments, rather than replaces, the standard OBJECT keyword. Furthermore, when indexed, the CATIDn keywords should only be used to give alternative identifications to the SAME source. It is NOT to be used to give identifications to multiple sources in a given observation.

Users are encouraged to use catalog abbreviations as given in the current version of 'The First Dictionary of Nomenclature of Celestial Objects' (Fernandez, Lortet & Spite 1983), it's first supplement (Lortet & Spite 1986), and any future supplements. COMMENT cards should translate any abbreviation which are used for catalogs not listed in these articles. Catalog abbreviations should be given with spaces replaced by underscores; one or more spaces should separate the catalog abbreviation from the source entry in the catalog. Ancillary information such as the reference to the catalog can, of course, be embedded in COMMENT cards.

Examples of Usage

Example 1
CATID1 = `HD 153919' / identification of source
COMMENT Henry Draper Catalog, Cannon, A., 1925 HCO

Example 2
CAT1D1 = `MPSLX 3' / identification of source
COMMENT MPSLX: The ROSAT MERGED SOURCE LIST for pointing
CAT1D2 = `HD 153919' / alternative identification of source
COMMENT Henry Draper Catalog, Cannon, A., 1925 HCO
CATID3 = `4U 1700-37' / alternative identification of source
COMMENT 4th Uhuru catalog

Example 3
OBJECT = `NORTH ECLIPTIC POLE'
CATID1 = `MPLSX 5' / identification of source
COMMENT MPSLX: The ROSAT MERGED SOURCE LIST for pointing

Recommendation R5

On the specification of physical units in FITS files
(Vote: 1993 Aug 04)

The OFWG recommends that all physical units given in FITS files conform to the standards outlined in OGIP/93-00l (George & Angelini 1994).

Recommendation R6

On the minimum & maximum actual & legal values within columns of FITS tables
(Vote: l993 Aug 27)

The OFWG recommends that should it be necessary to use keywords to store the minimum and maximum values contained within column nnn of a FITS table, the following keywords be used:

TDMINnnn
TDMAXnnn

respectively. These keywords are directly analogous to the DATAMIN and DATAMAX keywords used in association with the primary array, are have been adopted elsewhere within the FITS community.

The OFWG recommends that should it be necessary to use keywords to store the minimum and maximum legal values that may be stored within the elements of column nnn of a FITS table the following keywords be used:

TLMINnnn
TLMAXnnn

respectively. The OFWG also recommends the following for clarity:

The datatype of the keywords should be the same as that of the table column (nnn) to which they refer.
The keywords refer to all elements of a vector column.
These keywords imposed no constraints or information regarding the meaning of any null data values within the data.
The values of the keywords should be such that they should be compared to the data values stored in the column after those data values have been multiplied by/added to the values stored in the corresponding TSCALnnn and TZEROnnn keywords.
It should not be forbidden to have values of TDMINnnn < TLMINnnn or TDMAxnnn > TLMAXnnn, leaving it to individual applications as to what such situations implied.
If the keyword for the minimum value be greater than that for the maximum value (i.e., TDMINnnn > TDMAXnnn or TLMINnnn > TLMAXnnn as appropriate), then this should be taken to mean that the values had not been defined.

3 Effects On Previously Published Formats

3.1 The OGIP Spectral File Format (PHAVERSN = 1992a)

In their description of "The OGIP Spectral File Format" (PHAVERSN=1992a), Arnaud et al (1993) listed two keywords, RA-NOM and DEC-NOM, which are now in violation of OFWG recommendations R1 and R3. Luckily, these keywords were listed as optional, and do not significantly effect the format defined. No new OGIP version number of the format is therefore required, but the RA-NOM & DEC-NOM keywords should hereafter be considered replaced by RA_OBJ and DEC_OBJ within the PHAVERSN = 1992a.

It should be noted that the 4 other (optional) keywords listed in Arnaud et al which include a hyphen (DATE-OBS, TIME-OBS, DATE-END and TIME-END) are in widespread use within the FITS community and hence are exempt from recommendation R1.

The rules regarding the specification of physical units as given in OGIP/93-001 (George & Angelini 1993) should of course now be adhered to. Unfortunately a few of the values of the TUNITnnn keyword given as the examples in the Arnaud et al article violate the more recent R5 recommendation and should be thus disregarded.

3.2 The Proposed Timing FITS File Format for High Energy Astrophysics

(TIMVERSN = 0GIP/93-003)

In their description of "The Proposed Timing FITS File Format for High Energy Astrophysics" (TIMVERSN = OGIP/93-003), Angelini et al (1993) listed four keywords, RA, DEC, RA--NOM and DEC--NOM, which are now in violation of OFWG recommendations R1 and R3. Luckily, none of these keywords significantly effect the format defined. No new OGIP version number of the format is therefore required, but the RA & DEC should hereafter be considered replaced by RA_OBJ & DEC_OBJ and RA--NOM and DEC--NOM keywords replaced by RA_PNT and DEC_PNT within the TIMVERSN = 1993a.

It should be noted here also that the 4 other keywords listed in Angelini et al which include a hyphen (DATE-OBS, TIME-OBS, DATE-END and TIME-END) are in widespread use within the FITS community and hence are again exempt from recommendation R1.

References

Angelini, L., Pence, W. & Tennant, A.F., 1993. Legacy, 3, 32, (OGIP/93-003).
Arnaud, K. A., George, I.M. & Tennant A.F., 1993. Legacy, 2, 65, (OGIP/92-007).
Fernandez, Lortet & Spite, 1963. Astron Astrophys Suppl, 52, No. 4.
George, I. M. & Angelini, L., 1994. Legacy, 4, 57 (OGIP/93-001).
Lortet & Spite, 1986. Astron Astrophys Suppl, 64, No. 2.