OGIP Memo OGIP/93-003


The Proposed Timing FITS File Format
for High Energy Astrophysics Data


L. Angelini1, W. Pence1, & A. F. Tennant2
1 HEASARC, 2 X-ray Branch, NASA/MSFC


Code 668, NASA/GSFC,
Greenbelt, MD 20771


Version: 1994 Nov 30

LOG OF SIGNIFICANT CHANGES


Release Sections Changed Brief Notes
Date
1993 Mar Version Published in Legacy
1994 Nov 30 All Made compatible with LaTeX2HTML software
2007 Mar 19 All Made compatible with tth software (M. Corcoran)
2014 Aug 25 All typos fixed (M. Corcoran)

Contents

1  INTRODUCTION
2  General Description of a FITS Rate File
3  FITS Characteristics Used in this Document
4  Keywords in the Rate File Header
    4.1  Descriptive Keywords
    4.2  Time Definition Keywords
    4.3  TIME Column
    4.4  Time Correction Keywords
        4.4.1  Barycentric correction
        4.4.2  Time assignment
        4.4.3  Timing accuracy
    4.5  Total Exposure
    4.6  Intensity
    4.7  Background
    4.8  Dead Time Correction
    4.9  Collecting Area
5  Rate Table Formats
    5.1  Event List
    5.2  Binned Data
        5.2.1  Equispaced binned data
        5.2.2  Non-equispaced binned data
    5.3  Packet Data
6  Ancillary Information
    6.1  Barycentric Corrections
    6.2  Energy Boundary Information
    6.3  Good Time Intervals
    6.4  Exposure
7  Example Files
    7.1  The Primary Header
    7.2  Data Extension

1   INTRODUCTION

This is the first version of a document that defines a mission independent high-energy astrophysics FITS format for Rate Files, a class of data file which contains information about the variation in source intensity as a function of time. These files are also sometimes referred to as `light curves' or `event lists', depending on their content. The standard FITS formats defined here will be used by the HEASARC. It is hoped that other groups will also adopt these formats to reduce the proliferation of incompatible formats and to promote easier interchange of data between different projects and different software packages. This is a proposed standard which we expect to be updated as we and others gain experience with it. Wherever possible we will make revisions to the standard compatible with earlier versions.
These Rate File format definitions are, by necessity, as general as possible because different experiments can generate widely different types of information which must be included in the file. Thus, while these formats promote certain standards, file designers will still have considerable flexibility in defining a format to suit any particular data set. This document only specifies the minimum set of required keywords and data columns in a Rate File necessary to calculate the `correct' time and the associated intensity. To achieve this goal in a mission independent way, some mission-specific values are hidden in `standard' keywords. It is strongly encouraged that additional mission-specific keywords and/or columns be included in the Rate Files to preserve the original data in their original format. This allows users of the file to verify the accuracy of any conversions that have been performed on the data.
A general description of the FITS file organization is given in section 2. The FITS conventions used in the document are described in section 3. Section 4 is dedicated to the header keywords which define time, intensity and their corrections. The table format is described in section 5.

2  General Description of a FITS Rate File

The Rate Files are implemented using the FITS binary table extension format. This requires that the Rate File be preceded by a FITS primary array, but in most cases this will simply be a null array (with NAXIS = 0). A null primary array is not compulsory, however, and the primary array may be used to store any related data (e.g., a map of the source).
The header of the Rate Data File extension must contain a minimum set of keywords which describe the data and define various times associated with the observation. This is then followed by the Rate Table which may be given in one of four formats:
  • Event: A table of time measurements for a discrete set of events, e.g. the arrival times of X-ray photons.
  • Equally Spaced: A table of binned intensity measurements at equally spaced time intervals.
  • Unequally Spaced: A table of binned intensity measurements at unequally spaced time intervals.
  • Packet: Histogram array of timing or PHA information stored for a single reference time. The interval between each row maybe equispaced or unequally spaced.
For unequally spaced and event data, a TIME column that specifies the time of each event or bin measurement is required. The times may be specified either as an absolute time or as a time offset relative to a reference time specified in the header. For equally spaced data, the time associated with each measurement is calculated from a start time and the delta time interval which are given as keywords in the Rate File header.
Rate Data Tables which contain binned data require a column containing the intensity measurements. In the case of multichannel instruments (for which more than one energy band is sampled), this column may contain an array of simultaneous intensity measurements in different energy bands. The Rate Data table may have additional columns containing various corrections either to the time or to the intensity columns. Alternatively, the correction information may be included in a separate FITS extension appended to the Rate file.

3   FITS Characteristics Used in this Document

This section describes a number of FITS standard characteristics and conventions which are used in the Rate file definition. Some of those conventions are based on the FITSIO interface (Pence 1992).
Every column in the FITS binary table extension requires at least 2 keywords to define the name of the column and the intrinsic data type of the data, e.g.,

TTYPEn  = 'TIME    '           / time
TFORMn  = 'D       '           / data format of the field: DOUBLE PRECISION

