OFWG Report 93_002 Last Update: 1994 Sep 21

The recommendations of the OGIP FITS Working Group (OFWG) made over the period 1993 September - 1994 August are listed, along with references to the full text of recommendations not included herewithin. Any effects of these recommendations upon previously published OGIP FITS formats are also noted.

Introduction

This article is the second of an ongoing series describing the recommendations of the OFWG. As described in the first article (OFWG_93_001, George et al. 1994), the OFWG is comprised of at least one member from each group within the OGIP, and has the responsiblity of overseeing the development of FITS file formats/conventions. Meetings are held as often as necessary (usually once every two weeks), and are open to all. The minutes, recommendations and various other documents relating to the OFWG are publically available (see below).

Present Panel Members

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

Access to OFWG Information

The OFWG produces and maintains a number of documents, all of which are publically available.

Anonymous ftp

There are two areas accessible via anonymous ftp from heasarc.gsfc.nasa.gov directly related to the OFWG:

* fits_info/ofwg_minutes - containing (ASCII) files of the minutes from all OFWG meetings
* fits_info/ofwg_recom - containing (ASCII & occasionally also postscript) files of the recommendations of the OFWG, pending proposals, etc.

Also of likely interest are two other areas:

* fits_info/sample_files - containing sample FITS files used within the OGIP and/or ASCII dumps of their headers
* fits_info/fits_formats/docs - containing the format definition documents of many of the FITS files used within the OGIP, along with various other FITS-related documentation produced by the OGIP.

All these areas contain README files giving further information.

The World-Wide Web

Information regarding the OFWG is also available via the WWW. The most useful starting point is probably the URL http://heasarc.gsfc.nasa.gov/docs/heasarc/ofwg/ofwg_intro.html

All documents available via anonymous ftp are also accessible via the WWW.

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 the new full recommendations, and those recommendations overturned in the period 1993 September - 1994 August. Thus unless stated otherwise, recommendations listed in the previous document in this series (OFWG/93-001, George, et al. 1994) are still valid.

New Recommendations (since OFWG/93-001)

Recommendation R7

On the use of the CREATOR keyword

(Vote: 1993 Nov 17)

It is often useful to identify which software program created a particular FITS file. The reserved AUTHOR keyword has sometimes been used for this purpose, but this is not consistent with the original intent of the AUTHOR keyword to cite a publication. Instead, the OFWG recommends that a new keyword,

* CREATOR

be used for this purpose. When appropriate, the value of the CREATOR keyword should also reference the specific version of the program that created the FITS file, e.g.:

CREATOR = `progname v1.2.3' / Program that created this FITS file

where progname in the name of the s/w task, and 1.2.3 its version number.

It is intented that this keyword should refer to the program that originally defined the FITS file structure and wrote the contents. If a FITS file is subsequently copied largely intact into a new FITS by another program, then the value of the CREATOR keyword should still refer to the original program. HISTORY keywords should be used instead to document any further processing that is performed on the file after it is created.

Recommendation R8

On the use of the HDUCLASn keywords to provide a hierarchical classification scheme for FITS extensions

(Vote: 1994 Feb 02)

It is usually necessary not only to use a well-defined FITS format to store a given dataset, but also to INFORM a reader (either human or software) that such a defined format is in use along with details on the specific version of the format, detailed contents, etc.

The OFWG recommends that the following set of keywords be used to for such purposes in each extension:

* HDUCLASS - a character string giving a general identifier of data format used
* HDUDOC - a character string giving the document (preferably published) that describes the format/classification used
* HDUVERS - a character string giving the specific version of the document specified by HDUDOC.
* HDUCLASn - an indexed set of character strings giving the classification of data in the extension

Comments on Usage

HDUCLASn is an indexed keyword. HDUCLAS1 should provide the general data classification. HDUCLAS2-HDUCLAS9 specify subclasses within the general classification. Such subclasses can specify either modifications to the general classification or modifications to the data contained in the file.

An up-to-date list of OFWG-approved values for HDUCLASn is provided in the document hduclas.list available in the directory fits_info/ofwg_recomm of the anonymous ftp account on heasarc.gsfc.nasa.gov.

We propose that the value of HDUVERS have the form X.Y.Z, where X, Y, and Z are integers, with the following understanding:

* change in X: format has been completely redefined - software take note
* change in Y: bug fix or new keyword(s) added which may impact software
* change in Z: minor change, no impact on software

Of course, designers of data files have the option of using an existing format or defining a new format. Should it be necessary to define a new file format, the file designer(s) should provide the values of HDUCLASS, HDUDOC, HDUVERS and HDUCLASn keywords appropriate to that format if it is desired that the format be adopted as a "standard". Each value of HDUCLASS must be unique; the OGIP volunteers to keep a list of all values of HDUCLASS used.

Examples

HDUCLASS = `RDF ` / Rationalized Data Format
HDUDOC = `Arnaud et al. 1992, Legacy 2, p 65.' / format specification
HDUVERS = `1.0.0 ` / version of format
HDUCLAS1= `SPECTRUM' / spectral data format
HDUCLAS2= `BACKGROUND' / background spectrum

