Data Formats

Warning

Since November 2015 there is the Data formats for gamma-ray astronomy project. Most of the information in gammapy/docs should be moved there. Probably keeping the overview table which formats are supported in Gammapy and linking format names and class names should be kept.

Here we describe various data file formats that are useful for the exchange of TeV data, instrument response functions and results.

Note

In Access datasets (gammapy.datasets) you find example gamma-ray datasets, some in the formats described here.

Where available and useful existing standards are used, e.g. for spectral data the X-ray community has developed the PHA, ARF and RMF file formats and they have developed powerful tools to work with data in that format.

In other cases (flux points, point spread function, run lists) there is no standard and we simply use general-purpose file formats define our own semantics as described in the File formats section.

Overview

Here’s an overview of the file formats supported by Gammapy and Gammalib:

Type Format Name Gammapy Gammalib
Events EVENTS EventList GEventList
Effective area AEFF_2D EffectiveAreaTable2D GCTAAeff2D
Effective area ARF EffectiveAreaTable GCTAAeffArf
Energy dispersion EDISP_2D EnergyDispersion2D GCTAEdisp2D
Energy dispersion RMF EnergyDispersion GCTAEdispRMF
PSF PSF_2D_GAUSS EnergyDependentMultiGaussPSF GCTAPsf2D
PSF PSF_2D_KING PSFKing GCTAPsfKing
PSF no spec available TablePSF GCTAPsfVector
PSF gtpsf output EnergyDependentTablePSF N/A
PSF psf_table PSF3D GCTAPsfTable
PSF no spec available N/A GCTACubePsf
Background BACKGROUND_3D FOVCubeBackgroundModel GCTABackground3D
Background BACKGROUND_2D EnergyOffsetBackgroundModel N/A
Background no spec available N/A GCTAModelRadialAcceptance
Background no spec available N/A GCTACubeBackground
Exposure EXPOSURE_3D SkyCube GCTACubeExposure
Counts 3D SkyCube GCTAEventCube
Counts Image SkyImage GSkyMap
Counts PHA CountsSpectrum GPha

Notes:

  • The Gammalib docs contain a nice overview of IRFs here and detailed explanations of some IRF here.
  • We probably should unify / shorten the IRF class names in Gammapy.
  • There’s quite a few classes in Gammapy that don’t have a well-defined format. We should add a way to serialise every class and document the format for easier interop.
  • Maybe add info which format is used by Fermi, HESS HD/PA, CTA?
  • For every format there should be one or several test data files. This could even be in a repo that’s shared by Gammalib / Gammapy.
  • TODO: For TablePSF FITS I/O in the Gammalib format should be implemented.
  • TODO: the format name should be chosen so that it corresponds to FITS extension names or filenames. Is this the case? Can we agree on names with Gammalib?