where the `n' in the keyword names represents the number of the column in the table. The value field of TFORMn is a character string describing the data type in the field n. The values permitted are: L, logical; X, bit array; B, byte; A, ASCII characters; I, 16-bit integer; J, 32-bit integer; E, 32-bit floating point; D, 64-bit floating point. In addition, three optional keywords may be supplied for each column which specify the units and the coefficients of any linear scaling that must be applied to the numerical values in the FITS file:

TUNITn  = 's       '           / physical unit of field - seconds
TSCALn  =        .0023         / scaling factor for the column
TZEROn  =       15400          / scaling offset for the column

The scaling is defined as
physical value = (FITS file data value) * TSCALn + TZEROn
and is automatically and transparently applied to the data when the FITS file is read using FITSIO. This scaling feature provides a very useful and convenient way to compress the size of some data files by representing certain columns by scaled 1, 2, or 4-byte integers rather than 4-byte or 8- byte floating point values. For example, the TIME column in a Rate Table is generally read as a double precision value (8-bytes), however, some data sets do not require this much numerical precision. Therefore, the times could be recorded as scaled integer values with a significant saving in file space. A column parameter can be represented by an array rather than a single value (e.g. counts in different energy ranges). In the FITS standard representation, this information is stored in the TFORM value which for an array of size m is defined as:

TFORMn  = 'mD       '          / data format of the field: DOUBLE PRECISION

The FITS format also provides a mechanism for specifying an undefined value in any column. If the column has a floating point format then a special reserved bit pattern, called a Not a Number, NaN, is placed in the column. In the case of integer columns a keyword called

TNULLn  =            -99       / value used to represent an undefined value

must be included in the header to define the number to be used to represent null values. The order that columns are included in a Rate File is not significant. Any software which reads a Rate File should always locate a given column by searching for the appropriate column name as stored in the TTYPEn keywords.
Several conventions are used in the file:
  • Some parameters can be represented either as a column (if the value varies in different rows of the table), or as a keyword (if the value is a constant for every row of the table). The same name is adopted in either case and can be no longer than eight characters.
  • If a column parameter is described as an array rather than as a single value, e.g. intensity values in different energy ranges, the header keywords describing quantities related to the generic element in that array (e.g. background value to be subtracted at the element n in the array) are truncated to be eight characters long: five to describe the quantity and three for the related element number in the array.

4  Keywords in the Rate File Header

This section describes the minimum set of keywords that should be supplied in the header of every Rate file. In particular, the keywords which define the time, the time corrections, and the area are discussed. Any number of additional mission-specific keywords may also be included in the Rate Files to describe the data more fully and to preserve important parameters from the original data sets. The extension name is RATE or EVENTS.

4.1  Descriptive Keywords

The following keywords should be provided at a minimum to describe the general characteristics of the data:

EXTNAME = 'EVENTS'           / rate file type: RATE or EVENTS
TELESCOP= 'ASTRO-D'          / mission or telescope name
INSTRUME= 'SIS'              / instrument name
FILTER  =                    / if filter has been used 
OBJECT  = 'CEN X-3'          / name of the observed object
RA      =                    / source right ascension in degree 
DEC     =                    / source declination in degree 
RA--NOM =                    / r.a. nominal pointing in degree
DEC--NOM=                    / dec. nominal pointing in degree
EQUINOX = 2000.0             / equinox for ra and dec
RADECSYS= 'FK5'              / world coord. system for this file (FK5 or FK4)
DATE-OBS= '09/07/93'         / date of observation start (dd/mm/yy)
TIME-OBS= '01:02:26.003'     / time of observation start (hh:mm:ss.ddddd)
DATE-END= '09/07/93'         / date of observation end (dd/mm/yy)
TIME-END= '02:45:02.45'      / time of observation end (hh:mm:ss.ddddd)
ORIGIN  = ' Goddard'         / who produced the fits file
DATE    = '26/08/93'         / when the fits file was created
TIMVERSN= 'OGIP/93-003'      / OGIP memo number where the convention used
                             / in the file are described.
AUTHOR  = 'FRFREAD v3.4'     /name of program that produced this file
HISTORY  Description of how, where, and when the data file was produced.
HISTORY  More than one line can be used.

Some of the above keywords are fully described in the NASA/OSSA Office of Standards and Technology (NOST) 1992 document. Following the standard method for time definition, DATE-OBS, TIME-OBS, DATE-END, TIME-END should be included in every Rate File. However the values of these keywords do not necessarily have the full numerical accuracy needed for precise timing analysis. The FILTER keyword is inserted when a filter has been used in conjunction with the detector. The TIMVERSN keyword keeps a record of which version of this document has been used to write the current Rate file. If changes and/or new definitions for keywords are needed, a new version of this document will be issued. The software accessing the Rate file by looking at this keyword, if found, should understand which `standard' has been used and give a warning if that standard is not followed. RA and DEC are the coordinates of the source from which the `timing' data in the Rate file come, while RA-NOM (or RA_NOM)and DEC-NOM (or DEC_NOM) are the coordinates of the position at which the instruments were pointing during the observation. The pointing of the instrument should be inserted whenever possible for completeness. With the exception of EXTNAME, these descriptive keywords should also be inserted in primary header, although this is not compulsory.

4.2  Time Definition Keywords

