Skip to content

Data format for analysis of IACT data

Jump to bottom
Cosimo Nigro edited this page May 29, 2020 · 4 revisions

Introduction

This wiki page describes the data formats accepted by gLike to perform likelihood analysis with Imaging Air Cherenkov Telescopes (IACTs) data, i.e. when using the classes Iact1dUnbinnedLkl and Iact1dBinnedLkl.

A good introduction to the data format for IACT (and gamma-ray instruments in general) can be found in the Data formats for gamma-ray astronomy documentation. This wikipage assumes you are familiar with the concepts therein.

Unbinned data formats

Unbinned data formats consists basically of event lists and Instrument Response Function (IRF). As we shall see, additional components to be included in the likelihood analysis can be specified.
The IactEventListIrf class represents the interface between the physical data (in ROOT or FITS format) and the likelihood object Iact1dUnbinnedLkl. We provide an abstract description of its content first, followed by a more detailed description of the possible input format.

IactEventListIrf

  • Event Lists: two distinct lists of events are provided: one from a signal (or ON) sky region, the other from a background (or OFF) sky region. Each event in the list carries the information on its estimated energy (E'), coordinates (RA and DEC) and timestamp (t). At the moment only energy-dependent analysis are performed, so the coordinates and timestamps can be omitted (or inserted as null);
  • IRF components: gLike can accept different IRF components with effective area and migration matrix constituting a minimum to perform a classical 1D analysis.
    Additional IRFs available are:
    • effective area of the OFF region,
    • bias and resolution of the migration matrix in place of the latter;
  • mandatory for the likelihood computation are the observation effective time and the ON to OFF exposures ratio;
  • additional likelihood components that can be specified are:
    • histogram of dN/(dE' dt) vs log(E') for background events,
    • histogram of dN/(dE' dt) vs log(E') for foreground events (i.e. those produced by a nuisance gamma-ray source in the ON region).

Note on units: energies are specified in units of log10(E / GeV), times in s, effective areas in cm^2.

ROOT format

Examples of input ROOT files are available in gLike/data/root.
The data format of the ROOT files is directly defined by the IactEventListIrf class. A gLike ROOT input is nothing more than an instance of such class written in a ROOT file.
Follows a schema of the class attributes, listing the information you should extract from your IACT data (and the ROOT types you should generate from them) in order to produce a gLike ROOT input.

quantity / component attribute ROOT type mandatory?
ON event list fOnSample TNtupleD* yes
OFF event list fOffSample TNtupleD* yes
minimum estimated energy fEpmin Double_t no
minimum estimated energy fEpmax Double_t no
ON to OFF exposure ratio fTau Double_t yes
ON to OFF exposure ratio stat. error fDTau Double_t no
probability value of ON/OFF agreement fTauPValue Double_t no
observation time fObsTime Double_t yes
effective area fHAeff TH1F* yes
effective area for the OFF region fHAeffOff TH1F* no
resolution of the energy dispersion fGEreso TGraph* no (if fMigMatrix non-empty)
bias of the energy dispersion fGEbias TGraph* no (if fMigMatrix non-empty)
migration matrix fMigMatrix TH2F* no (if fGEreso and fGEbias non-empty)
dN/(dE' dt) vs log(E') for background events fHdNdEpBkg TH1F* no
dN/(dE' dt) vs log(E') for foreground events fHdNdEpFrg TH1F* no

the TNtupleD entries have the following structure

// structure to read the events from the NTuple
typedef struct {
  Double_t  E;        // [GeV] measured energy of event
  Double_t  pointRA;  // [deg] RA of telescope pointing direction
  Double_t  pointDEC; // [deg] DEC of telescope pointing direction
  Double_t  dRA;      // [deg] distance to pointing direction in the RA axis
  Double_t  dDEC;     // [deg] distance to pointing direction in the DEC axis
  Double_t  t;        // [MJD] arrival time
  Double_t  had;      // [1]   hadronness
} IactEvent_t;

and can be filled with the FillOnEvent and FillOffEvent functions.

Check out the data

Once you build gLike, you can examine the ROOT inputs from the ROOT terminal

root [0] IactEventListIrf *dataset = new IactEventListIrf("dataset1", "root dataset", "data/root/genericIact_dataIRF_01.root")
(IactEventListIrf *) 0x7fd67608c570
root [1] dataset->Print()
Energy Range: 59.2 - 10000 GeV 
ON/OFF Norm (tau): 1.00402 +- 0.00599 (Prob.: -1)
Observation Time: 162000 s 
root [2] dataset->PlotOverview()

FITS format

The FITS input definition is based on the standard defined in the Data formats for gamma-ray astronomy. We rely on an external software to generate gLike FITS input, specifically on gammapy.

To generate gLike FITS inputs check the example of unbinned spectral data extraction in gammapy-extra; there you will find a script reducing some DL3 data from the latest H.E.S.S. public data release in an unbinned format readable by gLike. The unbinned FITS format is based on the 1D counts spectral data definition in the data formats for gamma-ray astronomy documentation, it would be good to familiarise yourself with the concepts therein.

The IactEventListIrf class automatically digest FITS files, as an example try:

root [0] IactEventListIrf *dataset = new IactEventListIrf("dataset1", "fits dataset", "data/fits/obs_id_23523_unbinned_spectrum.fits")
(IactEventListIrf *) 0x7fa491686b00
root [1] dataset->Print()
Energy Range: 1 - 1e+06 GeV 
ON/OFF Norm (tau): 12 +- 0 (Prob.: -1)
Observation Time: 1581.74 s 
root [2] dataset->PlotOverview()

Note a patch in ROOT was needed to allow reading the complicated structure of the migration matrix in these FITS data. Therefore gLike supports FITS data input only if you are using a recent ROOT version > 6.20.04.

Binned data formats

This section will be completed once Iact1dBinnedLkl will be made independent from Iact1dUnbinnedLkl (at the moment the former inherits from the latter)

Clone this wiki locally