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
HEASARC Home |
Observatories |
Archive |
Calibration |
Software |
Tools |
Students/Teachers/Public
Last modified: Monday, 19-Jun-2006 11:40:52 EDT
|