Different missions provide time information in a variety of ways. There are differences not only in the units and reference time used (zero point for the clock counting), but also in whether or not time corrections have been applied. There are two ways to handle this diversity in time information. One approach is to convert the time from different missions into a standard absolute time frame: this can be quite complicated and prone to error. Another approach is to store the time as close as possible to the original reference frame chosen by each mission. In the second approach, it is easier to correct the time in a data set if errors are discovered in the time/clock calibration. In addition, if information is not available to compute an absolute time, it is still possible to perform some timing analyses on the data set. The disadvantage, in this latter approach, comes in combining data from different missions, for it can be time consuming to understand the reference time convention and to adjust it to a common time frame. A compromise between the two approaches-and the one used here-is not to manipulate the data values, but to provide auxiliary information, when possible, to construct the time in an `absolute/known' frame in a standard fashion. This allows the analysis software to make the conversion.
Below is the description of the proposed scheme for time definition. The related correction to be applied to the time are discussed in the next section. These time parameters may be given as a single keyword or may be specified using two keywords to express the integer and the fractional part of the time value separately. The choice between using one keyword or a pair to describe time is to provide precision when it is required. Any software which accesses those files should first search for the paired keywords and only use the single valued times if the paired keywords are not found.
Double keywords:


MJDREFI =             44238     / integer portion in MJD for reference time
MJDREFF =  0.0000000000000000   / fractional portion of MJD for reference time
TSTARTI =                       / integer portion of start time
TSTARTF =                       / fractional portion of start time 
TSTOPI  =                       / integer portion of stop time
TSTOPF  =                       / fractional portion stop time
TIMEZERI=                       / time zero integer used to calculate the
                                  n-time event or the n-time bin
TIMEZERF=                       / fractional portion of TIMEZERI

Single keywords


MJDREF  =                        / MJD for reference time
TSTART  =                        / start time
TSTOP   =                        / stop stop
TIMEZERO=                        / zero time used to calculate the
                                   n-time event or the n-time

In both cases the following keywords are required:
TIMESYS =                        / the system use to the define time
TIMEUNIT=                        / Unit for TSTART, TSTOP, TIMEZERO
                                   valid also for the two keywords 
                                   rapresentation
CLOCKCOR=                        / if time corrected to UT

  • TIMESYS records the time frame system used in the file. Standard values are MJD, JD, or TJD to define the various Julian day representations. If the time system is defined from an arbitrary UT time, the value is given in decimal years. The ROSAT data are timed relative to a reference time in MJD, so TIMESYS=`MJD'. EXOSAT data, by contrast, are timed from Jan 0, 1980, i.e. TIMESYS= '1980.00'.
  • TIMEUNIT gives the time unit used for the TSTART, TSTOP, and TIMEZERO keywords. TIMEUNIT is used by the software to make the value of the keywords compatible either with the internal conventions of the software, or with the units of the `TIME' column. TIMESYS does not implicitly define the units, with the exception of the various Julian Day representations. The recommended units code follows the IAU convention, i.e. `s' for second and `d' for day, and is described in OGIP/93-001 (George and Angelini 1993). If `s' is specified it is assumed that all the time header keywords are in units of seconds (TSTART, TSTOP and TIMEZERO).
  • TSTART, and TSTOP give the start and the stop time in the TIMESYS frame with the units specified by the TIMEUNIT keyword. These keywords should always be present, regardless of whether the data are equispaced, non-equispaced or given as an event list. Keeping TSTART and TSTOP values in the header speeds up a number of calculations, e.g. the observation duration.
  • TIMEZERO is used to calculate the time for each bin or event in the table. To reconstruct the full time of the nth event or bin, a residual or a delta time is added to a `start' value. This `start' value is stored in the TIMEZERO keyword (see section 5). The resulting time is in the time frame defined by TIMESYS and in units of TIMEUNIT.
  • CLOCKCOR specifies whether the time (namely TSTART, TSTOP, TIMEZERO) given in the system defined by TIMESYS has been corrected for any drift in the spacecraft clock relative to UT. The values allowed for this keyword are YES, NO or UNKNOWN. The method to correct for the clock drift is not discussed in this document because it is mission specific and should be part of the calibration information provided for each mission. Note that if the keyword value is YES then it is assumed any leap seconds are correctly accounted for.
  • MJDREF is the reference time adopted for each mission. Usually different missions have different reference times, defined using a convenient unit system (e.g. EXOSAT uses the reference time 1-1-1980 00:00:00, ROSAT uses MJD=48043.879745364201881). The reference time is the only time information which is not affected by any mission specific correction (e.g. spacecraft clock drift), and therefore can be given in a `known' system. The proposed `known' system in which the reference time for each mission should be written is Modified Julian Days (MJD), using the following convention MJD=JD-2400000.5. This reference time is given as a safety net to ensure that a time is given in the header that is in a standard form, independent of the time system adopted for the mission.
The MJDREF, TSTART, TSTOP, and TIMEZERO are double precision numbers. These keywords are related to the column TIME. In general only TIMEZERO, TIMEUNIT and TIMESYS are required to reconstruct the time of each row in the FITS file.

4.3  TIME Column

For event and unequally spaced data, a TIME column is required, containing either the tagged time for each event or the time of the center of the bin. The content of the column can be either the complete time (from year down to ms) or the residual from a value stored in the TIMEZERO keywords. If TIMEZERO is missing or 0, the time in the TIME column is the complete time expressed in the system defined by TIMESYS. The TIME column values in the case of binned data always refer to the center of the bin. The units are stored in the TUNITn keyword. Again, the recommended unit abbreviations are `s' for seconds and `d' for days.

4.4  Time Correction Keywords

Several additional keywords are available to indicate which corrections, if any, have been applied to the time of each bin or event.

4.4.1  Barycentric correction

To compare data sets from different missions (meaning not only data from satellites but also from ground observatories) a common `reference frame' for time is adopted. This means that the time tagged in the `local frame' needs to be recalculated in the common `reference frame'. This changing of frame is usually known as the `barycentric correction' because the time (recorded in the satellite reference frame) is calculated at the barycenter of the solar system. In principle, other `reference frames' can be adopted (e.g. Earth or Sun). The TIMEREF keywords specifies in which reference frame the times given in the file (namely the TSTART, TSTOP, TIMEZERO and/or the TIME column) are calculated. The values for the TIMEREF keyword are: LOCAL, SOLARSYSTEM, HELIOCENTRIC or GEOCENTRIC. These values refer to times given in the rate table being calculated in the local frame, the barycenter of the solar system, the Sun or the Earth, respectively.

TIMEREF = 'LOCAL' / other values LOCAL, SOLARSYSTEM, HELIOCENTRIC,GEOCENTRIC

