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

The Proposed Timing FITS File Format for High Energy Astrophysics Data

    Version: March 1993	                          OGIP Memo OGIP/93-003

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 may be equispaced or unequally spaced.

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 these 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 permitted values include: 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

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 savings 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

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

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.

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, is still possible to perform some timing analyses on the data set. The disadvantage of the latter approch, 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 a description of the proposed scheme for time definition. The related corrections to be applied to the time are discussed in section 4.4. These time parameters may be given as a single keyword or may be specified using two keywords to express the integer and the fractional parts of the time value separately. The option of using one keyword or a pair of keywords to describe time provides more precision when it is required. Any software which accesses those files should first search for the paired keywords and then use only the single valued times if the paired keywords are not found.

Keywords:

Double:

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

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

TIMESYS =                        / the system used to define the 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. For exapmple, 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 document (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 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 keyword 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 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 = `REFEARTH' or TTYPEn='REFSUN' or TTYPEn='REFBSOLS'

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 has 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. barycentric 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 expressed as rate 
TIERABSO=          0.1    / timing  precision  (seconds)

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 count 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 (count s^-1) is calculated in the following way:

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 second. The units are count/s 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 is stored, then flags should be inserted in the header to make known which, if any, of these 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

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 by 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'

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

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 a 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.

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 missions 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 DETX and DETY 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 et al. (1993).

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 and 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 then


t(n)=TIMEZERO+TIMEDEL*(N-1)

5.2.2 Non-equispaced binned data

In the general case, intensity measurements are not equally spaced in time. A TIME column, a TIMEDEL column (to give the length of the integrated bin) and a column containing the intensity value must be given in the Rate Table in this case. The format of the TIME column is the same as 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    `            /Subset of the TIME column value in the
				RATE extention 
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  =

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 and a maximum of 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 values 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'

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').

EXTNAME = `GTI     `           / name: Good Time Intervals 
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

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.

EXTNAME = `EXPOSURE  `        / 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 
TIMEDEL =                     / increment in time 
TTYPE1  = `FRACEXP   `        / fraction of exposure

This section gives examples of Rate Files created using this standard. 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'       / origin 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)
 TIMVERSN = `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
 TIMVERSN = `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, TIMEZERO
 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
 TTYPE1  = `RATE'               / data from detector channel
 TFORM1  = `1E      `           / data format of the field: 4-byte REAL
 TUNIT1  = `count /s'           / physical unit of field
 TTYPE2  = `ERROR   `           / error in intensity
 TFORM2  = `1E      `           / data format of the field: 4-byte REAL
 TUNIT2  = `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

 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
 TIMVERSN = `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   =                      / observation stop 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

Arnaud, K. A., George, I.M., Tennant, A. F. 1992, Legacy, 2, 65, (OGIP/92-007).
Corcoran, M., et al. 1993., in preparation
George, I.M., and Angelini, L., 1993, in preparation (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)', in press.
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 and Laura Whitlock for their critical reading the various drafts, and Charles Day for carefully reading the manuscript.

Proceed to the next article

Return to the previous article

Select another article