# Gammapy: a python package for (not only) gamma-ray astronomy

Claudio Galelli, Régis Terrier, Catherine Boisson, Bruno Khélifi

► To cite this version:

Claudio Galelli, Régis Terrier, Catherine Boisson, Bruno Khélifi. Gammapy: a python package for (not only) gamma-ray astronomy. 13th Cosmic-Ray International Studies and Multi-messenger As- troparticle Conference, Jun 2024, Trapani, Italy. pp.012032, 10.1088/1742-6596/3053/1/012032 . hal-05237023

HAL Id: hal-05237023

https://hal.science/hal-05237023v1

Submitted on 8 Sep 2025

HAL is a multi-disciplinary open access
archive for the deposit and dissemination of sci-
entific research documents, whether they are pub-
lished or not. The documents may come from
teaching and research institutions in France or
abroad, or from public or private research centers.

L'archive ouverte pluridisciplinaire HAL, est
destinée au dépôt et à la diffusion de documents
scientifiques de niveau recherche, publiés ou non,
émanant des établissements d'enseignement et de
recherche français ou étrangers, des laboratoires
publics ou privés.

<figure><img src="image_1.png" /></figure>

Distributed under a Creative Commons Attribution 4.0 International License
<figure><img src="image_2.png" /></figure>

PAPER • OPEN ACCESS

# Gammapy: a python package for (not only) gamma-ray astronomy

To cite this article: Claudio Galelli *et al* 2025 *J. Phys.: Conf. Ser.* **3053** 012032