If TIMEREF is LOCAL, it means that the time is in the `local frame' (e.g. satellite frame). In this case, the time calculated in a different frame may have been stored in the file in the RATE (or EVENTS) extension as a column. If the correction from the LOCAL frame to a different frame does not vary rapidly for a given interval, it is possible to store in an extension (TIMEREF) only the correction value which can be either added to the time written in the TIME column or added after an interpolation between the correction times. The choice between the two representations, i.e. column or extension, should be done considering how quickly the time correction changes for a given observation time interval. The column representation is described below. The table extension representation (EXTNAME= 'TIMEREF') is described in section 6.

Column Representation The column name should reflect the reference frame in which the time has been calculated:

TTYPEn  = ' 

The units of the value stored in the column are in the TUNITn keyword, as required by the FITS standard (see TUNIT, TSCAL and TZERO rules). The content of the column is the time calculated in a different reference frame, in other words, it should be treated as a second TIME column. A new set of keywords with the same meaning of TSTART, TSTOP is needed to define those values in the new reference frame. If the secondary time column only contains the offset value from a zero time, then the equivalent of the TIMEZERO keywords, defined for the TIME column, should be given to reconstruct the full time for the nth bin or event. These keywords should be ESTART, ESTOP and ETIMEZER, if the column is REFEARTH; SSTART, SSTOP and STIMEZER for REFSUN; and BSTART, BSTOP and BTIMEZER for the REFBSOLS.

4.4.2  Time assignment

The TASSIGN keyword specifies where the time assignment of the data is done. This keyword should clarify whether the time as been assigned according to the satellite clock, namely the time at which the photon arrived at the satellite, or to any other clock. This information is relevant when time corrections (e.g. barycenteric correction) are calculated. For example, the EXOSAT time assignment was made at the Madrid tracking station, so TASSIGN=`Madrid'. The value `SATELLITE' should be used if the assignment is at the satellite. If TASSIGN is a position on the Earth, this should be specified using the following self-explanatory keywords: GEOLAT, GEOLONG and ALTITUDE.

4.4.3  Timing accuracy

There are two types of timing error which can be specified: relative error and absolute error. The first is dominated by the clock accuracy and should be expressed as a dimensionless rate. The second gives the `absolute' precision of the timing measurement. This precision should include all contributions from uncertainties in the barycentric corrections or any other timing corrections that have been applied and can be expressed in units of seconds.

TIERRELA=          5.5e-7 / relative errors express as rate
TIERABSO=          0.1    / timing  precision  (seconds)

Knowledge of the timing error is important when comparing different data sets obtained in different ways. This type of ancillary information is often very difficult to track down if not included in the file. Therefore we encourage people who produce FITS rates file to try always to include this information.

4.5  Total Exposure

The keyword ONTIME gives the total time in seconds on source. This value will include a leap second if one occurred during the observation. The value does not include any dead time correction.

ONTIME  =      1000.     / total time on source in seconds.

4.6  Intensity

For binned data, the rate table should have a column containing the intensity of the source detected in the integrated bin. The intensity in each bin can be represented as counts or as a rate. The counts representation gives the total number of events (source+background) detected in an integrated time before any correction. The rate representation gives the counts per second detected in a time bin, where corrections such as dead time, collimator, or background subtraction may have been applied. A source rate (counts s -1) is calculated in the following way:

Rate = (counts - backcounts)/inttime
where counts and backcounts are the source and background counts, respectively (corrected for any collimator response or vignetting). The term inttime is the effective integration time corrected for the effect of dead time. If the background counts are accumulated in an area different from the source region, the background counts should be rescaled to the area of the source region before subtraction.
The column name for the intensity value depends on the type of data
  • COUNTS, number of counts observed in the integration time. The units in the TUNIT should be count and the values stored could be 1,2, or 4 byte.
  • RATE, counts per seconds. The units are count s-1 and the values stored are floating point numbers.
When the intensity measurements are available for a number, n, of different energy bands, then each row in the COUNT or RATE column is an array of n elements. The intensity values are accumulated in an energy interval (or as channels) and this information should be present in the file. Keywords to define energy have already been established by the HEASARC for the spectral and response matrix files (K.A. Arnaud et al. 1992, I.M. George et al. 1992). They are E_MINn and E_MAXn, where E_MINn represents the lower limit of band n and E_MAXn is the upper limit. The default unit for the energy channel is assumed to be keV, otherwise the appropriate unit is provided in the keyword, EUNIT. If the channel number is known, the keywords MINCHANn and MAXCHANn are used, where these define the channels before any rebinning. The number of the different bands is then given in the keyword NUMBAND. If only one energy band is present NUMBAND can be omitted and E_MIN and E_MAX are given. E_MINn and E_MAXn are real numbers, MINCHANn and MAXCHANn are integers. Since the RATE or COUNTS column can contain several intensity values in each row, the extension ENEBAND (described later in this document) can also be used to store those values in order to avoid having an unreasonable number of keywords defining the energy bounderies in the RATE extension.
Together with each COUNTS or RATE column, a column containing an error is required when the total error is not just the square root of the counts (column name ERROR).
To describe the intensity measurement fully, information regarding the background subtraction, dead time correction, and vignetting or collimator correction needs to be stored in the file. If COUNTS are stored then it is assumed that no correction has been applied. If RATE, then flags should be inserted in the header to make known if any of those corrections have been already applied to the value stored in the column. The flags, when appropriate, are inserted as logical keywords, one for each correction.

BACKAPP =                     T     / correction applied
DEADAPP =                     T     / correction applied
VIGNAPP =                     T     / correction applied

In the case of RATE, if the keywords are missing or false, it is assumed that none of the above corrections has been applied to the data. Regardless of whether or not the corrections have been applied to the intensity value stored either in RATE or COUNTS, they can be present in the file either as a column or, if they are constant with time, as keywords. In the next sections the background, dead time and the collimator/vignetting corrections are discussed.

4.7  Background

In the case of binned data, the background information can be stored either as a column or as keywords. In the BACKV column, a background value is stored bin by bin. If an error is necessary, this is defined in a column called BACKE. A similar arrangement can be used for the dead time and the collimator/vignetting correction (see next paragraph). If the column with the intensity value is represented with an array of elements in each row, BACKV and BACKE also need to be represented as arrays.

TTYPEn ='BACKV'                     / background given as column
TFORMn ='nE'
TTYPEn ='BACKE'                     / background error given as column
TFORMn ='nE'

If the background and its error are constant with time, the columns are transformed to keywords with the same name. If n energies are given in the column with the intensity value, then the background column should contain n values or n background keywords should be specified for each energy. In the last case, the keywords are specified as BACKVxxx where xxx is an increasing number corresponding to the band number for which the background value has been calculated. For example, if, in the intensity column, two energy bands are stored, then two background values should be given:

BACKV1 =                   /background counts for the first energy band 
BACKV2 =                   /                          second energy band
TTYPEn ='COUNTS'
TFORMn ='2I'

The background can otherwise be stored in a separate file in either an event list or in a rate file format. The keyword BACKFILE is used to indicate the file containing the background data.

4.8  Dead Time Correction

The value of the dead time correction can be given either as a keyword or as a column in the data table. A single keyword can be used only if a mean value applies to the entire observation. For binned data, storing the dead time in a column is desirable if it varies with time (i.e. if it strongly depends on rapidly changing count rate). Also, if the dead time has a strong dependence on energy, different keywords for all the different intensity measurements stored in the file should be given. If it is time and energy dependent, a column with an array representation in each row should be specified. The deadtime is unitless with a value between 0 and 1. As a keyword:

DEADCn  =       /mean dead time correction for the element n in the array
                 for column INTENSITY. The dead time value does not change 
                 with time

As a column:

TTYPEm = 'DEADC'   /Dead time correction column. The n dimension in TFORMm
TFORMm = 'nE'       represents the number of elements present in a row
                    (i.e. correction at different energy). 
                    The dead time value changes with time.

4.9  Collecting Area

Instruments (both imaging and non-imaging) have a different response depending on the position of the source relative to the instrument pointing, and a vignetting or collimator correction factor may need to be applied. All this information can be defined by the following keywords:

GEOAREA=                              / detector area in cm**2
VIGNET =                              / off-axis vignetting or collimator
                                        correction E-dependent, unitless
DETNAM  =  '       '                  / string, standard name for the detector
NPIXSOU =                             / area in pixels of the source region
NPIXBACK=                             / area in pixels of the background region

  • GEOAREA is the total geometric collecting area of the detector, i.e., the size of the opening through which the photons must pass, assuming the detector is pointing directly at the source. This should not vary during the observation.
  • VIGNET is the projected collecting area of the detector, taking into account that the detector may not be pointed directly at the source (collimator response or vignetting). This value might change during the observation in the case of a scanning satellite or variation in pointing direction, and may be given as a column (TTYPEn =`VIGNET') in the RATE header table. The vignetting correction may also be energy dependent. If the correction does not depend on time, the mean value is stored in a single keyword (VIGNET). However, if it depends on energy, the correction is specified by the keyword VIGNETn where n is the number of channels or energy bands in the intensity column. If the data are given as an event list and the vignetting is changing with time, there are different possible methods to correct the data which require mission-specific software. This software might create binned data corrected for the time dependent vignetting.
  • DETNAM defines the detector used to collect the data. This keyword is different from INSTRUME, where the generic name of the instrument is stored and is most relevant for instruments composed of several selectable detectors (e.g. the EXOSAT Medium Energy (ME) instrument consisted of eight argon and eight xenon detectors which could have been used in almost all possible combinations). A list of the allowed string values for the mission archived or to be archived by HEASARC are defined in George et al. 1993.
  • For imaging instruments only, NPIXSOU and NPIXBACK are, respectively, the total number of pixels in the selected source and background regions. They are included so that counts collected in the background region can be normalized to the source region. To keep a history of the region descriptor selected from the detector, it is recommended to insert this as a COMMENT as shown below.

