EVENTS
The EVENTS extension is a binary FITS table that contains an event list.
Each row of the table provides information that characterises one event.
The mandatory and optional columns of the table are listed below. In
addition, a list of header keywords providing metadata is specified.
Also here there are mandatory and optional keywords.
The recommended extension name of the binary table is EVENTS.
Mandatory columns
We follow the OGIP event list standard.
EVENT_IDtype: int64Event identification number at the DL3 level. See notes on EVENT_ID below.
TIMEtype: float64, unit: sEvent time (see Time)
RAtype: float, unit: degReconstructed event Right Ascension (see RA / DEC).
DECtype: float, unit: degReconstructed event Declination (see RA / DEC).
ENERGYtype: float, unit: TeVReconstructed event energy.
Optional columns
Note
None of the following columns is required to be part of an EVENTS
extension. Any software using these columns should first check whether the
columns exist, and warn in case of their absence. Any software ignoring
these columns should make sure that their presence does not deteriorate the
functioning of the software.
EVENT_TYPEtype: bit field (in FITStform=32X)Event quality partition.
MULTIPtype: intTelescope multiplicity. Number of telescopes that have seen the event.
GLONtype: float, unit: degReconstructed event Galactic longitude (see Galactic).
GLATtype: float, unit: degReconstructed event Galactic latitude (see Galactic).
ALTtype: float, unit: degReconstructed altitude (see Alt / Az)
AZtype: float, unit: degReconstructed azimuth (see Alt / Az)
DETXtype: float, unit: degReconstructed field of view X (see Field of view).
DETYtype: float, unit: degReconstructed field of view Y (see Field of view).
THETAtype: float, unit: degReconstructed field of view offset angle (see Field of view).
PHItype: float, unit: degReconstructed field of view position angle (see Field of view).
GAMMANESStype: floatClassification score of a signal / background separation. SHOULD be between 0 and 1, with higher values indicating larger confidence that the event was produced by a gamma ray.
DIR_ERRtype: float, unit: degDirection error of reconstruction
ENERGY_ERRtype: float, unit: TeVError on reconstructed event energy
COREXtype: float, unit: mReconstructed core position X of shower
COREYtype: float, unit: mReconstructed core position Y of shower
CORE_ERRtype: float, unit: mError on reconstructed core position of shower
XMAXtype: float, unit: radiation lengthsFirst interaction depth
XMAX_ERRtype: float, unit: radiation lengthsError on first interaction depth
HIL_MSWtype: floatHillas mean scaled width
HIL_MSW_ERRtype: floatHillas mean scaled width error
HIL_MSLtype: floatHillas mean scaled length
HIL_MSL_ERRtype: floatHillas mean scaled length error
Mandatory header keywords
The standard FITS reference time header keywords should be used (see Formats). An observatory Earth location should be given as well (see Earth location).
HDUCLASStype: stringSignal conformance with HEASARC/OGIP conventions (option: ‘OGIP’). See HDU classes.
HDUDOCtype: stringReference to documentation where data format is documented. See HDU classes.
HDUVERStype: stringVersion of the format (e.g. ‘1.0.0’). See HDU classes.
HDUCLAS1type: stringPrimary extension class (option: ‘EVENTS’). See HDU classes.
OBS_IDtype: intUnique observation identifier (Run number)
TSTARTtype: float, unit: sStart time of observation (relative to reference time, see Time)
TSTOPtype: float, unit: sEnd time of observation (relative to reference time, see Time)
ONTIMEtype: float, unit: sTotal good time (sum of length of all Good Time Intervals). If a Good Time Interval (GTI) table is provided,
ONTIMEshould be calculated as the sum of those intervals. Corrections for instrumental dead time effects are NOT included.
LIVETIMEtype: float, unit: sTotal time (in seconds) on source, corrected for the total instrumental dead time effect.
DEADCtype: floatDead time correction, defined by
LIVETIME/ONTIME. Is comprised in [0,1]. Defined to be 0 ifONTIME=0.
OBS_MODEtype: stringObservation mode. See notes on OBS_MODE below.
RA_PNTtype: float, unit: degPointing Right Ascension (see RA / DEC). Not mandatory if
OBS_MODE=DRIFT, but average values could optionally be provided.
DEC_PNTtype: float, unit: degPointing declination (see RA / DEC). Not mandatory if
OBS_MODE=DRIFT, but average values could optionally be provided.
ALT_PNTtype: float, unit: degPointing Altitude (see Alt / Az). Only mandatory if
OBS_MODE=DRIFT
AZ_PNTtype: float, unit: degPointing azimuth (see Alt / Az). Only mandatory if
OBS_MODE=DRIFT
EQUINOXtype: floatEquinox in years for the celestial coordinate system in which positions given in either the header or data are expressed (options: 2000.0). See also HFWG Recommendation R3 for the OGIP standard.
RADECSYStype: stringStellar reference frame used for the celestial coordinate system in which positions given in either the header or data are expressed. (options: ‘ICRS’, ‘FK5’). See also HFWG Recommendation R3 for the OGIP standard.
ORIGINtype: stringOrganisation that created the FITS file. This can be the same as
TELESCOP(e.g. “HESS”), but it could also be different if an organisation has multiple telescopes (e.g. “NASA” or “ESO”).
TELESCOPtype: stringTelescope (e.g. ‘CTA’, ‘HESS’, ‘VERITAS’, ‘MAGIC’, ‘FACT’)
INSTRUMEtype: stringInstrument used to aquire the data contained in the file. Each organisation and telescop has to define this. E.g. for CTA it could be ‘North’ and ‘South’, or sub-array configurations, this has not been defined yet.
CREATORtype: stringSoftware that created the file. When appropriate, the value of the
CREATORkeyword should also reference the specific version of the program that created the FITS file. It is intented that this keyword should refer to the program that originally defined the FITS file structure and wrote the contents. If a FITS file is subsequently copied largely intact into a new FITS by another program, then the value of theCREATORkeyword should still refer to the original program.HISTORYkeywords should be used instead to document any further processing that is performed on the file after it is created. For more reading on the OGIP standard, see here.
Optional header keywords
OBSERVERtype: stringName of observer. This could be for example the PI of a proposal.
CREATEDtype: stringTime when file was created in ISO standard date representation “ccyy-mm-ddThh:mm:ss” (UTC)
OBJECTtype: stringObserved object (e.g. ‘Crab’)
RA_OBJtype: float, unit: degRight ascension of
OBJECT
DEC_OBJtype: float, unit: degDeclination of
OBJECT
EV_CLASStype: strEvent class. See notes on EV_CLASS and EVENT_TYPE below.
TELAPSEtype: float, unit: sTime interval between start and stop time (
TELAPSE=TSTOP-TSTART). Any gaps due to bad weather, or high background counts and/or other anomalies, are included.
Warning
Keywords below seem to be pretty low-level and eventually instrument specific. It needs to be discussed whether a recommendation on these keywords should be made, or whether the definition should be left to the respective consortia.
HDUCLAS2type: stringSecondary extension class (option: ‘ACCEPTED’). See HDU classes.
TELLISTtype: stringTelescope IDs in observation (e.g. ‘1,2,3,4’)
N_TELStype: intNumber of observing telescopes
TASSIGNtype: stringPlace of time reference (‘Namibia’)
DST_VERtype: stringVersion of DST/Data production
ANA_VERtype: stringReconstruction software version
CAL_VERtype: stringCalibration software version
CONV_DEPtype: floatconvergence depth (0 for parallel pointing)
CONV_RAtype: float, unit: degConvergence Right Ascension
CONV_DECtype: float, unit: degConvergence Declination
TRGRATEtype: float, unit: HzMean system trigger rate
ZTRGRATEtype: float, unit: HzZenith equivalent mean system trigger rate
MUONEFFtype: floatMean muon efficiency
BROKPIXtype: floatFraction of broken pixels (0.15 means 15% broken pixels)
AIRTEMPtype: float, unit: deg CMean air temperature at ground during the observation.
PRESSUREtype: float, unit: hPaMean air pressure at ground during the observation.
RELHUMtype: floatRelative humidity
NSBLEVELtype: float, unit: a.u.Measure for night sky background level
Notes
This paragraph contains some explanatory notes on some of the columns and header keys mentioned above.
EVENT_ID
Most analyses with high-level science tools don’t need EVENT_ID information.
But being able to uniquely identify every event is important, e.g. when
comparing the high-level reconstructed event parameters (RA, DEC,
ENERGY) for different calibrations, reconstructions or gamma-hadron
separations.
Assigning a unique EVENT_ID during data taking can be difficult or
impossible. E.g. in H.E.S.S. we have two numbers BUNCH_ID_HESS and
EVENT_ID_HESS that only together uniquely identify an event within a given
run (i.e. OBS_ID). Probably the scheme to uniquely identify events at the
DL0 level for CTA will be even more complicated, because of the much larger
number of telescopes and events.
So given that data taking and event identification is different for every IACT
at low data levels and is already fixed for existing IACTs, we propose here to
have an EVENT_ID that is simpler and works the same for all IACTs at the DL3
level.
As an example: for H.E.S.S. we achieve this by using an INT64 for EVENT_ID
and to store EVENT_ID = (BUNCH_ID_HESS << 32) | (EVENT_ID_HESS), i.e. use
the upper bits to contain the low-level bunch ID and the lower bits to contains
the low-level event ID. This encoding is unique and reversible, i.e. it’s easy
to go back to BUNCH_ID_HESS and EVENT_ID_HESS for a given EVENT_ID,
and to low-level checks (e.g. look at the shower images for a given event that
behaves strangely in reconstructed high-level parameters).
EV_CLASS and EVENT_TYPE
Currently in this format specification, event class EV_CLASS is a header key
(i.e. the same for all events in a given event list) and EVENT_TYPE is a
bitfield column (i.e. can have a different value for each event). Both are
optional at this time, only used as provenance information, not by science tools
to make any decisions how to analyse the data.
The reason for this is simply that we have not agreed yet on a scheme what event
class and event type means, and how it should be used by science tools for
analysis. Developing this will be one of the major topics for the next version
of the spec. It is likely that a proper definition of event classes and types
will not be compatible with what is currently defined here, so not filling
EV_CLASS and EVENT_TYPE when creating DL3 data is not a bad idea.
To summarise a bit the discussions on this important point in the past years, they were mostly done by looking at what Fermi-LAT is doing and some prototyping in H.E.S.S. to export DL3 data to FITS.
The scheme in Fermi-LAT for event classes and event types is nicely summarised here or here. There event classes and types are key parts of the data model, used for EVENT to IRF association and even end users need to learn about them and pass event class and type information when using science tools.
One option could be to mostly adopt what Fermi-LAT does for IACTs. However, a major difference is that Fermi-LAT is a more stable detector, that has a CALDB of a very limited number or IRFs that can be used for all data, whereas for IACTs with changing telescope configurations, degrading mirrors, changing atmosphere, zenith angle, … most likely we will have to produce per-observation IRFs, and then it’s easier to bundle the IRFs with the EVENTS in one file, and the use of event class and type to link EVENTS and IRFs is no longer needed.
An alternative scheme is to use the term “event class” to describe a given
analysis configuration. This is e.g. how we currently use EV_CLASS in
H.E.S.S., we fill values like “standard” or “hard” or “loose” to describe a
given full configuration that is the result of a calibration, event
reconstruction and gamma-hadron separation pipeline. This is similar to what
Fermi-LAT does, except less sophisticated, the event classes are completely
independent, there is no nesting, and separate events and IRF files are produced
for each class/configuration. To analyse data from a given class, the user
chooses which set of files to download (e.g. “loose” for pulsars or “hard” for a
bright source where a good PSF is needed), and then the science tools don’t need
to do anything with EV_CLASS, it is just provenance information. Some people
are experimenting with the use of EVENT_TYPE in a similar way as Fermi-LAT,
e.g. to have event quality partitioning based on number of telescopes that saw a
given event, or other criteria. Again, it is left to users to split events by
EVENT_TYPE and produce IRFs for each event type and pass those for a joint
fit to the science tools, as there is no agreement or implementation yet in the
science tools to support EVENT_TYPE directly.
So to conclude and summarise again: EV_CLASS and EVENT_TYPE as mentioned
here in this spec are optional and very preliminary. Defining event class and
type for IACTs needs more prototyping by the science tools and current IACTs and
CTA and discussion, and then a proposal for a specification.
OBS_MODE
The keyword OBS_MODE specifies the mode of the observation.
This is used in cases where the instrument or detector can be configured to
operate in different modes which significantly affect the resulting data, or to accomodate
different types of instrument. More details can be found
here
Most IACT data will be POINTING, indicating a constant pointing in equatorial coordinates.
In addition to the OGIP-defined values (POINTING, RASTER, SLEW and SCAN), we
define the option DRIFT to accomodate ground-based wide-field instruments, in
which local zenith/azimuth coordinates remain constant. In this case, the header keywords
RA_PNT and DEC_PNT are no longer mandatory, and instead ALT_PNT and AZ_PNT
are required.
It is likely that OBS_MODE in the future will be a key piece of information
in the DL3 data model, defining the observation mode (e.g. pointed, divergent,
slewing, …) and being required to analyse the data correctly.