View the [article online](#) for updates and enhancements.

You may also like

- [Recent outreach activities of the EEE Project](#)
C. Ripoli, M. Abbrescia, C. Avanzini et al.

- [GINGER Status Report](#)
Carlo Altucci, Francesco Bajardi, Andrea Basti et al.

- [Exploring cosmic rays with educational outreach activities: a long-term study of the correlation between atmospheric conditions and muon counts](#)
D. Miceli, C. Arcaro, S. Canella et al.

UNITED THROUGH SCIENCE & TECHNOLOGY

<figure><img src="image_3.png" /></figure>

The Electrochemical Society
Advancing solid state & electrochemical science & technology

248th
ECS Meeting
Chicago, IL
October 12-16, 2025
Hilton Chicago

<figure><img src="image_4.png" /></figure>

Science +
Technology +
YOU!

Register by
September 22
to save $$

REGISTER NOW
# Gammapy: a python package for (not only) gamma-ray astronomy

Claudio Galelli<fnref n="1" />, Regis Terrier<fnref n="2" />, Catherine Boisson<fnref n="1" />, and Bruno Khélifi<fnref n="2" />

¹LUTh, Observatoire de Paris, Meudon, France

²APC, Université Paris Cité, Paris, France

E-mail: claudio.galelli@obspm.fr

**Abstract.** Gammapy ¹is a community-driven ²open-source Python package to analyze very high-energy gamma-ray astronomical data. Created in 2014, it has since expanded to support analysis methods in multiwavelength and multimessenger astrophysics. Currently, in version 1.2, Gammapy is utilized by various instruments like HESS, VERITAS, HAWC, and Fermi-LAT, and tested with X-ray and neutrino data, and is the base for the science analysis tools of the Cherenkov Telescope Array Observatory <fnref n="3" />. Operating on the common open FITS-based data format GADF, it ensures interoperability between different experiments. The package's analysis pipeline handles data, instrument response functions, and dependencies on time, energy, and sky location. It offers diverse methods for background estimation and data reduction, producing standardized datasets. Gammapy includes spatial, spectral, and temporal models, supporting custom model integration and permitting maximum-likelihood fitting on datasets. Additionally, it provides tools for accessing flux points, likelihood profiles, and light curves, facilitating comprehensive time-domain analyses. Gammapy has de facto become the reference software for VHE gamma-ray analysis, strives to be integrated into the open science framework with the FAIR4RS guidelines [20], and will adopt the VODF format in future versions.

## 1 Introduction

Gammapy [1] is an open-source Python package that aims to be a standard and interoperable analysis tool for very-high-energy (VHE) gamma-ray experiments and more. It operates on high-level data from different instruments, containing event lists, instrument response functions (IRFs), metadata, or more complex data structures. This high-level data is produced at the end of the low-level analysis pipelines of the instruments, like imaging atmospheric Cherenkov telescopes such as H.E.S.S., MAGIC, VERITAS, or CTAO, or water Cherenkov detectors such as HAWC and SWGO, but also space telescopes such as Fermi-LAT [10], and neutrino experiments like KM3NeT.

Gammapy is an affiliated package of `astropy` [3], which it uses for astronomical functionalities, and depends on ` numpy` [4] for array-like data structures, ` matplotlib` [5] for visualization, ` scipy` [6] for algorithms, and `iminuit` [7] for minimization tools. The package is built upon the `gamma-astro-data-format` (GADF) [8] and the serialization to FITS [9] files. This schema is summarized in figure 1

<figure><img src="image_5.png" /></figure>

<footnote n="1">¹https://gammapy.org</footnote>

<footnote n="2">²Contributor list: https://github.com/gammapy/gammapy/graphs/contributors</footnote>

<footnote n="3">³https://www.ctao.org/</footnote>
<figure><img src="image_6.png" /><figcaption>Figure 1: Schema depicting the relation of the Gammapy idea to instruments, format, and dependencies.</figcaption></figure>

Gammapy is a well-established, open-source software package built and maintained by the Very-High-Energy (VHE) gamma-ray astronomy community. This collaborative effort involves a core team of lead developers, sub-package maintainers, and a coordinating committee. Importantly, contributors from various VHE experiments and other fields actively improve the package's core code, documentation, and testing environment.

Reflecting its continuously increased adoption in the scientific community, Gammapy was chosen by the Cherenkov Telescope Array Observatory (CTAO) as the foundation for its Science Analysis Tools (SAT) in 2021 [11]. This recognition was further solidified by Gammapy receiving the Jury Prize in Open Science at the French Ministry of Higher Education, Research, and Innovation's awards ceremony in 2022 [12].

## 2 The Long-term stable v1.0 and the current v1.2

The first long-term stable version of Gammapy, v1.0, was released in November 2022⁴ and is accompanied by a journal paper published on A&A on October 2023. This LTS version will be supported by minor bugfix releases (numbered v1.0.x) until the next long-term stable version v2.0 is released; v1.0.2 was released in December 2023 <fnref n="5" />. This version contains around 50000 lines, of which 34% is the code itself, 22% code testing routines, 26% code documentation, and 9% package documentation.

The typical flow of a Gammapy analysis is divided into two main steps:

1. Data Reduction: the user selects data or filtering techniques, the geometry for the analysis (spectral, spatial, temporal), and in general the analysis type. IRFs and events are selected according to these choices, projected on the geometry, and reduced into matrices along the chosen axes (energy, position, time...), technically known as *data cubes*. The data product of this step is a data container class that inherits from *Dataset*, the central element of a Gammapy analysis.

2. Modeling and fitting: the user chooses models, either custom or from the internal Gammapy model library, describing the spectral, spatial or temporal behavior of the data. The chosen models are associated to the dataset and their parameters are estimated from Poisson maximum likelihood fitting.

This analysis flow is reported in figure 2.

Gammapy allows the production of different VHE gamma-ray data products, drawing on algorithms developed across various astronomical communities (TeV, GeV, and X-ray).

<footnote n="4">⁴https://docs.gammapy.org/1.2/release-notes/v1.0.html</footnote>

<footnote n="5">⁵https://docs.gammapy.org/1.2/release-notes/v1.0.2.html</footnote>
<figure><img src="image_7.png" /><figcaption>Figure 2: Data flow of the Gammapy package: for each data level following the GADF definitions, the container classes are mentioned; the flows between the levels are indicated in grey with their associated classes.</figcaption></figure>

* **1D Spectral Analysis:** Fit spectral models to any region of interest, considering background levels with the reflected background method [15] and optionally energy-dependent cuts. Calculate point-source sensitivity using ON-OFF estimations and derive flux points with likelihood profiles. Additionally, perform 1D spectrum simulations.

* **2D Image Analysis:** Generate significance maps using established statistics (wstat [13] or Cash [14]) and perform source detection. Estimate background levels for excess maps using the Ring Background method, enabling subsequent 2D map fitting.

* **Time-Domain Analysis:** Extract light curves (flux vs. time) with flexible binning options for diverse applications like pulsar analysis or simulating time-variable sources. Evaluate variability parameters for these lightcurves.

* **Data Cube Analysis:** Fit spatial, spectral, and potentially temporal models to data cubes, incorporating background models provided with the Instrument Response Functions (IRFs). Perform flux profile estimations and data cube simulations. This functionality has advanced capabilities for multi-instrument joint analysis (both 3D and 1D).

* **Global features:** Gammapy offers a comprehensive library of source models (analytical and template-based) describing spatial, spectral, and temporal behaviors. Estimate likelihood profiles for fitted parameters and analyze correlated parameter errors. You can also incorporate user-defined models or likelihood functions into any analysis. Additionally, interfaces are provided to dark matter models [17], the Naima library <fnref n="6" />, and the open TeV source catalog gamma-cat <fnref n="7" /> (accessible both through the library and a web interface: http://gamma-sky.net/).

The latest version of Gammapy is v1.2, released on the 29th of February 2024 <fnref n="8" />. One of the main focuses of improvements for this release has been the introduction of the class containers for Metadata

<footnote n="6">⁶https://naima.readthedocs.io/en/latest/</footnote>

<footnote n="7">⁷https://github.com/gammapy/gamma-cat</footnote>

<footnote n="8">⁸https://docs.gammapy.org/1.2/release-notes/v1.2.html</footnote>
information for DL3 to DL5 objects. A comprehensive and documented Metadata framework is of fundamental importance to adhere to the FAIR directives for open data [18]. The chosen Metadata structure is hierarchical and inheritance-based, allowing for flexible implementation and composition of the fundamental, "base"-blocks of Metadata (instrument, author, production...) to propagate them into more complex objects. This structure is explained more in-depth in PIG 25 <fnref n="9" />.

Another change in the latest release that focuses on open data is the introduction of a function to export part of a DataStore to a ObsCoreTable compliant object - the first step towards compliance with the International Virtual Observatory Alliance (IVOA) <fnref n="10" /> guidelines for Gammapy. An effort was also put into data quality check, with the introduction of checksum options for most read/write methods in Gammapy.

Regarding analysis changes, this version introduces parameter prior support for Bayesian fitting, as described in PIG 26 <fnref n="11" />, as well as initial support for asymmetric IRFs and new utility functions for temporal analyses.

Gammapy version 1.2 was released on February 29th, 2024 <fnref n="12" />. This release places a strong emphasis on open data management and advanced analysis capabilities. A key improvement is the introduction of the class containers for Metadata information for DL3 to DL5 objects, which is fundamental if Gammapy strives to adhere to the FAIR data principles (Findable, Accessible, Interoperable, Reusable). The hierarchical structure chosen allows for flexible organization of information like instruments, authors, and production details across different data objects through the inheritance of the fundamental metadata blocks by the more complex objects. Further details on this structure can be found in PIG 25 <fnref n="13" />. Additionally, version 1.2 introduces a function to export portions of a DataStore object into a format compliant with ObsCoreTable, paving the way for Gammapy's alignment with the IVOA guidelines. Data quality checks are also enhanced with the addition of checksum options for most read/write methods within Gammapy. On the analysis front, v1.2 introduces support for parameter priors in Bayesian fitting, as described in PIG 26¹⁴, expands capabilities with asymmetric Instrument Response Functions (IRFs), and provides new utility functions to characterize variability improving temporal analyses. The LHAASO1 catalog has been added together with an update of the 4FGL catalog from Fermi-LAT, which has been updated to include data from DR4. The release includes also many other smaller utility functions, updates, bug fixes, and improvements to code and documentation.

## 3 Roadmap to v2.0 and commitment to CTAO

The second Long-Term Support release by Gammapy, v2.0, is targeted for the spring of 2025. The development plan includes improvement on infrastructure, features, and documentation. A brief wishlist follows.

* Event type handling [16]: for IACTs and WCDs, events can be tagged according to some properties (e.g. their angular reconstruction accuracy, the number of hit sub-detectors) and be associated to specific IRFs in order to improve the analysis sensitivity.

* Unbinned spectral or 3D analysis: when gamma-ray numbers are limited, for example for transient and flaring sources, unbinned likelihood analysis provides an improvement of the analysis

* Transient source detection: improved specific time-domain algorithms to detect variable sources and characterize their variability such as Bayesian Excess Variance.

* Spectral unfolding: extraction of the intrinsic source spectrum with minimal hypothesis on its shape.

* Morphology estimation: tools to measure extension profiles and their associated significances to determine energy-dependent morphology.

* Handling of systematic effects: from systematic errors stored into IRFs or by adding systematic effects on the IRFs, one could quantify these effects on the final products.

<footnote n="9">⁹https://docs.gammapy.org/1.2/development/pigs/pig-025.html</footnote>

<footnote n="10">¹⁰https://ivoa.net/</footnote>

<footnote n="11">¹¹https://docs.gammapy.org/1.2/development/pigs/pig-026.html</footnote>

<footnote n="12">¹²https://docs.gammapy.org/1.2/release-notes/v1.2.html</footnote>

<footnote n="13">¹³https://docs.gammapy.org/1.2/development/pigs/pig-025.html</footnote>

<footnote n="14">¹⁴https://docs.gammapy.org/1.2/development/pigs/pig-026.html</footnote>
* Nuisance parameters and priors for Bayesian analysis: by adding a systematic effect of unknown amplitude (e.g. a bias in the absolute energy scale), one could estimate the impact of this effect on the estimation of the parameters assuming a prior distribution of the nuisance parameter.

* Improvements on the YAML-based high-level configurable analysis interface.

* Development of distributed computing interfaces: using tensor products such as Jax<sup>15</sup> or Pytorch<sup>16</sup> to improve efficient computing for large, joint datasets, or efficient application to clusters, and prepare for machine learning applications.

* Evolution of the data and metadata format: to comply with IVOA standards and FAIR principles the data format is expected to move forward from the current GADF to the Very High Energy Open Data Format (VODF), and Gammapy needs to handle these changes.

Some of these items, such as the priors, time-domain tools, and morphology estimators have already had an initial or preliminary implementation in the latest releases after v1.0.

Gammapy, being the base for the science analysis tools of CTAO, has been used as the standard for the simulations and the target analysis tool in the latest internal Science Data Challenge (SDC) of the CTAO consortium, which has the objective of training the consortium members to use the analysis tools to understand the data and test some CTAO tools and practices. The Gammapy team is gaining important insight and feedback from this experience to improve simulation frameworks, API, tutorials, and documentation to be ready for the open SDC which will be the first true open test of CTAO simulated data to the wider public.

# 4 Summary and conclusions

Gammapy is a public Python package designed for VHE gamma-ray astronomy. It processes high-level data from VHE facilities to extract astrophysical information. This data adheres to the standardized VHE data format, GADF. The lightweight Gammapy package is actively used by several TeV facilities and has been chosen by the CTA Observatory as the foundation for its future open-source Science Analysis Tool (SAT).

The common GADF format facilitates multi-instrument analyses by allowing joint fitting of data from various instruments. This mature software supports data from ASTRI, CTA, FACT, Fermi-LAT, HAWC, H.E.S.S., MAGIC, and VERITAS. LHAASO, SWGO, and KM3NeT facilities are also exploring Gammapy's capabilities.

With over 70 citations and established use in academic research, Gammapy's popularity is growing within the VHE community, recognized as a key research software tool. The Gammapy team recently released the first Long-Term Stable (LTS) version, v1.0, providing users with a well-maintained and stable platform for scientific analysis. This stable interface, with minor bug fixes implemented with patches usually along with the minor releases, offers a user-friendly environment for researchers.

The v1.0 LTS includes all standard and historical VHE algorithms, along with algorithms from other astrophysics domains like data cube analysis. It also enables proper statistical treatment for joint analyses of diverse high-level data.

In parallel, the development team is actively enhancing the package's capabilities, exploring features like Bayesian analysis and unbinned analysis. Several feature releases are anticipated before the next LTS, introducing new functionalities and scientific algorithms. The high-level data format is also expected to evolve as the GADF initiative has concluded. Eleven gamma-ray and neutrino experiments have launched a new initiative, Very-high-energy Open Data Format (VODF) [19], aiming to establish new standards for VHE detectors adhering to the FAIR principles and aligning with IVOA standards as much as possible. In this context, Gammapy's internal data model is being separated from the read data model with an I/O layer to handle diverse formats and versions.

Looking ahead, the Gammapy team remains committed to improving the open-source package and expanding its functionalities. As an open project, we encourage contributions to the package's development or educational activities, emphasizing proper recognition of all efforts. The authors again acknowledge the valuable contributions from all Gammapy participants and users.

<footnote n="15"><sup>15</sup>https://jax.readthedocs.io/en/latest/index.html</footnote>

<footnote n="16"><sup>16</sup>https://pytorch.org/</footnote>
References

[1] A. Donath et al., 2023, *Gammapy: A Python package for gamma-ray astronomy*, 10.1051/0004-6361/202346488, A&A.

[2] F. Acero et al., 2024, *Gammapy: Python toolbox for gamma-ray astronomy*, v1.2, 10.5281/zenodo.10726484, Zenodo.

[3] Astropy Collaboration, 2013, *Astropy: A community Python package for astronomy*, A&A, [arXiv:1307.6212].

[4] C. R. Harris, et al., 2020, *Array programming with NumPy*, Nature, [arXiv:2006.10256].

[5] J. D. Hunter, et al., 2007, *Matplotlib: A 2D Graphics Environment*, Computing In Science and Engineering, 9.

[6] P. Virtanen, et al., 2020, *SciPy 1.0: fundamental algorithms for scientific computing in Python*, Nature Methods 17, [arXiv:1907.10121].

[7] H. Dembinski, P. Ongmongkolkul, et al., 2020, *scikit-hep/iminuit*, [doi:10.5281/zenodo.3949207], Zenodo.

[8] C. Deil et al., 2016, *Open high-level data formats and software for gamma-ray astronomy*, http://dx.doi.org/10.1063/1.4969003, AIP Conference Proceedings

[9] D. C. Wells, E. W. Greisen, and R. H. Harten, 1981, *FITS - a Flexible Image Transport System*, Astronomy and Astrophysics Supplement 44.

[10] A. Albert, et al., 2022, *Validation of standardized data formats and tools for ground-level particle-based gamma-ray observatories*, A&A 667 [arXiv:2203.05937].

[11] CTAO Observatory Press release, 2021, *CTAO Adopts the Gammapy Software Package for Science Analysis*, CTAO News.

[12] French Ministry of higher education, research and Innovation, 2022, Jury prize of open science awards for open source research software, News from the French research ministry.

[13] M. de Naurois, *Very High Energy astronomy from H.E.S.S. to CTA. Opening of a new astronomical window on the non-thermal Universe*, 2012, Thesis: Habilitation Ecole Polytechnique

[14] W. Cash, *Parameter estimation in astronomy through application of the likelihood ratio.*, 1979, ApJ, 228, 939.

[15] D. Berge, S. Funk and J. Hinton, 2007, *Background Modelling in Very-High-Energy gamma-ray Astronomy*, A&A 466, [astro-ph/0610959].

[16] T. Hassan, et al., 2021, *Performance of a proposed event-type based analysis for the Cherenkov Telescope Array*, Proc. of International Cosmic Ray Conference 2021 [arXiv:2108.10135].

[17] M. Cirelli, et al. 2011, *PPPC 4 DM ID: a poor particle physicist cookbook for dark matter indirect detection*, JCAP, 051.

[18] M. D. Wilkinson, et al., 2016, *The FAIR Guiding Principles for scientific data management and stewardship*, Scientific Data 3.

[19] B. Khélifi, et al., 2023, *The Very-high-energy Open Data Format: towards a shared, open data format in very-high-energy astronomy*, Proc. of the 28th International Cosmic Ray Conference 2023.

[20] M. Barker, et al., 2022, *Introducing the FAIR Principles for research software*, Scientific Data 9, 622.