COMMENT
COMMENT source CIRCLE (200,300,4)
COMMENT background  CIRCLE (500,100,10)

5  Rate Table Formats

The different types of Rate Files differ in the way the time and intensity are presented. The first type, called an Event List, simply tabulates the recorded time for a sequence of events such as X-ray photons detected in a particular instrument. The other types of Rate Files give the measured intensity during a specified integration period, either at equally or unequally spaced time intervals.

5.1  Event List

An Event file has only one required column, called `TIME', which gives the recorded time for each event in the table. In the table, the row n contains single-value parameters for the event n. If the file has data from selected channels, two keywords defining the PHA and/or energy range should be supplied (see section 4.6). A PHA column can optionally be included when the instrument allows data to be resolved in energy. In this case, two quantities are given, the time and the channel, for each event.
The values in the TIME column either give the full time of the event (TIMEZERO missing or 0), or the time as an offset in seconds or days from the zero time specified in the header by the TIMEZERO keyword. If m is the column `TIME', the time for the nth event in the interval defined by TSTART and TSTOP is
t(n)= TIMEZERO + TTYPEm(n)
It is required that TIMEZERO and TTYPE be expressed in the same units. In other words, to apply the above formula the TIMEUNIT and the TUNIT associated with the TIME column should have identical values. If the full time is stored in the column, then
t(n)=TTYPEm(n)
The `TIME' (e.g. TTYPEm(n)) values should (in general) be read as double precision floating point values by any analysis software. However, as described above, any datatype (I1, I2, I4, R4, or R8) may be used as long as the value, after any scaling by the TSCALn and TZEROn keyword values, still preserves the required numerical precision in the time measurement.
An exposure histogram is needed for a photon event list to distinguish the case where the interval between two events was caused by the instrument being turned off. This exposure histogram can be stored in an extension (see GTI and EXPOSURE extension) and the layout is describe in the Ancillary file paragraph. The REFEARTH, REFSUN or REFBSOLS columns, which contain the corrected time at the Earth, Sun, or Solar System Barycenter, respectively, can also be present in the event table. Other attributes of each event, such as X and Y, the projected position of the photon in the sky, the detector DX and DY coordinates or data quality flags may be included as optional columns. If the last columns are inserted, a number of other header keywords are recommended. These are defined in the rationalized FITS event format described by Corcoran & Conroy (1992).
There are two other issues to be considered about event lists: the vignetting correction and the background subtraction. If the vignetting does not depend on energy and does not vary with time, a mean value can be associated with the interval stored in the VIGNET keywords. If the vignetting varies with time, a binned histogram is necessary where in each time bin the average vignetting correction value is stored. The EXPOSURE extension can be used to store this information (see Ancillary Information). The total number of counts detected in the selected background region (NPIXBACK) for all energies can be stored in the keyword BACKV. Time-dependent background can be stored in a different file, the name of which is in the BACKFILE keyword.

5.2  Binned Data

The binned data table requires the columns, RATE, COUNTS (see description above) which contain the intensity of the source detected in the integrated bin, together with the correction or keywords discussed in section 4.6. Various information is required to define the time associated with each bin depending on whether the data are in equispaced bins or not.

5.2.1  Equispaced binned data

If the time intervals are equally spaced, the column containing the intensity value is the only column required. In this case, a TIME column is not necessary because the time of each bin can be calculated from a `start time' and a delta time interval, TIMEDEL, which are specified as header keywords. TIMEDEL should have the same unit specified in the TIMEUNIT keyword (see time definition).

