NOTICE:
This Legacy journal article was published in Volume 5, November 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.
|
OGIP FITS Working Group Report
Recommendations of the OGIP FITS Working Group
1993 September - 1994 August
Ian M. George
HEASARC
OFWG Report 93_002 Last Update: 1994 Sep 21
Summary
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
HEASARC Home |
Observatories |
Archive |
Calibration |
Software |
Tools |
Students/Teachers/Public
Last modified: Wednesday, 20-Oct-2021 10:51:55 EDT
The Astrophysics Science Division (ASD) at NASA's Goddard Space Flight Center (GSFC) seeks a creative, innovative individual with strong teamwork and leadership skills to serve as Director of the High Energy Astrophysics Science Archive Research Center (HEASARC). This will be a permanent civil servant position. + Learn more.
|