Recommendation R9

On the OGIP data quality flag convention

(Vote: 1994 Jul 06)

The meaning and use of quality flags is often specific to a given instrument and/or data type. However, when devising quality flags for new FITS files, the OFWG recommends that the integer value 0 (zero) be used to indicate that the data to which the flag refers is of GOOD quality, and is to be automatically used by downstream software.

An instrument/dataset/application-specific scale of non-zero quality flag values can be used to indicate why the data is considered of bad quality, the degree of `badness', and data flagged to be ignored in downstream applications by the user.

Recommendation R10

On the Keywords and definitions denoting the channel and energy boundaries

(Vote: 1994 Jul 06)

Typically, in the FITS header of a 'derived' file (such as an image, a lightcurve or a spectrum), it is desirable to have keywords which carry the information of the channel or energy boundaries/ranges used to select the data.

The OFWG recommends that channel and/or energy boundaries be recorded using the following keywords.

Channel boundary

The keywords to define lower and higher channel bounderies are:

* CHANMIN - a numeric (integer) value, m, for the lower boundary
* CHANMAX - a numeric (integer) value, n, for the higher boundary

where m & n are specified in unbinned ('raw') channels.

For those experiments which derived files could be created selecting on diffent channel coordinates (eg. PHA or PI), the coodinates type should be specified using the keyword

* CHANTYPE - a character string given the type of channel system CHANMIN & CHANMAX refer to.

Currently, the only values allowed within the OGIP are:

* CHANTYPE = 'PHA' - for observed Pulse Height Analyser channels
* CHANTYPE = 'PI' - for (converted) 'Pulse Invariant' detector channels

Energy boundary

To define the energy range of the data in a derived/product file, the keywords recommended are :

* E_MIN - a real giving the lower energy boudary
* E_MAX - a real giving the higher energy boundary
* EUNIT - character string giving the physical units in which E_MIN & E_MAX are measured (which must conform to the rules given in OGIP memo OGIP/93-001, George & Angelini 1994)

It should be stressed that E_MIN & E_MAX give the approximate (or nominal) energies of the lower boundary of the lowest channel, and the upper boundary of the highest channel included in the dataset. Any conversion between channel numbers and nominal energies should be performed using the 'EBOUNDS' extension on the appropriate detector response matrix.

Deprecated Alternatives

Within the OGIP a number of files and/or documents have used or defined different keywords to specify energies or channels boundaries. Below is a list of those different/old definitions. These old keywords should no longer be used unless they are required by existing instrument-specific software. It is strongly suggested that any such software be updated to handle the above keywords as soon as possible:

1. The memo number OGIP/93-003 (Angelini {\it et al} 1993) defines the keywords MINCHAN and MAXCHAN for the channel boundaries.

2. The previous versions of the ROSAT standard processing software (SASS) created images containing the following keywords: XS-MINCH, MINPI, MINPHA, XS-MAXCH, MAXPI, MAXPHA, XS-CHAN, PICHANS, PHACHANS.

3. The latest version of the ROSAT standard processing software (SASS) creates images where the above 9 keywords have been replaced by PIMIN, PIMAX in the case of PSPC instrument, and PHAMIN, PHAMAX in the case of HRI instruments.

Recommendation R11

On the Keywords and definitions relating to `exposure-times' and their corrections

(Vote: 1994 Jul 06)

Below are two sets of FITS keywords & definitions: List 1 gives the keywords which should be used in OGIP files to store various `exposure times' associated with a FITS dataset; List 2 gives the related keywords which should be used to store various correction factors to these times.

This set of keywords & definitions was constructed from the most common usage within X- & [[gamma]]-ray FITS files. The lack of a consistent naming convention most probably reflects the fact that most of these keywords were devised by different people in different places at different times.

The OFWG strongly recommends that these keywords (only) be used to store the various quantities within OGIP FITS files. It should be noted that only those keywords/quantities considered necessary must be included in the header of a given FITS dataset. However the OFWG suggests that where possible all know quantities are included in the header.

LIST 1 - "Exposure-time" related keywords

TELAPSE
is the time interval (in seconds) obtained as difference between the start and stop times of an observation. Any gaps due to Earth occultation, or high background counts and/or other anomalies, are included.

ONTIME
is the total "good" time (in seconds) on `source'. If a `Good Time Interval' (GTI) table is provided, ONTIME should be calculated as the sum of those intervals. Corrections for instrumental `dead time' effects are NOT included.

LIVETIME
is the total time (in seconds) on source, corrected for the `total' instrumental dead time effect. The ratio LIVETIME/ONTIME therefore gives the dead time correction value (which hence lies in the range 0.0-1.0).

EXPOSURE
is the total time (in seconds) on source, corrected for any relevant quantity used to calculate the corrected count rate. The value can include correction which are not directly related with time (e.g. collimation efficiency or vignetting). This keyword used in the header of FITS file, is a mean value when appropriate.