TIMEDEL =                       / integration time in TIMEUNIT

The time at the center of the N-th bin is given then
t(n)=TIMEZERO+TIMEDEL*(N-1)
since TIMEZERO gives the midpoint of the first integrated bin. Using the FITS standard convention, gaps are inserted either as NaN values or, in the case of an integer, using the TNULL value as described in section 3. If the number of gaps in the data is considerably larger or comparable to the number of data points, it may be more economical to use a time column which tags the data points. In this case, the TIMEDEL keywords should still be given to define the integration time of each bin.

5.2.2  Non-equispaced binned data

In the general case, the intensity measurements are not equally spaced in time. A TIME column must be given in the Rate Table, along with a TIMEDEL column, to give the length of the integrated bin, and the column containing the intensity value. The format of the TIME column is the same in Event List Rate Tables and can either be the absolute time of the bin (TIMEZERO header keyword is 0), or just the time offset from TIMEZERO.

5.3  Packet Data

Telemetry data can be arranged in packets (or frames) within which a number of PHA or intensity histograms is stored. In this case, the time information is attached to a single packet rather than to a single bin. To minimize the number of manipulations, a packet of data can be directly stored in a rate file. Two columns are required: TIME, containing the time for each packet, and a second one containing the PHA or intensity histograms in each packet. Multiple histogram columns can be present, depending on the particular on-board computer mode. For example, if an instrument is composed of several selectable detectors and if the mode allows the separation, by detector, of the packet value of the PHA or intensity histogram, each column histogram then contains packets from a single detector. In the header, TIMEDEL, defines the increment in time between two consecutive packets.
Other keywords may be required to decode the packet information. For example, if the packet contains an intensity histogram, keywords must be defined which indicate the increment in time associated with each bin, starting from the time of the packet. We are currently developing these keyword conventions as part of a project to reformat EXOSAT, Einstein SSS, and XTE telemetry data to FITS. These proposed FITS standards will be published in a future issue of Legacy.

6  Ancillary Information

6.1  Barycentric Corrections

The TIMEREF keyword in the RATE extension header specifies which correction has already been applied to the times listed in the TIME column (when applicable). If the value of the keyword is LOCAL, then either a column with the corrected time or a separate FITS binary table extention will be present in the file (EXTNAME='TIMEREF'). If the correction changes slowly for a given time interval, it is a waste of disk space to list the corrected time for every single time measurement in the RATE extension. If a separate extension is used, it is possible to list the residual corrections only when a significant change occurs. More than one correction may be listed, allowing the user to choose easily which correction applies. The column names are the same used in the RATE extension REFEARTH (earth), REFSUN (heliocentric) and REFBSOLS (barycenter of the solar system). Events (or bins) are efficiently matched to their corrections by the inclusion of a TIME column in the TIMEREF extension which identifies the TIME in the RATE extension from which the correction is valid. The TIME values in the TIMEREF extension are a subset of the TIME values in the RATE extension and should correspond to the time when the barycentric correction value changed. For example, to correct the time t(n) (associated with the nth event or bin) in the RATE table, quicker access to the relevant values for REFEARTH or REFSUN is gained by finding the time value near by t(n) in the TIME column of the TIMEREF extension. The correction values can be either ADDED to the time stored in the TIME column in the RATE extention or ADDED after interpolation through a convenient number of points. The content of the table is:

EXTNAME = ' TIMEFRAM'           / barycenter correction table name
TSTART  =                       /start time same unit and system used in
                                 the rate table
TSTOP   =                       /stop time same unit and system used in
                                 the rate table
TIMEZERO=                       /zero time same unit and system used
                                 in the rate table
TTYPE1  = 'TIME    '            / Time after which the value in the
                                  following to column should be applied to 
                                  the data stored in the 'RATE' table
TTYPE2  = 'REFEARTH '           / bary correction at the earth
TFORM2  =
TUNIT2  =
TTYPE3  = 'REFSUN '             / bary correction at the earth
TFORM3  =
TUNIT3  = 
TTYPE4  = 'REFBSOLS '           / bary correction at the solar system
TFORM4  =
TUNIT4  =

It is assumed that the time written in the TIME column has the same unit and is in the same system as defined in TIMESYS and TIMEUNIT in the RATE extention. The time keywords follow the same convention used in the rate table. For this extension the same convention for TFORM, TUNIT, TSCAL, and TZERO explained in the 'Rate Table Format' is applicable. Since the correction values in REFEARTH, REFSUN and REFBSOLS depend on the source position, the keywords RA and DEC should be included in this extension.

6.2  Energy Boundary Information

This extension, ENEBAND, is needed if multiband intensities are stored in the RATE extension to specify the energy or channel range. The extension can contain a minimum of two columns up to four columns. Two columns, MINCHAN and MAXCHAN, contain the value of the lower and upper channels, respectively, in the band. The E_MIN and E_MAX contain the lower bound in energy for the channel in the MINCHAN column and the higher bound of the channel in the MAXCHAN column, respectively. MINCHAN and MAXCHAN are 2-byte integer numbers; E_MIN and E_MAX are 4-byte real. The E_MIN and E_MAX value have the same meaning as described in George et al. (1992). Each row in the table corresponds to an energy or range of channels, the total number of rows in this table should match the keyword NUMBAND in the RATE extension. Table contents:

