Merge branch 'main' into sf

Author: Claudio Galelli

.github/workflows/ci.yml

@@ -9,7 +9,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: psf/black@stable
         with:
-          version: "22.6.0"
+          version: "24.2.0"
   ci-runs:
     name: ${{ matrix.os }}, ${{ matrix.tox_env }}
     runs-on: ${{ matrix.os }}
@@ -44,6 +44,11 @@ jobs:
             tox_env: 'py311-test-alldeps_noray'
             gammapy_data_path: /home/runner/work/gammapy/gammapy/gammapy-datasets/dev
             allowed_fail: false
+          - os: ubuntu-latest
+            python: '3.12'
+            tox_env: 'py312-test-alldeps_noray'
+            gammapy_data_path: /home/runner/work/gammapy/gammapy/gammapy-datasets/dev
+            allowed_fail: false
           - os: ubuntu-latest
             python: '3.10'
             tox_env: 'py310-test'

.pre-commit-config.yaml

@@ -6,7 +6,7 @@ repos:
       - id: isort
         args: ["--profile", "black", "--filter-files"]
   - repo: https://github.com/psf/black
-    rev: 22.6.0
+    rev: 24.2.0
     hooks:
       - id: black
   # https://black.readthedocs.io/en/stable/guides/using_black_with_other_tools.html?highlight=other%20tools#flake8
@@ -15,4 +15,4 @@ repos:
     hooks:
       - id: flake8
         exclude: examples
-        args: ["--count", "--max-line-length=100", "--extend-ignore=E203,E712,W503"]
+        args: ["--count", "--max-line-length=100", "--extend-ignore=E203,E712,W503"]

CITATION.cff

@@ -8,12 +8,12 @@ abstract: 'Gammapy analyzes gamma-ray data and creates sky images, spectra and l
 type: software
 message: "If you use this software, please cite it using the metadata from this file."
 url: "https://gammapy.org/"
-date-released: 2024-02-19
+date-released: 2024-02-29
 keywords:
 - Astronomy
 - "Gamma-rays"
 - "Data analysis"
-version: v1.2rc1
+version: v1.2
 repository-code: "https://github.com/gammapy/gammapy"
 license: BSD-3-Clause
 contact:

codemeta.json

@@ -253,7 +253,7 @@
         }
     ],
     "codeRepository": "https://github.com/gammapy/gammapy",
