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