The Recommended Columns and Keywords
for a FITS Event List

W. Pence and I. George
HEASARC

I. Introduction

The purpose of this article is to concisely describe the recommended set of columns and keywords that should be included in a FITS Event List. Each mission or dataset requires a slightly different set of keywords, so this article only describes the most frequently used elements that are common to most Event Lists. Users who are designing the FITS format for a new event data set should contact the HEASARC for specific recommendations. Other related FITS information can be found on-line on the WWW.

II. What is an Event List?

Within the context of the HEASARC FITS files, an Event List is defined to be a FITS TABLE or BINTABLE extension containing a list of parameters associated with events recorded by an instrument. Each row of the table contains the attributes of a single event, and each event attribute or parameter is given in a separate column. A typical Event List might list the TIME and the recorded X and Y position of each event, and so would have three columns and as many rows as there are events. Most Event Lists have a TIME column, but this is not required and one could have an Event List which only contains spatial or spectral information about each event.

III. Recommended Event Table Columns

The number of required columns in an event list depends on the particular data set. Some missions only record the time of each event while others may record many other event parameters such as the position of the event on the detector or the sky, or the energy of the event. The following table lists the columns that are commonly used in various high energy missions.

Name	    Units      	  Description 

TIME      `s' or `d'  The time associated with the event 
RAWX      `pixel'     Raw telemetry X position of the event 
RAWY      `pixel'     Raw telemetry Y position of the event 
DETX      `pixel'     Linearized X position of the event on the detector
DETY      `pixel'     Linearized Y position of the event on the detector
X         `pixel'     Projected X position of the event on the sky 
Y         `pixel'     Projected Y position of the event on the sky 
PHA       `chan'      Pulse height analyzer' energy channel 
PI        `chan'      Energy channel after correction for detector variations 
RISE_TIME `    `      Electronic rise time of the event 
SPREAD    `    `      Spatial `spreading' of the event 
RTI       `    `      Rise time invariant of the event 
GRADE     `    `      Specifies how the event is split between pixels
CCDID     `    `      Number of the CCD on which the event occurred 
EVENT     `    `      "Event word": a bit string of encoded event parameters 
STATUS    `    `      Status flag

One is free to add as many other mission-specific columns to the table as is necessary to record all the parameters associated with each event.

The name of each column is specified in the FITS header by the TTYPEn keyword and the units are specified by the TUNITn keyword. For many columns it is also necessary to specify the allowed range of values contained in the column. For example, if the values in a particular column can range from 0 to 255, inclusive, then this should be specified with the keywords:

TLMINn  =                    0 / minimum allowed value in column n 
TLMAXn  =                  255 / maximum allowed value in column n

where n is an integer defining the number of the column in the table. This information is often needed to determine the dimensions of the spectrum or image that can be generated by calculating a 1-D or 2-D histogram from the columns of data in the table.

In some cases it may also be desired to specify the actual minimum and maximum value recorded in the column (as opposed to the legal range given by TLMIN and TLMAX). This can be specified with the following keywords:

TDMINn  =                   13 / minimum value in column n 
TDMAXn  =                  201 / maximum value in column n

IV. Recommended FITS Header Keywords

The FITS header of each Event List should contain enough keywords to fully document and describe the contents of the list. The set of recommended keywords depends of course on the particular mission, but in general the keywords can be subdivided into the 4 different categories described in the following sections. Not all of these keywords are appropriate for every mission, and the keyword values shown here are just for illustration.

A. General Descriptive Keywords

The following keywords provide general information about the FITS file, the instrumental configuration used during the observation, and the observed object.

ORIGIN  = `HEASARC/GSFC/NASA'  / institution that created this file 
CREATOR = `program v1.2.3'     / program and version that created this file
EXTNAME = `EVENTS  `           / this is an event table 
HDUCLASS= `OGIP    `           / this file conforms to OGIP/HEASARC conventions 
HDUCLAS1= `EVENTS  `           / this is an Event List

TELESCOP= `EINSTEIN'           / telescope or mission name 
INSTRUME= `FPCS    `           / instrument name 
DETNAM  = `PbL     `           / detector name 
FILTER  = `AL      `           / filter name 
OBS_MODE= `POINTING'           / POINTING, SLEW, or SCAN, etc. 
DATAMODE= `FAINT   `           / on-board data processing mode 
OBJECT  = `name    `           / name of the observed object 
OBSERVER= `Smith, J. G.'       / name of observer or P.I.

B. Time Keywords

The following keywords provide approximate timing information in a format that is easy for humans to understand. Generally speaking, these keywords are not used for precise timing calculations.

DATE    = `31/12/94'           / date that FITS file was created 
DATE-OBS= `28/02/88'           / start date of the observation (dd/mm/yy)
TIME-OBS= `15:45:57'           / start time of the observation (hh:mm:ss)
DATE-END= `28/02/89'           / end date of the observation 
TIME-END= `17:12:55'           / end time of the observation

The following keywords provide precise information on the times of the events in the list. Refer to the previous Legacy article ("The Proposed Timing FITS File Format", Legacy 3, 32) for a more complete description of these and other timing keywords.

TSTART  =            325300.00 / mission time of the start of the observation 
TSTOP   =            326100.00 / mission time of the end of the observation
MJDREF  =              49353.0 / MJD corresponding to SC clock start (1994.0) 
TIMEUNIT= `s       `           / units for the time related keywords
TIMESYS = `UTC     `           / type of time system that is used 
TIMEREF = `LOCAL   `           / reference frame used for times 
TASSIGN = `SATELLITE'          / Location where time assignment performed
CLOCKAPP=                    F / has clock correction been applied? 
TELAPSE =               800.00 / total elapsed time of the observation
ONTIME  =               650.00 / active integration time 
LIVETIME=               600.00 / ONTIME corrected for deadtime effects
EXPOSURE=               575.00 / total time used to calc the correct countrate 
DEADC   =                0.923 / deadtime factor = LIVETIME/ONTIME 
TIMEDEL =                  1.0 / delta time or time resolution of events