EXTNAME ='ENEBAND'
TTYPE1  ='MINCHAN'    /lower channel
TFORM1  ='I'
TTYPE2  ='MAXCHAN'    /higher channel
TFORM2  ='I'
TTYPE3  ='E_MIN'      /lower bound of the channel MINCHAN
TFORM3  ='E
TUNIT3  ='keV'
TTYPE4  ='E_MAX'      /higher bound of the channel MAXCHAN
TFORM4  ='E'
TUNIT4  ='keV'

6.3  Good Time Intervals

To calculate a binned histogram (counts versus time) for an events file, time exposure information is required so that the absence of counts can be attributed correctly either to the non-detection of a photon or to the instrument not being on. This information should be inserted in the file only for an event list. If no exposure information is provided, it is assumed that the instrument was on for the full duration between the TSTART and TSTOP keyword values.
A separate FITS binary table extension can be used to list the exposure information. There are two possible formats: either a collection of start and stop times of the good time intervals (EXTNAME='GTI') or a binned time series where the value is the exposure in that bin (EXTNAME= 'EXPOSURE'). For the GTI extension, there are two required columns ('START' and 'STOP').

TSTART  =                      /start time same unit and system used in
                                the rate table
TSTOP   =                      /stop time same unit and system used in
                                the rate table
TIMEZERO=                      /zero time same unit and system used
                                in the rate table
TTYPE1  = 'START   '           / start of good time interval
TTYPE2  = 'STOP    '           / end of good time interval
EXTNAME = 'GTI     '           / name: Good Time Intervals

In this case the exposure associated with a bin calculated from the event list is 100% if the bin is completely inside a good interval, 0% if outside, and exposure X% if falling only partially (X%) inside a GTI. The format of the time values may be specified in the same way as the TIME column in a Rate Table, as either absolute times or as time offsets from a TIMEZERO.

6.4  Exposure