-    "datePublished": "2024-02-19",
+    "datePublished": "2024-02-29",
     "description": "Gammapy analyzes gamma-ray data and creates sky images, spectra and lightcurves, from event lists and instrument response information; it can also determine the position, morphology and spectra of gamma-ray sources. It is used to analyze data from H.E.S.S., Fermi-LAT, HAWC, and the Cherenkov Telescope Array (CTA).",
     "identifier": "https://doi.org/10.5281/zenodo.4701488",
     "keywords": [
@@ -264,7 +264,7 @@
     "license": "https://spdx.org/licenses/BSD-3-Clause",
     "name": "Gammapy: Python toolbox for gamma-ray astronomy",
     "url": "https://gammapy.org/",
-    "softwareVersion": "v1.2rc1",
+    "softwareVersion": "v1.2",
     "maintainer": {
         "@id": "https://orcid.org/0000-0003-4568-7005",
         "@type": "Person",
@@ -284,7 +284,7 @@
     "softwareRequirements": [
         "numpy>=1.21,<2.0",
         "scipy>=1.5,!=1.10",
-        "astropy>=5.0",
+        "astropy>=5.0,<6.1",
         "regions>=0.5.0",
         "pyyaml>=5.3",
         "click>=7.0",

docs/conf.py

@@ -43,6 +43,7 @@
 
 # flake8: noqa
 
+
 # Add our custom directives to Sphinx
 def setup(app):
     """

docs/development/doc_howto.rst

@@ -111,6 +111,32 @@ the code as well as the output value produced.
             (10., 20.)>
         radius: 3.0 deg
 
+To allow the code block to be placed correctly over multiple lines utilise the "...":
+
+.. code-block:: text
+
+        Examples
+        --------
+        >>> from gammapy.maps import WcsGeom, MapAxis
+        >>> energy_axis_true = MapAxis.from_energy_bounds(
+        ...            0.5, 20, 10, unit="TeV", name="energy_true"
+        ...        )
+
+
+For a larger code block it is also possible to utilise the following syntax.
+
+.. code-block:: text
+
+        Examples
+        --------
+        ::
+
+            from gammapy.maps import MapAxis
+            from gammapy.irf import EnergyDispersion2D
+            filename = '$GAMMAPY_DATA/hess-dl3-dr1/data/hess_dl3_dr1_obs_id_020136.fits.gz'
+            edisp2d = EnergyDispersion2D.read(filename, hdu="EDISP")
+
+
 In order to perform tests of these snippets of code present in the docstrings of the Python files, you may run the
 following command.
 

docs/getting-started/environments.rst

@@ -8,12 +8,36 @@ We recommend to create an isolated virtual environment for each version of Gamma
 control over additional packages that you may use in your analysis. This will also help you on improving
 reproducibility within the user community.
 
+
 Conda Environments
 ------------------
-For convenience we also provide, for each stable release of Gammapy,
-a YAML file that allows you to easily create a specific conda execution environment.
-See  :ref:`start installation quick instructions <quickstart-setup>` section. To create a new custom
-environment for your analysis with conda you can use:
+
+For convenience we provide, for each stable release of Gammapy,
+a pre-defined conda environment file, so you can
+get additional useful packages together with Gammapy in a virtual isolated
+environment. First install `Miniconda <https://docs.conda.io/en/latest/miniconda.html>`__
+and then just execute the following commands in the terminal:
+
+.. substitution-code-block:: bash
+
+    $ curl -O https://gammapy.org/download/install/gammapy-|release|-environment.yml
+    $ conda env create -f gammapy-|release|-environment.yml
+
+.. note::
+
+    On Windows, you have to open up the conda environment file and delete the
+    lines with ``sherpa`` and ``healpy``. Those are optional dependencies that
+    currently aren't available on Windows.
+
+Once the environment has been created you can activate it using:
+
+.. substitution-code-block:: bash
+
+    $ conda activate gammapy-|release|
+
+
+
+To create a new custom environment for your analysis with conda you can use:
 
 .. code-block:: bash
 

docs/getting-started/index.rst

@@ -17,13 +17,16 @@ Getting started
 Installation
 ------------
 
+There are various ways for users to install Gammapy. **We recommend setting up a virtual
+environment using either conda or mamba.** Here are two methods to quickly install Gammapy.
+
 .. panels::
     :column: col-lg-6 col-md-6 col-sm-12 col-xs-12 p-3
 
     Working with conda?
     ^^^^^^^^^^^^^^^^^^^
 
-    Gammapy can be installed with `Anaconda <https://docs.continuum.io/anaconda/>`__ or Miniconda:
+    Gammapy can be installed with `Anaconda <https://docs.continuum.io/anaconda/>`__:
 
     .. code-block:: bash
 

docs/getting-started/install.rst

@@ -5,12 +5,12 @@
 Installation
 ============
 
-There are many ways to install Python and Gammapy as a user. On this page we list the most common ones.
-In general **we recommend to use virtual environments** when using Gammapy. This ways you have full
-control over additional packages that you may use in your analysis and you work with
-well defined computing environments, that you can share and allow **reproducibility of your
-scientific analysis results**. If you want to learn about using virtual environments see :ref:`virtual-envs`.
-You can also :ref:`install Gammapy for development <dev_setup>`.
+There are numerous ways to install Python and Gammapy as a user. On this page, we list the most common ones.
+In general, **we recommend using** :ref:`virtual environments <virtual-envs>` when using Gammapy. This
+way you have complete control over the additional packages that you may use in your analysis and you work with
+well defined computing environments. This enables you to easily share your work and ensure **reproducibility of your
+scientific analysis results**. You can also :ref:`install Gammapy for development <dev_setup>`.
+
 
 .. _anaconda:
 
@@ -35,28 +35,28 @@ To install a specific version of Gammapy just execute:
 
 .. code-block:: bash
 
-    $ conda install -c conda-forge gammapy=0.19
+    $ conda install -c conda-forge gammapy=1.0
 
-If you encountered any issues you can check the :ref:`troubleshoot` guide.
+If you encounter any issues you can check the :ref:`troubleshoot` guide.
 
 Using Mamba
 -----------
 Alternatively, you can use `Mamba <https://mamba.readthedocs.io/>`__ for the installation.
-Mamba is an alternative package manager that support most of conda’s command but offers higher installation
+Mamba is an alternative package manager that supports most of conda’s commands but offers higher installation
 speed and more reliable environment solutions. To install ``mamba`` in the Conda base environment:
 
 .. code-block:: bash
 
     $ conda install mamba -n base -c conda-forge
 
-then:
+Then install Gammapy through:
 
 .. code-block:: bash
 
     $ mamba install gammapy
 
-Mamba supports of the commands that are available for conda. So updating and installing specific versions
-works the same way as above except for replacing the ``conda`` with the ``mamba`` command.
+Mamba supports the same commands available in conda. Therefore, updating and installing specific versions
+follows the same process as above, just simply replace the ``conda`` command with the ``mamba`` command.
 
 .. _install-pip:
 
@@ -71,13 +71,6 @@ using `pip`_:
    $ python -m pip install gammapy
 
 This will install Gammapy with the required dependencies only.
-
-.. note::
-
-    For Apple silicon M1 (`arm64`) architectures you also have to open the
-    environment file and delete the `sherpa` entry, as currently there are
-    no conda packages available. However you can later install `sherpa`
-    in the environment using `python -m pip install sherpa`.
 
 To install Gammapy with all optional dependencies, you can specify:
 
@@ -86,33 +79,33 @@ To install Gammapy with all optional dependencies, you can specify:
    $ python -m pip install gammapy[all]
 
 
-To update an existing installation you can use:
+To update an existing installation use:
 
 .. code-block:: bash
 
    $ python -m pip install gammapy --upgrade
 
-To install a specific version of Gammapy you can use:
+To install a specific version of Gammapy use:
 
 .. code-block:: bash
 
-    $ python -m pip install gammapy==0.19
+    $ python -m pip install gammapy==1.0
 
-To install the current Gammapy **development** version using `pip`_ you can use:
+To install the current Gammapy **development** version with `pip`_ use:
 
 .. code-block:: bash
 
    $ python -m pip install git+https://github.com/gammapy/gammapy.git#egg=gammapy
 
-Or like this, if you want to study or edit the code locally:
+If you want to study or edit the code locally, use the following:
 
 .. code-block:: bash
 
    $ git clone https://github.com/gammapy/gammapy.git
    $ cd gammapy
    $ python -m pip install .
 
-If you encountered any issues you can check the :ref:`troubleshoot` guide.
+If you encounter any issues you can check the :ref:`troubleshoot` guide.
 
 .. _install-other:
 
@@ -138,8 +131,8 @@ Example:
         python3-pip python3-matplotlib \
         ipython3-notebook python3-gammapy
 
-    $ python3 -m pip install antigravity
+    $ python3 -m pip install gammapy
 
 Note that the Linux package managers typically have release cycles of 6 months,
 or yearly or longer, meaning that you'll typically  get an older version of
-Gammapy. But you can always get a recent version via `pip` or `conda` (see above).
+Gammapy. However, you can always get the recent version via `pip` or `conda` (see above).

docs/getting-started/quickstart.rst

@@ -1,13 +1,10 @@
 .. _quickstart-setup:
 
-Quickstart Setup
-----------------
+Recommended Setup
+-----------------
 
-The best way to get started and learn Gammapy are the :ref:`tutorials`. For
-convenience we provide a pre-defined conda environment file, so you can
-get additional useful packages together with Gammapy in a virtual isolated
-environment. First install `Miniconda <https://docs.conda.io/en/latest/miniconda.html>`__
-and then just execute the following commands in the terminal:
+We recommend using :ref:`virtual environments <virtual-envs>`, to do so
+execute the following commands in the terminal:
 
 .. substitution-code-block:: bash
 
@@ -22,23 +19,21 @@ and then just execute the following commands in the terminal:
 
 .. note::
 
-    For Apple silicon M1 (`arm64`) architectures you also have to open the
-    environment file and delete the `sherpa` entry, as currently there are
-    no conda packages available. However you can later install `sherpa`
+    For gammapy versions **prior to v1.2**, if you're using
+    Apple silicon M1 (`arm64`) architectures you have to open the
+    environment file and delete the `sherpa` entry. Currently there are
+    no conda packages available. You can then install `sherpa`
     in the environment using `python -m pip install sherpa`.
 
-Once the environment has been created you can activate it using:
 
-.. substitution-code-block:: bash
-
-    $ conda activate gammapy-|release|
-
-You can now proceed to download the Gammapy tutorial notebooks and the example
+The best way to get started and learn Gammapy are the :ref:`tutorials`.
+You can download the Gammapy tutorial notebooks and the example
 datasets. The total size to download is ~180 MB. Select the location where you
 want to install the datasets and proceed with the following commands:
 
 .. substitution-code-block:: bash
 
+    $ conda activate gammapy-|release|
     $ gammapy download notebooks
     $ gammapy download datasets
     $ conda env config vars set GAMMAPY_DATA=$PWD/gammapy-datasets/|release|
@@ -60,7 +55,7 @@ variable directly in your shell with:
     else instead of ``export``, and also the profile setup file will be different.
     On Windows, you should set the ``GAMMAPY_DATA`` environment variable in the
     "Environment Variables" settings dialog, as explained e.g.
-    `here <https://docs.python.org/3/using/windows.html#excursus-setting-environment-variables>`__
+    `here <https://docs.python.org/3/using/windows.html#excursus-setting-environment-variables>`__.
 
 Finally start a notebook server by executing:
 
@@ -69,5 +64,5 @@ Finally start a notebook server by executing:
     $ cd notebooks
     $ jupyter notebook
 
-If you are new to conda, Python and Jupyter, maybe also read the :ref:`using-gammapy` guide.
-If you encountered any issues you can check the :ref:`troubleshoot` guide.
+If you are new to conda, Python and Jupyter, it is recommended to also read the :ref:`using-gammapy` guide.
+If you encounter any issues you can check the :ref:`troubleshoot` guide.