NOTICE:This Legacy journal article was published in Volume 6, August 1995, 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 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