OGIP Memo OGIP/94-003
GUIDELINES FOR DEFINING FITS FORMATS FOR
EVENT LISTS
Code 668,
NASA/GSFC,
Greenbelt,
MD20771.
Version: 1994 Dec 01
This memo defines an Event List, and gives guidelines for the defining
suitable FITS file formats. A list of column names and their definitions
used previously within Event Lists is also given.
Intended audience: primarily instrument hardware & software teams
|
Release |
Sections Changed |
Brief Notes |
Date |
|
|
|
|
|
1994 Jul 13 |
|
First (internal) Draft |
1994 Dec 01 |
All |
Made compatible with LaTeX2HTML software |
|
|
|
INTRODUCTION
For many applications, an Event List is the starting point for scientific
data reduction & analysis. The events are sorted & filtered based on a
wide variety of criteria until a list of acceptable events is obtained.
Detailed scientific analysis is then performed on the acceptable events,
often (but not always) by first converting the list into another class of
filetype (eg by constructing an Image, Light curve, Spectrum from the
Event List). But what exactly is an "Event List" ?
Definition of an Event List
In the context of OGIP FITS files, an Event List is defined to be a FITS
extension containing a list of parameters/flags associated with events
recorded by an instrument (eg the time-tag, position on the detector,
pulse height), and/or parameters/flags derived from these quantities
(e.g., barycentric time, linearized detector coordinates, celestial
coordinates, photon energy ... etc of the events) -- both the original
and derived quantities will be referred to as "attributes". The list can
contain the results of events arising from the cosmos (including cosmic
ray events), and/or "false" background events recorded as a result of
instrumental/electronic noise. For an OGIP-standard Event List, one
row contains attributes of a single event; a related file format which
contains multiple events per row may be advantageous for specific missions
and will be defined elsewhere.
An Event List can also be considered a Light Curve, or (binned) time series
histogram, with time bins of size equal to the accuracy of the time stamp.
However, when viewed as a binned light curve, the Event List has the
following properties that binned light curves usually do not have and that,
therefore, distinguish the event list as a special kind of binned light
curve:
- The event list is a sparse histogram
(i.e., only filled bins are present).
- Each bin (by definition) has a population of one event.
- Each bin (as defined by the value of the time stamp) may be
present more than once, thus indicating populations greater than
one.
The detailed format of a given Event Lists is considered
instrument-specific, and the order in which the events are listed
application-specific.
MULTI-MISSION COLUMN NAMES
The following column names have been approved by the
OGIP FITS Working Group (OFWG)
for use within Event Lists,
and are considered to have applications
for multiple missions.
Spatial Information
RAWX
giving the X-coordinate of the event in
raw detector coordinates (prior to linearization).
Units: Detector-specific
Format: Detector-specific
Used by: ASCA, Einstein IPC
Notes:
- Einstein IPC has units of
'pixels'
which is not an OFWG-recognized unit
RAWY
giving the Y-coordinate of the event in
raw detector coordinates (prior to linearization).
Units: Detector-specific
Format: Detector-specific
Used by: ASCA, Einstein IPC
Notes:
- Einstein IPC has units of
'pixels'
which is not an OFWG-recognized unit
DETX
giving the X-coordinate of the event in
linearized detector coordinates.
Units: Detector-specific
Format: Detector-specific
Used by: ROSAT (RDF 1.4), ASCA, SAS-2, Einstein IPC
Notes:
- Einstein IPC has units of
'pixels'
which is not an OFWG-recognized unit
DETY
giving the Y-coordinate of the event in
linearized detector coordinates.
Units: Detector-specific
Format: Detector-specific
Used by: ROSAT (RDF 1.4), ASCA, SAS-2, Einstein IPC
Notes:
- Einstein IPC has units of
'pixels'
which is not an OFWG-recognized unit
Derived
X
giving the projected X position of photon on sky.
Units: pixels (unitless)
Format: integer
Used by: ROSAT (RDF 1.4), ASCA, SAS-2, Einstein (HRI, IPC)
Notes:
- Einstein IPC has units of
'pixels'
which is not an OFWG-recognized unit
Y
giving the projected Y position of photon on sky.
Units: pixels (unitless)
Format: integer
Used by: ROSAT (RDF 1.4), ASCA, SAS-2, Einstein (HRI, IPC)
Notes:
- Einstein IPC has units of
'pixels'
which is not an OFWG-recognized unit
RA
giving the (derived) Right Ascension of the photon.
Units: angular, preferably deg
Format: real
Used by: SAS-2
Notes:
- The coordinate system and equinox must be specified by
accompanying
RADECSYS and EQUINOX keywords.
DEC
giving the (derived) Declination of the photon.
Units: angular, preferably deg
Format: real
Used by: SAS-2
Notes:
- The coordinate system and equinox must be specified by
accompanying
RADECSYS and EQUINOX keywords.
L
giving the (derived) Galactic Longitude of the photon.
Units: angular, preferably deg
Format: real
Used by: SAS-2
B
giving the (derived) Galactic Longitude of the photon.
Units: angular, preferably deg
Format: real
Used by: SAS-2
Spectral Information
PHA
giving the Pulse Height Analyzer bin (channel) number.
Units: None in principle, but chan allowed.
Format: integer
Used by: ROSAT (RDF 1.4), ASCA, Einstein (HRI, IPC)
Notes:
- ROSAT (RDF 1.4) has units of
'CHAN'
which is not an OFWG-recognized unit
- Einstein IPC has units of
'bin'
which is not an OFWG-recognized unit
PI
giving the Pulse Invariant bin (channel) number.
Units: None in principle, but chan allowed.
Format: integer
Used by: ROSAT (RDF 1.4), ASCA, Einstein (HRI, IPC)
Notes:
- ROSAT (RDF 1.4) has units of
'CHAN'
which is not an OFWG-recognized unit
- Einstein IPC has units of
'bin'
which is not an OFWG-recognized unit
ENERGY
giving the (derived) energy of the event.
Units: Energy, preferably keV or MeV
Format: real
Used by: SAS-2
Notes:
- Due to a lack of precision, SAS-2 stores the values as integers
WAVELENGTH
giving the (derived) wavelength of the event.
Units: wavelength, preferably m or angstrom
Format: real
Used by: Einstein (FPCS)
Notes:
- Einstein FPCS has units of
'Angstroms'
which is not an OFWG-recognized unit
Temporal Information
TIME
giving the time of the event.
Units: Temporal, preferably seconds (s ).
Format: real/double precision
Used by: ROSAT (RDF 1.4), ASCA, BBXRT, SAS-2, Einstein (FPCS, HRI, IPC)
Notes:
- BBXRT has units of
'MET day'
which is not an OFWG-recognized unit
- ROSAT (RDF 1.4) has units of
'S'
which is the OFWG-recognized unit for Siemens, and hence incorrect
Data Quality Flags
STATUS
giving the coded data quality flag of the event.
Units: None.
Format: Detector Specific
Used by: ROSAT (RDF 1.4), Einstein (IPC)
Notes:
- ROSAT (RDF 1.4) has units of
'CODED' which are not
recognized by the OFWG
Spacecraft Housekeeping Information
X_COORD
giving the 'X-axis celestial coordinate' of the event.
Units: Presumed angular, preferably deg
Format: real
Used by: SAS-2
Notes:
- SAS-2 has units of
km , which are OFWG-recognized, but
incorrect in this context ?
Y_COORD
giving the 'Y-axis celestial coordinate' of the event.
Units: Presumed angular, preferably deg
Format: real
Used by: SAS-2
Notes:
- SAS-2 has units of
km , which are OFWG-recognized, but
incorrect in this context ?
Z_COORD
giving the 'Z-axis celestial coordinate' of the event.
Units: Presumed angular, preferably deg
Format: real
Used by: SAS-2
Notes:
- SAS-2 has units of
km , which are OFWG-recognized, but
incorrect in this context ?
LAT_GEO
giving the (projected) geographic lattitude of the spacecraft at the
time of the event.
Units: angular (deg )
Format: real
Used by: SAS-2
LON_GEO
giving the (projected) geographic longitude of the spacecraft at the
time of the event.
Units: angular (deg )
Format: real
Used by: SAS-2
RAD_GEO
giving the altitude of the spacecraft at the
time of the event.
Units: linear distance, preferably m
Format: real
Used by: SAS-2
XAXISRA
giving the Right Ascension of the X-axis of the spacecraft at the
time of the event.
Units: angular, preferably deg
Format: real
Used by: SAS-2
Notes:
- The coordinate system and equinox must be specified by
accompanying
RADECSYS and EQUINOX keywords.
XAXISDEC
giving the Declination of the X-axis of the spacecraft at the
time of the event.
Units: angular, preferably deg
Format: real
Used by: SAS-2
Notes:
- The coordinate system and equinox must be specified by
accompanying
RADECSYS and EQUINOX keywords.
ZAXISRA
giving the Right Ascension of the Z-axis of the spacecraft at the
time of the event.
Units: angular, preferably deg
Format: real
Used by: SAS-2
Notes:
- The coordinate system and equinox must be specified by
accompanying
RADECSYS and EQUINOX keywords.
ZAXISDEC
giving the Declination of the Z-axis of the spacecraft at the
time of the event.
Units: angular, preferably deg
Format: real
Used by: SAS-2
Notes:
- The coordinate system and equinox must be specified by
accompanying
RADECSYS and EQUINOX keywords.
SPINRATE
giving the instanteous rate of spin of
the spacecraft at the
time of the event.
Units: angular per unit time, preferably deg/s
Format: real
Used by: SAS-2
Notes:
- SAS-2 has units of
rad/sec which is not an OFWG-recognized unit
string
INSTRUMENT-SPECIFIC COLUMN NAMES
The use of following column names is likely to be limited to a
specific instrument, though it is feasible that they could be
used by two or more
similar instruments (on different satellites).
ASCA
RISE_TIME
giving the
electronic rise time of event.
Units: None (unitless)
Format: Integer
SPREAD
giving the "spatial spreading" of the event.
Units: None (unitless)
Format: Integer
RTI
giving the
Rise time invariant of the event.
Units: None (unitless)
Format: Integer
ASCA SIS
GRADE
giving a flag indicating how
the event was split between detector pixels.
Units: Unitless.
Format: Integer
CCDID
giving the number of the CCD in which the event was detected.
Units: Unitless.
Format: Integer
PHAS
giving a array of PHA information (in SIS FAINT mode only).
Units: Unknown
Format: Unknown
BBXRT
DETECTOR
giving an integer code for the BBXRT telescope and pixel in which the
event was detected.
Units: None (unitless)
Format: Integer
PHAS
giving the Pulse Height Analyser bin (channel) in which the event was
recorded.
Units: None
Format: Integer
Notes:
- NOT RECOMMENDED
This information should be stored in columns named as outlined in
Section 2.2.
- The ASCA SIS
uses a column with the same name to store subtly different type
of information (Section 3.1.2)
LED
giving the value of the LED flag
(no further information).
Units: None
Format: Byte
GUARD
giving the value of the GUARD flag
(no further information).
Units: None
Format: Byte
VLE
giving the value of the VLE flag.
(no further information).
Units: None
Format: Byte
PTP
giving the value of the PTP flag
(no further information).
Units: None
Format: Byte
PPU
giving the value of the PPU flag
(no further information).
Units: None
Format: Byte
Einstein
ANGLE
giving the Bragg Angle of the crystal at the time of the event.
Units: angular, preferably rad
Format: Real
DET-POS
giving the Detector Position at the time of the event.
Units: detector specific
Format: Real
Notes:
- Einstein FPCS uses units of linear distance (
cm )
A
giving the 'A Pulse Height' of the event
(no further information)
Units: None
Format: Integer
B
giving the 'B Pulse Height' of the event
(no further information)
Units: None
Format: Integer
Notes:
- NOT RECOMEENDED
The name of this column clashes
with a mission-independent keyword listed in
Section 2.1.2
WIRE-NUM
giving the 'Wire Number' of the event
(no further information)
Units: None
Format: Integer
DQF
giving the coded data quality flag of the event.
Units: None.
Format: Detector Specific
Notes:
- NOT RECOMMENDED
This information should be stored in columns named as outlined in
Section 2.4.
SAS-2
NEVENT
giving the 'event number from Encyclopedia' !
(no further information).
Units: None (unitless)
Format: integer
FLAG
giving an encoded bit-flag value
(no further information).
Units: None (unitless)
Format: integer
DEL_TIME
giving the time of the previous event
(no further information).
Units: temporal, 's' used
Format: real
ENDEVENT
giving the time of the event
(no further information).
Units: temporal, 'ms' used
Format: integer
FOVCLASS
giving the 'Field-of-view' class flag in the range 0-5
(no further information).
Units: None (unitless)
Format: integer
SPKDAT
giving an array of 12 integers associated with the 'Spark chamber data'
of the event
(no further information).
Units: None (unitless)
Format: integer array
XTE
(NOTE: The definitions in this section should be considered provisional.)
EventWord
giving bit-encoded information regarding the event
(no further information).
Units: None (unitless)
Format: Integer
LiveTime
giving bit-encoded information regarding the livetime
(no further information).
Units: None (unitless)
Format: Integer
XTE HEXTE
(NOTE: The definitions in this section should be considered provisional.)
ClstrPos
giving the position of the HEXTE cluster
(no further information).
Units: Unknown
Format: Unknown
The following column names were discovered in Event Lists, and are awaiting
classification and/or approval.
SAS-2
TTYPE20 = 'ZENITH ' / Zenith angle
TFORM20 = '1E ' / data format of the field: 4-byte REAL
TUNIT20 = 'deg ' / degrees
TTYPE23 = 'AXISANG ' / Axis angle
TFORM23 = '1E ' / data format of the field: 4-byte REAL
TUNIT23 = 'deg ' / physical unit of field
EXAMPLE HEADERS
GIS
XTENSION= 'BINTABLE' / binary table extension
... etc ...
TFIELDS = 12 / number of fields in each row
TTYPE1 = 'TIME ' / Photon arrival time
TFORM1 = '1D ' / data format of the field: DOUBLE PRECISION
TUNIT1 = 's ' / physical unit of field
TTYPE2 = 'X ' / projected X position of photon on sky
TFORM2 = '1I ' / data format of the field: 2-byte INTEGER
TUNIT2 = 'pixel ' / physical unit of field
TTYPE3 = 'Y ' / projected Y position of photon on sky
TFORM3 = '1I ' / data format of the field: 2-byte INTEGER
TUNIT3 = 'pixel ' / physical unit of field
TTYPE4 = 'PHA ' / Pulse Height Analyzer bin number
TFORM4 = '1I ' / data format of the field: 2-byte INTEGER
TUNIT4 = 'channel ' / physical unit of field
TTYPE5 = 'PI ' / Pulse Invariant bin number
TFORM5 = '1I ' / data format of the field: 2-byte INTEGER
TUNIT5 = 'channel ' / physical unit of field
TTYPE6 = 'RISE_TIME' / Electronic rise time of event
TFORM6 = '1I ' / data format of the field: 2-byte INTEGER
TTYPE7 = 'SPREAD ' / Spatial spreading of event
TFORM7 = '1I ' / data format of the field: 2-byte INTEGER
TTYPE8 = 'RAWX ' / X position of photon in telemetry
TFORM8 = '1I ' / data format of the field: 2-byte INTEGER
TUNIT8 = 'pixel ' / physical unit of field
TTYPE9 = 'RAWY ' / Y position of photon in telemetry
TFORM9 = '1I ' / data format of the field: 2-byte INTEGER
TUNIT9 = 'pixel ' / physical unit of field
TTYPE10 = 'DETX ' / Detector X position of photon
TFORM10 = '1I ' / data format of the field: 2-byte INTEGER
TUNIT10 = 'pixel ' / physical unit of field
TTYPE11 = 'DETY ' / Detector Y position of photon
TFORM11 = '1I ' / data format of the field: 2-byte INTEGER
TUNIT11 = 'pixel ' / physical unit of field
TTYPE12 = 'RTI ' / Rise time invariant
TFORM12 = '1I ' / data format of the field: 2-byte INTEGER
EXTNAME = 'EVENTS ' / name of this binary table extension
HDUCLASS= 'OGIP ' / format conforms to OGIP/GSFC conventions
HDUCLAS1= 'EVENTS ' / Extension contains Events
SIS
XTENSION= 'BINTABLE' / binary table extension
... etc ...
TFIELDS = 11 / number of fields in each row
TTYPE1 = 'TIME ' / Photon arrival time
TFORM1 = '1D ' / data format of the field: DOUBLE PRECISION
TUNIT1 = 's ' / physical unit of field
TTYPE2 = 'PI ' / Pulse Invariant bin number
TFORM2 = '1J ' / data format of the field: 4-byte INTEGER
TUNIT2 = 'channel ' / physical unit of field
TTYPE3 = 'X ' / projected X position of photon on sky
TFORM3 = '1I ' / data format of the field: 2-byte INTEGER
TUNIT3 = 'pixel ' / physical unit of field
TTYPE4 = 'Y ' / projected Y position of photon on sky
TFORM4 = '1I ' / data format of the field: 2-byte INTEGER
TUNIT4 = 'pixel ' / physical unit of field
TTYPE5 = 'RAWX ' / X position of photon in telemetry
TFORM5 = '1I ' / data format of the field: 2-byte INTEGER
TUNIT5 = 'pixel ' / physical unit of field
TTYPE6 = 'RAWY ' / Y position of photon in telemetry
TFORM6 = '1I ' / data format of the field: 2-byte INTEGER
TUNIT6 = 'pixel ' / physical unit of field
TTYPE7 = 'PHA ' / Pulse Height Analyzer bin number
TFORM7 = '1I ' / data format of the field: 2-byte INTEGER
TUNIT7 = 'channel ' / physical unit of field
TTYPE8 = 'DETX ' / Detector X position of photon
TFORM8 = '1I ' / data format of the field: 2-byte INTEGER
TUNIT8 = 'pixel ' / physical unit of field
TTYPE9 = 'DETY ' / Detector Y position of photon
TFORM9 = '1I ' / data format of the field: 2-byte INTEGER
TUNIT9 = 'pixel ' / physical unit of field
TTYPE10 = 'GRADE ' / How the event was split between detector pixe
TFORM10 = '1I ' / data format of the field: 2-byte INTEGER
TTYPE11 = 'CCDID ' / The CCD the event was detected in
TFORM11 = '1I ' / data format of the field: 2-byte INTEGER
EXTNAME = 'EVENTS ' / name of this binary table extension
HDUCLASS= 'OGIP ' / format conforms to OGIP/GSFC conventions
HDUCLAS1= 'EVENTS ' / Extension contains Events
PSPC
XTENSION= 'BINTABLE' / binary table extension
... etc ...
TFIELDS = 8 / number of fields in each row
TTYPE1 = 'X ' / projected X position of photon on sky
TFORM1 = '1I ' / data format of the field: 2-byte INTEGER
TUNIT1 = 'PIXEL ' / unit: 0.5 arcsecond x 0.5 arcsecond pixel
TTYPE2 = 'Y ' / projected Y position of photon on sky
TFORM2 = '1I ' / data format of the field: 2-byte INTEGER
TUNIT2 = 'PIXEL ' / unit: 0.5 arcsecond x 0.5 arcsecond pixel
TTYPE3 = 'PHA ' / Pulse Height Analyzer bin number
TFORM3 = '1I ' / data format of the field: 2-byte INTEGER
TUNIT3 = 'CHAN ' / unit: channels
TTYPE4 = 'PI ' / Pulse Invariant bin number
TFORM4 = '1I ' / data format of the field: 2-byte INTEGER
TUNIT4 = 'CHAN ' / unit: channels
TTYPE5 = 'TIME ' / spacecraft clock time of event
TFORM5 = '1D ' / data format of the field: DOUBLE PRECISION
TUNIT5 = 'S ' / unit: seconds
TTYPE6 = 'DETX ' / corrected X coordinate of photon
TFORM6 = '1I ' / data format of the field: 2-byte INTEGER
TUNIT6 = 'PIXEL ' / unit: 0.93 arcsecond x 0.93 arcsecond pixel
TTYPE7 = 'DETY ' / corrected Y coordinate of photon
TFORM7 = '1I ' / data format of the field: 2-byte INTEGER
TUNIT7 = 'PIXEL ' / unit: 0.93 arcsecond x 0.93 arcsecond pixel
TTYPE8 = 'STATUS ' / status flag for the event
TFORM8 = '1I ' / data format of the field: 2-byte INTEGER
TUNIT8 = 'CODED ' / unit: None
EXTNAME = 'STDEVT ' / name: Standard Events
and similarly for
EXTNAME = 'REJEVT ' / name: Rejected Events
- A
- Einstein FPCS
- ANGLE
- Einstein FPCS
- B
- Derived
| Einstein FPCS
- CCDID
- ASCA SIS
- ClstrPos
- XTE HEXTE
- Column names used within the OGIP
- mission/instrument specific
- INSTRUMENT-SPECIFIC COLUMN NAMES
- ASCA
- ASCA
| ASCA SIS
- BBXRT
- BBXRT
- Einstein
- Einstein
- Examples
- EXAMPLE HEADERS
- SAS-2
- SAS-2
- XTE
- XTE
| XTE HEXTE
- multi-mission
- MULTI-MISSION COLUMN NAMES
- housekeeping
- Spacecraft Housekeeping Information
- quality flags
- Data Quality Flags
- spatial
- Spatial Information
- spectral
- Spectral Information
- temporal
- Temporal Information
- DEC
- Derived
- DEL_TIME
- SAS-2
- DET-POS
- Einstein FPCS
- DETECTOR
- BBXRT
- DETX
- Measured
- DETY
- Measured
- DQF
- Einstein FPCS
- ENDEVENT
- SAS-2
- ENERGY
- Spectral Information
- Event Lists
- definition
- Definition of an Event
- EventWord
- XTE
- Example Headers
- ASCA
- GIS
- GIS
- SIS
- SIS
- ROSAT
- PSPC
- PSPC
- FLAG
- SAS-2
- FOVCLASS
- SAS-2
- GRADE
- ASCA SIS
- GUARD
- BBXRT
- Introduction
- INTRODUCTION
- L
- Derived
- LAT_GEO
- Spacecraft Housekeeping Information
- LED
- BBXRT
- LiveTime
- XTE
- LON_GEO
- Spacecraft Housekeeping Information
- NEVENT
- SAS-2
- PHA
- Spectral Information
- PHAS
- ASCA SIS
| BBXRT
- PI
- Spectral Information
- PPU
- BBXRT
- PTP
- BBXRT
- RA
- Derived
- RAD_GEO
- Spacecraft Housekeeping Information
- RAWX
- Measured
- RAWY
- Measured
- RISE_TIME
- ASCA GIS
- RTI
- ASCA GIS
- SPINRATE
- Spacecraft Housekeeping Information
- SPKDAT
- SAS-2
- SPREAD
- ASCA GIS
- STATUS
- Data Quality Flags
- TIME
- Temporal Information
- VLE
- BBXRT
- WAVELENGTH
- Spectral Information
- WIRE-NUM
- Einstein FPCS
- X
- Derived
- X_COORD
- Spacecraft Housekeeping Information
- XAXISDEC
- Spacecraft Housekeeping Information
- XAXISRA
- Spacecraft Housekeeping Information
- Y
- Derived
- Y_COORD
- Spacecraft Housekeeping Information
- Z_COORD
- Spacecraft Housekeeping Information
- ZAXISDEC
- Spacecraft Housekeeping Information
- ZAXISRA
- Spacecraft Housekeeping Information
We thank the numerous people, both inside and outside the OGIP, who have
contributed ideas and suggestions. In particular we thank Alan Smale,
Nick White, Bill Pence & Lorella Angelini
for their critical reading of the various drafts.
Angelini, L., et al.,
1992.
In preparation.
George, I.M.,
1992. Legacy, 1, 56,
(CAL/GEN/91-001).
George, I.M., Arnaud, K.A., Pence, W. & Ruamsuwan, L.,
1992a.
(CAL/GEN/92-002).
George, I.M., et al.,
1992b. In preparation.
(CAL/SW/92-004).
The following useful links are available (in the HTML version of this
document only):
This document was generated using the
LaTeX2HTML translator Version 99.2beta8 (1.46)
Copyright © 1993, 1994, 1995, 1996,
Nikos Drakos,
Computer Based Learning Unit, University of Leeds.
Copyright © 1997, 1998, 1999,
Ross Moore,
Mathematics Department, Macquarie University, Sydney.
The command line arguments were:
latex2html -t OGIP/94-003 -image_type gif -split 3 ogip_94_003.tex
The translation was initiated by Michael Arida on 2001-06-28
This file was last modified on Wednesday, 20-Oct-2021 10:40:05 EDT
This page maintained by:
Michael Arida (SP Sys); arida@milkyway.gsfc.nasa.gov
HEASARC Guest Observer Facility
|