LIST 2 - Keywords for "Exposure-time" correction factors

DEADC

is the total correction factor for any dead time effect (i.e. LIVETIME/ONTIME), and lies in the range 0.0-1.0. Thus the multiplication of this value by the ONTIME value gives the `effective' integration time or LIVETIME (TIMEDEL in the case of a light curve). Since the total dead time of a given dataset can be the result of a multitude of instrumental/processing effects (especially related to the particular experiment, and/or processing by an onboard computer, and/or spacecraft operations), it is recommended that as well as including the total correction factor in the DEADC keyword, instrument-specific keywords are used to keep a record of the original value for the individual correction factors.

ERRCOR

Corrections are usually applied to the stored counts and the error on those counts. However, in some cases the errors can need an extra correction, different to that applied to the counts. The ERRCOR keyword contains this extra value. The value is unitless.

Eg. If the dead time is related to the sampling of the on board computer, it has been found that different correction are needed for counts (count/s) and errors. This can be generalized to all cases in which the error needs to be treated differently compared to the counts.

VIGNET

is the correction factor for the collimator response or vignetting function (depending upon the instrument) such as to enable the scientific dataset (e.g., lightcurve) to be rescaled to that which would have been obtained had the source been observed at the angle of peak collimator response (for collimated instruments) or on-axis (for instruments employing imaging optics). In both cases the value of VIGNET should lie in the range 0.0-1.0, and thus be the factor by which the scientific dataset should be divided in order to obtain the equivalent on-axis value. In both cases (but especially in the case of imaging optics) the correction factor can be a function of energy, and thus can only be used if a useful mean value can be defined. In the case of imaging optics, VIGNET should contain the the total correction factor due to vignetting and any (energy-independent) reduction in collecting area resulting from obscuration by the near-side of the mirror, support structures etc. It should be noted that historically these correction factors have often (naturally) been referred to by different names, and sometimes as the reciprical of the value defined above.

Recommendation R12

On standard strings to denote the mission, instrument and filters within X- & [[gamma]]-ray astronomy

(Vote: 1994 Jul 06)

The OFSP recommends that the strings listed in OGIP Memo OGIP/93-013 be adopted to by the High Energy community to describe the mission, instrument & filters in use for a given dataset.

This memo can be obtained via the Legacy anonymous ftp account as

* /FTP/fits_info/fits_formats/docs/general/ogip_93_013.tex (LaTeX source)
* /FTP/fits_info/fits_formats/docs/general/ogip_93_013.ps (Postscript)

Recommendation R13

The OGIP Long String Keyword Convention

(Vote: 1994 Jul 27)

The following example illustrates the OGIP Long String Keyword Convention (version 1.0):

BIGSTRNG= `This is a long string value that is continued &' / Any comments
CONTINUE `over three keywords in the& ` / may be appended
CONTINUE ` FITS header.' / after the quoted value.

The & character is used as the last non-blank character of the string to indicate that the string is (probably) continued on the following keyword (if the next keyword name = CONTINUE as described below).

Each continuation line has the keyword name = CONTINUE. Since there is no equal sign in column 9, this keyword belongs to the same class of keywords as the COMMENT and HISTORY keywords that do not have a defined value. Under our convention the continuation of the character string value is enclosed in quotes starting in column 11 (or higher) of the 80-character record. Any other characters (e.g. a comment field) may optionally follow the closing quote character on any or all of the keywords.

Finally, the following keywords should be added to the header of any FITS extension that uses this long string convention (the exact wording may change slightly):

LONGSTRN= `OGIP 1.0' / The OGIP long string convention may be used.
COMMENT This FITS file may contain long string keyword values that are
COMMENT continued over multiple keywords. This convention uses the `&'
COMMENT character at the end of a string which is then continued
COMMENT on subsequent keywords whose name = `CONTINUE'.

The presence of the LONGSTRN keyword serves to indicate that long string keywords may be present in the FITS file. The value of this keyword gives the name and version number of the specific convention that is used, which in our case is the OGIP long string convention, version 1.0. Note that the value of this keyword is a string so that it may be used to give the name of any other convention that the FITS community might eventually adopt.

Effects on Previously Published Formats

The Proposed Timing FITS File Format for High Energy Astrophysics (TIMVERSN = OGIP/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 two keywords, MINCHAN & MAXCHAN, which are now in violation of OFWG recommendation R10. Neither of these keywords significantly effect the format defined, hence no new OGIP version number of the format is therefore required. However MINCHAN & MAXCHAN should hereafter be considered replaced by CHANMIN & CHANMAX+ within the TIMVERSN =1993a format.

References

Angelini, L., Pence, W. & Tennant, A. F., 1993. Legacy, 3, 32 (OGIP/93-003).
George, I. M. (on behalf of the OFWG), 1994. Legacy, 4, 72. (OFWG_93_001).
George, I. M., Angelini, L., 1994. Legacy, 4, 57, (OGIP/93-001).

Proceed to the next article

Return to the previous article

Select another article