Introduction to pyirf

pyirf aims to provide functions to calculate the Instrument Response Functions (IRFs) and sensitivity for Imaging Air Cherenkov Telescopes.

To support a wide range of use cases, pyirf opts for a library approach of composable building blocks with well-defined inputs and outputs.

For more information on IRFs, have a look at the Specification of the Data Formats for Gamma-Ray Astronomy or the ctools documentation on IRFs.

Currently, pyirf allows calculation of the usual factorization of the IRFs into:

  • Effective area

  • Energy migration

  • Point spread function

Additionally, functions for calculating point-source flux sensitivity are provided. Flux sensitivity is defined as the smallest flux an IACT can detect with a certain significance, usually 5 σ according to the Li&Ma likelihood ratio test, in a specified amount of time.

pyirf also provides functions to calculate event weights, that are needed to translate a set of simulations to a physical flux for calculating sensitivity and expected event counts.

Event selection with energy dependent cuts is also supported, but at the moment, only rudimentary functions to find optimal cuts are provided.

Input formats

pyirf does not rely on specific input file formats. All functions take numpy arrays, astropy quantities or astropy tables for the required data and also return the results as these objects.

~pyirf.io provides functions to export the internal IRF representation to FITS files following the Specification of the Data Formats for Gamma-Ray Astronomy

DL2 event lists

Most functions for calculating IRFs need DL2 event lists as input. We use ~astropy.table.QTable instances for this. QTable are very similar to the standard ~astropy.table.Table, but offer better interoperability with astropy.units.Quantity.

We expect certain columns to be present in the tables with the appropriate units. To learn which functions need which columns to be present, have a look at the API Documentation

Most functions only need a small subgroup of these columns.

Column definitions for DL2 event lists

Column

Unit

Explanation

true_energy

TeV

True energy of the simulated shower

weight

Event weight

true_source_fov_offset

deg

Distance of the true origin to the FOV center

reco_source_fov_offset

deg

Distance of the reco origin to the FOV center

true_alt

deg

True altitude of the shower origin

true_az

deg

True azimuth of the shower origin

pointing_alt

deg

Altitude of the field of view center

pointing_az

deg

Azimuth of the field of view center

reco_energy

TeV

Reconstructed energy of the simulated shower

reco_alt

deg

Reconstructed altitude of shower origin

reco_az

deg

Reconstructed azimuth of shower origin

gh_score

Gamma/Hadron classification output

multiplicity

Number of telescopes used in the reconstruction