C. Spatial Position Keywords

The following keywords provide information about the position of the object, the telescope pointing, or the spacecraft axes during the observation. Not all of these keywords are relevant for all missions.

RA_OBJ  =               340.00 / R.A. of the object (degrees) 
DEC_OBJ =               -57.55 / declination of the object (degrees)
RA_PNT  =               341.00 / R.A. of the pointing direction (degrees)
DEC_PNT =               -57.05 / declination of the pointing direction(degrees) 
RA_NOM  =               340.00 / nominal proposed R.A. of the pointing
DEC_NOM =               -57.55 / nominal proposed dec of the pointing
RA_SCX  =                 0.00 / R.A. of the spacecraft X-axis (degrees)
DEC_SCX =                 0.00 / declination of the spacecraft X-axis (degrees) 
RA_SCY  =                90.00 / R.A. of the spacecraft Y-axis (degrees)
DEC_SCY =                 0.00 / declination of the spacecraft Y-axis (degrees) 
RA_SCZ  =                 0.00 / R.A. of the spacecraft Z-axis (degrees)
DEC_SCZ =                90.00 / declination of the spacecraft Z-axis (degrees) 
EQUINOX =               2000.0 / coordinate epoch 
RADECSYS= `FK5     `           / frame of reference of coordinates 
MJD-OBS =              49733.0 / MJD of observation (not for precise timing)

The following keywords are used to the specify the coordinate of each event as projected onto the sky. The `X' and `Y' columns (described above) give the pixel coordinate of each event within a 2-dimensional sky projected image. The actual sky coordinate (e.g., R.A. and Dec.) associated with each image pixel can then be calculated from the following set of keywords which are analogous to the set of celestial coordinate keywords that are recommended for FITS 2-dimensional images (see the document ftp://fits.cv.nrao.edu/fits/documents/wcs/wcs.all.ps for more details about FITS celestial coordinate systems). In this example, the X and Y pixel values are contained in columns 3 and 4 of the table:

TTYPE3  = `X       `           / column name 
TTYPE4  = `Y       `           / column name 
TCTYP3  = `RA---TAN'           / axis type for column 3 
TCTYP4  = `DEC--TAN'           / axis type for column 4 
TCRPX3  =                128.0 / reference pixel for column 3 
TCRPX4  =                128.0 / reference pixel for column 4 
TCRVL3  =                120.0 / reference value for column 3 (degrees)
TCRVL4  =                -30.0 / reference value for column 4 (degrees)
TCDLT3  =                -0.01 / pixel increment for column 3 (degrees)
TCDLT4  =                 0.01 / pixel increment for column 4 (degrees)
TCROT4  =                  0.0 / axis rotation

In this example the 2-dimension image is a tangent plane projection of the sky with the X axis (column 3) representing Right Ascension and the Y axis (column 4) representing Declination (as specified by the TCTYPn keywords). Pixel number 128 is the reference pixel (given by the TCRPXn keywords) and the sky coordinate at this pixel is 120.0 degrees R.A. and -30.0 degrees declination (given by the TCRVLn keywords). At the location of the reference pixel (which should also be the tangent point of the map projection) each pixel is 0.01 by 0.01 degrees in size. Note that the TCDLT3 keyword value is negative because the R.A. value decreases with increasing pixel number (towards the west).

To clarify a common source of confusion, the first pixel in a FITS image is defined to range from 0.5 to 1.5, with the center of the pixel at coordinate 1.0. This differs from the usual convention for image display devices where the pixel is considered to range from 0.0 to 1.0, with the center of the pixel at coordinate 0.5. In this example the reference pixel location is given as 128.0 which means that it is located in the center of the 128th pixel in the image. If instead the reference pixel value was given as 127.5, this would indicate that the reference pixel location was on the boundary between the 127th and 128th pixels.

D. Energy Keywords

The following keywords define the range of energy or detector channels associated with the events in the Event List. These keywords are more frequently used in `derived' files (such as an image, lightcurve, or spectrum), but they may sometimes be relevant for Event Lists as well.

CHANMIN =                    0 / lower channel boundary 
CHANMAX =                  511 / upper channel boundary 
E_MIN   =                  0.5 / lower energy boundary 
E_MAX   =                  8.0 / upper energy boundary 
EUNIT   = `keV     `           / units for E_MIN and E_MAX

V. Summary

This article describes only the most commonly used columns and keywords that should appear in Event Lists. Most Event Lists will have a host of other mission-specific parameters. Please contact the HEASARC if you have any questions or would like suggestions on the format of any particular event list files.

Proceed to the next article

Return to the previous article

Select another article