next_inactive up previous


OGIP Memo OGIP/94-003


GUIDELINES FOR DEFINING FITS FORMATS FOR EVENT LISTS

Code 668,
NASA/GSFC,
Greenbelt,
MD20771.




Version: 1994 Dec 01







SUMMARY

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


Contents

LOG OF SIGNIFICANT CHANGES




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:

  1. The event list is a sparse histogram (i.e., only filled bins are present).
  2. Each bin (by definition) has a population of one event.
  3. 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

Measured

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

ASCA GIS

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 $3\times3$ 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

Einstein FPCS

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

OUTSTANDING

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

ASCA


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

ROSAT


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


Index

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

ACKNOWLEDGMENTS

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.

REFERENCES


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).

USEFUL LINKS TO OTHER HTML PAGES

The following useful links are available (in the HTML version of this document only):

About this document ...

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



next_inactive up previous
HEASARC home page

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

Michael Arida 2001-06-28