This table is relevant only for event data. Variation in exposure during a GTI can occur due to either a dead time effect and/or variation in the pointing position. For example, in the ROSAT PSPC the "wobble"-performed in order to prevent unwanted shadowing of the X-ray source behind the opaque supporting structures in the PSPC-varies the fraction of exposure in each part of the detector. It also causes a time variation in the vignetting function. The EXPOSURE is required to correct for these effects. The layout can be either a sequence of exposure corrections equispaced in time (only one column required) or a sequence of exposure corrections not equispaced (three columns are required, two describing the time (TIME and TIMEDEL) and one to store the exposure value in that bin (FRACEXP). The FRACEXP column contains the correction factor for which all the single effects (dead time, vignetting) are taken into account. For equally spaced data, the TIMEDEL keyword gives the increment in time between two consecutive bins.

TSTART  =                      /start time same unit and system used in
                                the rate table
TSTOP   =                      /stop time same unit and system used in
                                the rate table
TIMEZERO=                      /zero time same unit and system used
                                in the rate table
TIMEDEL =                     / increment in time 
TTYPE1  = 'FRACEXP   '        / fraction of exposure
EXTNAME = 'EXPOSURE  '        / name

7  Example Files

This section gives examples of Rate files created using this standards. A primary array and a binary extension are required. The extension layout is different depending on the data, e.g. events or binned data (EXTNAME = 'EVENTS' or EXTNAME = 'RATE'), while the primary header is common in both cases.

7.1   The Primary Header


 SIMPLE  =                    T / file does conform to FITS standard
 BITPIX  =                    8 / number of bits per data pixel
 NAXIS   =                    0 / number of data axes
 EXTEND  =                    T / FITS data set may contain extensions
 CONTENT = 'LIGHT CURVE'        / file contains rate data
 ORIGIN  = 'HEASARC/GSFC'       / orin of the file
 DATE    = '04/01/93'           / file creation date (DD/MM/YY)
 TELESCOP= '        '           / Telescope (mission) name
 INSTRUME= '        '           / instrument used for observation
 OBJECT  = '        '           / common object name
 RA      =          1.49221E+01 / source RA in degrees
 DEC     =          -3.0531E+01 / source declination in degrees
 EQUINOX =           1.9500E+03 / equinox of celestial coord. system
 RADECSYS= 'FK4     '           / FK4 coordinate system used
 DATE-OBS= '28/05/69'           / date of first obsvn (DD/MM/YY)
 TIME-OBS= '10:41:03'           / time of first obsvn (HH:MM:SS.n)
 DATE-END= '18/06/79'           / date of last obsrn (DD/MM/YY)
 TIME-END= '09:35:08'           / time of last obsvn (HH:MM:SS.n)
 TIMVERS = 'OGIP/93-003'        / OGIP memo number for file format
 AUTHOR  =  '      '            / Program name that produced this file
 END

7.2   Data Extension

RATE: This example header describes equispaced binned data taken in one energy band with a time resolution written in TIMEDEL. The column TIME and TIMEDEL is required for non-equally spaced data.

 XTENSION= 'BINTABLE'           / binary table extension
 BITPIX  =                    8 / 8-bit bytes
 NAXIS   =                    2 / 2-dimensional binary table
 NAXIS1  =                    8 / width of table in bytes
 NAXIS2  =               146675 / number of rows in table
 PCOUNT  =                    0 / size of special data area
 GCOUNT  =                    1 / one data group (required keyword)
 TFIELDS =                    2 / number of fields in each row
 EXTNAME = 'RATE    '           / name of this binary table extension
 TIMVERS = 'OGIP/93-003'        / OGIP memo number for file format
 MJDREF  =                      / MJD for reference file
 TIMESYS = 'MJD     '           / The time system is MJD
 TIMEUNIT= 'd       '           / unit for TSTARTI/F and TSTOPI/F
 CLOCKCOR= 'YES'                / if time corrected to UT
 TIMEREF = 'LOCAL   '           / barycentric correction applied to times
 TASSIGN = 'SATELLITE'          / where time is assigned 
 TSTART  =                      / observation start time 
 TSTOP   =                      / observationstop time 
 TIMEZERO=                      / zerotime to calculate t(n) event or bin 
 TIMEDEL =                      / integration time 
 TIERRELA=                      / relative time error
 TIERABSO=                      / absolute time error
 ONTIME  =                      / time on source
 TTYPE2  = 'RATE'               / data from detector channel
 TFORM2  = '1E      '           / data format of the field: 4-byte REAL
 TUNIT2  = 'count/s'            / physical unit of field
 TTYPE3  = 'ERROR   '           / error in intensity
 TFORM3  = '1E      '           / data format of the field: 4-byte REAL
 TUNIT3  = 'count/s'            / physical unit of field
 BACKAPP =                    T / background is subtracted
 DEADAPP =                    T / deadtime applied 
 VIGNAPP =                    T / vignetting or collimator applied
 E_MIN   =                      / low energy for channel (keV)
 E_MAX   =                      / high energy for channel (keV)
 EUNIT   = 'keV     '           / energy unit
 TELESCOP= '        '           / Telescope (mission) name
 INSTRUME= '        '           / Instrument used
 OBJECT  = '        '           / name of observed object
 RA      =          1.49221E+01 / R.A. in degrees
 DEC     =          -3.0531E+01 / Declination in degrees
 EQUINOX =           1.9500E+03 / equinox of celestial coord. system
 RADECSYS= 'FK4     '           / FK4 coordinate system used
 DATE-OBS= '28/05/90'           / UT date of first obs data set (DD/MM/YY)
 TIME-OBS= '07:33:22'           / UT time of first obs data set (HH:MM:SS)
 DATE-END= '28/05/90'           / UT date of last obs  data set (DD/MM/YY)
 TIME-END= '12:40:58'           / UT time of last obs data set (HH:MM:SS.n)
 ORIGIN  = 'HEASARC/GSFC'       / file created at Goddard HEASARC
 DATE    = '04/01/93'           / file creation date (DD/MM/YY)
 END 

EVENTS: This example header describes event data. The GTI extension is required in this case. Other attributes for each event may be included as optional columns.

 XTENSION= 'BINTABLE'           / binary table extension
 BITPIX  =                    8 / 8-bit bytes
 NAXIS   =                    2 / 2-dimensional binary table
 NAXIS1  =                    8 / width of table in bytes
 NAXIS2  =               146675 / number of rows in table
 PCOUNT  =                    0 / size of special data area
 GCOUNT  =                    1 / one data group (required keyword)
 TFIELDS =                    1 / number of fields in each row
 EXTNAME = 'EVENTS  '           / name of this binary table extension
 TIMVERS = 'OGIP/93-003'        / OGIP memo number for file format
 MJDREF  =                      / MJD for reference file
 TIMESYS = 'MJD     '           / The time system is MJD
 TIMEUNIT= 'd       '           / unit for TSTARTI/F and TSTOPI/F
 CLOCKCOR= 'YES'                / if time corrected to UT
 TIMEREF = 'LOCAL   '           / barycentric correction applied to times
 TASSIGN = 'SATELLITE'          / where time is assigned 
 TSTART  =                      / observation start time 
 TSTOP   =                      / observationstop time 
 TIMEZERO=                      / zerotime to calculate t(n) event or bin 
 TIERRELA=                      / relative time error
 TIERABSO=                      / absolute time error
 ONTIME  =                      / time on source
 TTYPE1  = 'TIME    '           / time of measurement
 TFORM1  = '1D      '           / data format of the field: DOUBLE PRECISION
 TUNIT1  = 'd       '           / physical unit of field
 NPIXSOU =                      / number of pixels within the source region
 NPIXBACK=                      / number of pixels within the background region
 BACKV   =                      / total background counts
 VIGNET  =                      / mean vignetting correction
 E_MIN   =                      / low energy for channel (keV)
 E_MAX   =                      / high energy for channel (keV)
 EUNIT   = 'keV     '           / energy unit
 TELESCOP= '        '           / Telescope (mission) name
 INSTRUME= '        '           / Instrument used
 OBJECT  = '        '           / name of observed object
 RA      =          1.49221E+01 / R.A. in degrees
 DEC     =          -3.0531E+01 / Declination in degrees
 EQUINOX =           1.9500E+03 / equinox of celestial coord. system
 RADECSYS= 'FK4     '           / FK4 coordinate system used
 DATE-OBS= '28/05/90'           / UT date of first obs data set (DD/MM/YY)
 TIME-OBS= '07:33:22'           / UT time of first obs data set (HH:MM:SS)
 DATE-END= '28/05/90'           / UT date of last obs  data set (DD/MM/YY)
 TIME-END= '12:40:58'           / UT time of last obs data set (HH:MM:SS.n)
 ORIGIN  = 'HEASARC/GSFC'       / file created at Goddard HEASARC
 DATE    = '04/01/93'           / file creation date (DD/MM/YY)
 COMMENT 
 COMMENT source CIRCLE (200,300,4)
 COMMENT background  CIRCLE (500,100,10)
 END

REFERENCES

Arnaud, K. A., George, I.M., Tennant, A. F. 1992. Legacy, 2, 65, (OGIP/92-007).
Corcoran, M., & Conroy, M., 1992, "RDF User's Guide"
George, I.M., and Angelini, L., 1993, OGIP/93-001.
George, I.M., Arnaud, K. A., Pence, W., Ruamsuwan, L, 1992. Legacy, 2, 51, (CAL/GEN/91-002).
George, I.M., Zellar, R., Pence W. 1993, in preparation (CAL/GEN/92-011)
NASA/OSSA Office of Standards and Technology (NOST) 100-1.0, 'Definition of the Flexible Image Transport System (FITS)', Nov 16 1992
Pence, W 1992 Legacy, 1 15.


Acknowledgements
We thank the numerous people in the OGIP who have contributed ideas and suggestions. In particular we thank Nick White, Laura Whitlock for their critical reading of the various drafts, and Charles Day for carefully reading the manuscript.

USEFUL LINKS TO OTHER HTML PAGES

Other OFWG FITS Format Documentation



File translated from TEX by TTH, version 3.85.
On 4 Sep 2014, 16:07.