Merge branch 'gammapy:main' into fitresults

Author: Claudio Galelli

docs/_templates/custom-footer.html

@@ -0,0 +1,4 @@
+{% block extrafooter %}
+    {{super}}
+     <a href="https://gammapy.org/DataPrivacy.html">Data Privacy.</a>
+{% endblock %}

docs/conf.py

@@ -116,7 +116,7 @@ def setup(app):
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns.append("_templates")
+#exclude_patterns.append("_templates")
 exclude_patterns.append("**.ipynb_checkpoints")
 exclude_patterns.append("user-guide/model-gallery/*/*.ipynb")
 exclude_patterns.append("user-guide/model-gallery/*/*.md5")
@@ -186,6 +186,11 @@ def setup(app):
 
 # Static files to copy after template files
 html_static_path = ["_static"]
+html_css_files = ["custom.css"]
+html_js_files = ["matomo.js"]
+
+templates_path = ["_templates"]
+
 
 # The name of an image file (within the static path) to use as favicon of the
 # docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32
@@ -237,10 +242,10 @@ def setup(app):
         "json_url": "https://docs.gammapy.org/stable/switcher.json",
         "version_match": switch_version,
     },
-    "navbar_end": ["version-switcher", "theme-switcher", "navbar-icon-links"],
+    "navbar_end": ["version-switcher", "navbar-icon-links"],
     "navigation_with_keys": True,
     # footers
-    "footer_start": ["copyright"],
+    "footer_start": ["copyright","custom-footer.html"],
     "footer_center": ["last-updated"],
     "footer_end": ["sphinx-version", "theme-version"]
 }
@@ -336,13 +341,7 @@ def setup(app):
     },
 }
 
-html_static_path = ["_static"]
-html_css_files = ["custom.css"]
-html_js_files = ["matomo.js"]
-
 html_context = {
     "default_mode": "light",
 }
 
-# Add-on to insert the Matomo tracker
-templates_path = ['_templates']

docs/user-guide/astro/darkmatter/index.rst

@@ -89,11 +89,11 @@ module `DarkBit`_.  DarkBit can be used for directly computing observables and
 likelihoods, for any combination of parameter values in some underlying
 particle model.
 
-Gammapy tutorial
-================
+Using gammapy.astro.darkmatter
+------------------------------
+
+.. minigallery:: gammapy.astro.darkmatter
 
-.. minigallery:: `gammapy.astro.darkmatter.DarkMatterAnnihilationSpectralModel`
-    :add-heading:
 
 
 .. _Cirelli et al. 2011: http://iopscience.iop.org/article/10.1088/1475-7516/2011/03/051/pdf

docs/user-guide/astro/index.rst

@@ -9,14 +9,14 @@ This module contains utility functions for some astrophysical scenarios:
 * `~gammapy.astro.population` for astrophysical population models
 * `~gammapy.astro.darkmatter` for dark matter spatial and spectral models
 
-The ``gammapy.astro`` sub-package is in a prototyping phase and its scope and future
+The `gammapy.astro` sub-package is in a prototyping phase and its scope and future
 are currently being discussed. It is likely that some functionality will
 be removed or split out into a separate package at some point.
 
 Getting started
 ---------------
 
-The ``gammapy.astro`` namespace is empty. Use these import statements:
+The `gammapy.astro` namespace is empty. Use these import statements:
 
 .. testcode::
 

docs/user-guide/catalog.rst

@@ -5,17 +5,17 @@ Source catalogs
 
 `gammapy.catalog` provides convenient access to common gamma-ray source catalogs.
 
-* ``hgps`` / `SourceCatalogHGPS` - H.E.S.S. Galactic plane survey (HGPS)
-* ``gamma-cat`` /  `SourceCatalogGammaCat` - An open catalog of gamma-ray sources
-* ``3fgl`` / `SourceCatalog3FGL` - LAT 4-year point source catalog
-* ``4fgl`` / `SourceCatalog4FGL` - LAT 8-year point source catalog
-* ``2fhl`` / `SourceCatalog2FHL` - LAT second high-energy source catalog
-* ``3fhl`` / `SourceCatalog3FHL` - LAT third high-energy source catalog
-* ``2hwc`` / `SourceCatalog2HWC` - 2HWC catalog from the HAWC observatory
-* ``3hwc`` / `SourceCatalog3HWC` - 3HWC catalog from the HAWC observatory
-
-For each catalog, a `SourceCatalog` class is provided to represent the catalog table,
-and a matching `SourceCatalogObject` class to represent one catalog source and table row.
+* ``hgps`` / `~gammapy.catalog.SourceCatalogHGPS` - H.E.S.S. Galactic plane survey (HGPS)
+* ``gamma-cat`` /  `~gammapy.catalog.SourceCatalogGammaCat` - An open catalog of gamma-ray sources
+* ``3fgl`` / `~gammapy.catalog.SourceCatalog3FGL` - LAT 4-year point source catalog
+* ``4fgl`` / `~gammapy.catalog.SourceCatalog4FGL` - LAT 8-year point source catalog
+* ``2fhl`` / `~gammapy.catalog.SourceCatalog2FHL` - LAT second high-energy source catalog
+* ``3fhl`` / `~gammapy.catalog.SourceCatalog3FHL` - LAT third high-energy source catalog
+* ``2hwc`` / `~gammapy.catalog.SourceCatalog2HWC` - 2HWC catalog from the HAWC observatory
+* ``3hwc`` / `~gammapy.catalog.SourceCatalog3HWC` - 3HWC catalog from the HAWC observatory
+
+For each catalog, a `~gammapy.catalog.SourceCatalog` class is provided to represent the catalog table,
+and a matching `~gammapy.catalog.SourceCatalogObject` class to represent one catalog source and table row.
 
 The main functionality provided is methods that map catalog information to
 `~gammapy.modeling.models.SkyModel`, `~gammapy.modeling.models.SpectralModel`,
@@ -29,9 +29,9 @@ or to create initial source models for certain energy bands and sky regions.
 Using gammapy.catalog
 ---------------------
 
-.. minigallery:: gammapy.catalog.SourceCatalog3FHL
+.. minigallery:: `~gammapy.catalog.SourceCatalog3FHL`
     :add-heading:
 
 
-.. minigallery:: gammapy.catalog.SourceCatalogGammaCat
+.. minigallery:: `~gammapy.catalog.SourceCatalogGammaCat`
     :add-heading:

docs/user-guide/datasets/index.rst

@@ -8,7 +8,7 @@ Datasets (DL4)
 The `gammapy.datasets` sub-package contains classes to handle reduced
 gamma-ray data for modeling and fitting.
 
-The `Dataset` class bundles reduced data, IRFs and model to perform
+The `~gammapy.datasets.Dataset` class bundles reduced data, IRFs and model to perform
 likelihood fitting and joint-likelihood fitting.
 All datasets contain a `~gammapy.modeling.models.Models` container with one or more
 `~gammapy.modeling.models.SkyModel` objects that represent additive emission
@@ -96,7 +96,7 @@ a joint fit across multiple datasets.
 Predicted counts
 ----------------
 
-The total number of predicted counts from a `MapDataset` are computed per bin like:
+The total number of predicted counts from a `~gammapy.datasets.MapDataset` are computed per bin like:
 
 .. math::
 
@@ -174,7 +174,7 @@ Here, :math:`k` denotes a bin in reconstructed energy,
 
 For the model evaluation, an important factor that needs to be accounted for is
 that the energy threshold changes between observations.
-With the above implementation using a `~gammapy.irf.EDispersionMap`,
+With the above implementation using a `~gammapy.irf.EDispMap`,
 the `npred` is conserved,
 ie, the predicted number of counts on the stacked
 dataset is the sum expected by stacking the `npred` of the individual runs,
@@ -220,11 +220,13 @@ stack runs taken under similar conditions and then do a joint fit on the stacked
 Serialisation of datasets
 -------------------------
 
-The various `Map` objects contained in `~gammapy.datasets.MapDataset` and `~gammapy.datasets.MapDatasetOnOff` are serialised according to `GADF Sky Maps <https://gamma-astro-data-formats.readthedocs.io/en/v0.2/skymaps/index.html>`__.
+The various `~gammapy.maps.Map` objects contained in `~gammapy.datasets.MapDataset` and
+`~gammapy.datasets.MapDatasetOnOff` are serialised according to
+`GADF Sky Maps <https://gamma-astro-data-formats.readthedocs.io/en/v0.2/skymaps/index.html>`__.
 A hdulist is created with the different attributes, and each of these are written with the data
-contained in a `BinTableHDU` with a `WcsGeom` and a `BANDS HDU` specifying the non-spatial dimensions.
-Optionally, a `meta_table` is also written as an `astropy.table.Table` containing various information
-about the observations which created the dataset. While the `meta_table` can contain useful information for
+contained in a ``BinTableHDU`` with a `~gammapy.maps.WcsGeom` and a ``BANDS HDU`` specifying the non-spatial dimensions.
+Optionally, a ``meta_table`` is also written as an `astropy.table.Table` containing various information
+about the observations which created the dataset. While the ``meta_table`` can contain useful information for
 later stage analysis, it is not used anywhere internally within gammapy.
 
 `~gammapy.datasets.SpectrumDataset` follows a similar convention as for `~gammapy.datasets.MapDataset`, but uses a
@@ -233,7 +235,7 @@ later stage analysis, it is not used anywhere internally within gammapy.
 either according to the above specification, or (by default), according to the
 `OGIP standards <https://gamma-astro-data-formats.readthedocs.io/en/v0.1/ogip/index.html>`__.
 
-`~gammapy.datasets.FluxPointsDatasets` are serialised as `gammapy.estimators.FluxPoints` objects, which contains
+`~gammapy.datasets.FluxPointsDataset` are serialised as `gammapy.estimators.FluxPoints` objects, which contains
 a set of `gammapy.maps.Map` objects storing the estimated flux as function of energy, and some optional quantities like
 typically errors, upper limits, etc. It also contains a reference model,
 serialised as a `~gammapy.modeling.models.TemplateSpectralModel`.

docs/user-guide/dl3.rst

@@ -32,7 +32,7 @@ You can use the `~gammapy.data.EventList` class to load IACT gamma-ray event lis
     filename = '$GAMMAPY_DATA/hess-dl3-dr1/data/hess_dl3_dr1_obs_id_023523.fits.gz'
     events = EventList.read(filename)
 
-To load Fermi-LAT event lists, use the `~gammapy.data.EventListLAT` class:
+To load Fermi-LAT event lists, you can also use the `~gammapy.data.EventList` class:
 
 .. testcode::
 
@@ -139,7 +139,7 @@ Writing event lists and GTIs to file
 
 To write the events or GTIs separately, one can just save the underlying
 `astropy.table.Table`. To have an event file written in a correct DL3 format, it is
-necessary to utilise the  ``write`` method available for`~gammapy.data.Observation`.
+necessary to utilise the  ``write`` method available for `~gammapy.data.Observation`.
 It will write the `~gammapy.data.EventList` and their associated GTIs together in the
 same FITS file according to the format specifications. To avoid writing IRFs along the
 ``EventList`` one has to set ``include_irfs`` to ``False``. See the example below:

docs/user-guide/estimators.rst

@@ -35,7 +35,7 @@ In general the flux can be estimated using two methods:
    not re-optimising other parameters, one can estimate the significance based on the
    analytical solution by [LiMa1983]. In this case the "best fit" flux and significance
    are given by the excess over the null hypothesis. This method is also named
-   **backward folding**. This method is currently only exposed in the `ExcessMapEstimator`
+   **backward folding**. This method is currently only exposed in the `~gammapy.estimators.ExcessMapEstimator`
 
 
 Energy edges
@@ -91,7 +91,7 @@ arguments are translated into a TS difference assuming ``ts = n_sigma ** 2``.
 .. _sedtypes:
 
 SED types
-~~~~~~~~~
+^^^^^^^^^
 
 In addition to the norm values a reference spectral model and energy ranges
 are given. Using this reference spectral model the norm values can be converted
@@ -112,7 +112,7 @@ e2dnde            Differential energy flux at ``e_ref``
 The same can be applied for the error and upper limit information.
 More information can be found on the `likelihood SED type page`_.
 
-The `FluxPoints` and `FluxMaps` objects can optionally define meta
+The `~gammapy.estimators.FluxPoints` and `~gammapy.estimators.FluxMaps` objects can optionally define meta
 data with the following valid keywords:
 
 ================= =================================================
@@ -141,7 +141,7 @@ A note on negative flux and upper limit values:
 Flux maps
 ---------
 
-This how to compute flux maps with the `ExcessMapEstimator`:
+This how to compute flux maps with the `~gammapy.estimators.ExcessMapEstimator`:
 
 .. testcode::
 

docs/user-guide/hli.rst

@@ -14,7 +14,7 @@ the functionality that is available in the sub-packages to support
 standard analysis use case in a convenient way.
 
 
-Using gammapy.datasets
+Using gammapy.analysis
 ----------------------
 
 .. minigallery:: gammapy.analysis.Analysis

docs/user-guide/howto.rst

@@ -278,6 +278,18 @@ warning like so:
 
 .. accordion-footer::
 
+.. accordion-header::
+    :id: HowToAvoidNaninFp
+    :title: Avoid NaN results in Flux Point estimation
+    :link: ../tutorials/api/estimators.html#a-fully-configured-flux-points-estimation
+
+Sometimes, upper limit values may show as ``nan`` while running a `~gammapy.estimators.FluxPointsEstimator`
+or a `~gammapy.estimators.LightCurveEstimator`. This often arises because the range of the norm parameter
+being scanned over is not sufficient. Increasing this range usually solves the problem. In some cases,
+you can also consider configuring the estimator with a different `~gammapy.modeling.Fit` backend.
+
+.. accordion-footer::
+
 .. accordion-header::
     :id: HowToProgressBar
     :title: Display a progress bar

docs/user-guide/makers/index.rst

@@ -24,7 +24,7 @@ Background estimation
 Safe data range definition
 --------------------------
 
-The definition of a safe data range is done using the `SafeMaskMaker` or manually.
+The definition of a safe data range is done using the `~gammapy.makers.SafeMaskMaker` or manually.
 
 
 Using gammapy.makers

docs/user-guide/maps/index.rst

@@ -20,11 +20,11 @@ non-spatial dimensions and can represent images (2D), cubes (3D), or hypercubes
 
 
 `gammapy.maps` is organized around two data structures: *geometry* classes
-inheriting from `~Geom` and *map* classes inheriting from `~Map`. A geometry
-defines the map boundaries, pixelization scheme, and provides methods for
-converting to/from map and pixel coordinates. A map owns a `~Geom` instance
+inheriting from `~gammapy.maps.Geom` and *map* classes inheriting from `~gammapy.maps.Map`. A geometry
+defines the map boundaries, pixelisation scheme, and provides methods for
+converting to/from map and pixel coordinates. A map owns a `~gammapy.maps.Geom` instance
 as well as a data array containing map values. Where possible it is recommended
-to use the abstract `~Map` interface for accessing or updating the contents of a
+to use the abstract `~gammapy.maps.Map` interface for accessing or updating the contents of a
 map as this allows algorithms to be used interchangeably with different map
 representations. The following reviews methods of the abstract map interface.
 
@@ -33,11 +33,11 @@ Getting started with maps
 -------------------------
 
 All map objects have an abstract interface provided through the methods of the
-`~Map`. These methods can be used for accessing and manipulating the contents of
+`~gammapy.maps.Map`. These methods can be used for accessing and manipulating the contents of
 a map without reference to the underlying data representation (e.g. whether a
-map uses WCS or HEALPix pixelization). For applications which do depend on the
+map uses WCS or HEALPix pixelisation). For applications which do depend on the
 specific representation one can also work directly with the classes derived from
-`~Map`. In the following we review some of the basic methods for working with
+`~gammapy.maps.Map`. In the following we review some of the basic methods for working with
 map objects, more details are given in the :doc:`/tutorials/api/maps`
 tutorial.
 
@@ -47,20 +47,20 @@ Accessor methods
 ----------------
 
 All map objects have a set of accessor methods provided through the abstract
-`~Map` class. These methods can be used to access or update the contents of the
+`~gammapy.maps.Map` class. These methods can be used to access or update the contents of the
 map irrespective of its underlying representation. Four types of accessor
 methods are provided:
 
 * ``get`` : Return the value of the map at the pixel containing the
-  given coordinate (`~Map.get_by_idx`, `~Map.get_by_pix`, `~Map.get_by_coord`).
+  given coordinate (`~gammapy.maps.Map.get_by_idx`, `~gammapy.maps.Map.get_by_pix`, `~gammapy.maps.Map.get_by_coord`).
 * ``interp`` : Interpolate or extrapolate the value of the map at an arbitrary
   coordinate.
 * ``set`` : Set the value of the map at the pixel containing the
-  given coordinate (`~Map.set_by_idx`, `~Map.set_by_pix`, `~Map.set_by_coord`).
+  given coordinate (`~gammapy.maps.Map.set_by_idx`, `~gammapy.maps.Map.set_by_pix`, `~gammapy.maps.Map.set_by_coord`).
 * ``fill`` : Increment the value of the map at the pixel containing
   the given coordinate with a unit weight or the value in the optional
-  ``weights`` argument (`~Map.fill_by_idx`, `~Map.fill_by_pix`,
-  `~Map.fill_by_coord`).
+  ``weights`` argument (`~gammapy.maps.Map.fill_by_idx`, `~gammapy.maps.Map.fill_by_pix`,
+  `~gammapy.maps.Map.fill_by_coord`).
 
 Accessor methods accept as their first argument a coordinate tuple containing
 scalars, lists, or numpy arrays with one tuple element for each dimension of the
@@ -84,7 +84,7 @@ coordinates can be expressed in one of three coordinate systems:
   array for each non-spatial dimension.
 
 The coordinate system accepted by a given accessor method can be inferred from
-the suffix of the method name (e.g. `~Map.get_by_idx`).  The following
+the suffix of the method name (e.g. `~gammapy.maps.Map.get_by_idx`).  The following
 demonstrates how one can access the same pixels of a WCS map using each of the
 three coordinate systems:
 
@@ -141,7 +141,7 @@ following demonstrates how one can set pixel values:
 Interface with MapCoord and SkyCoord
 ------------------------------------
 
-The ``coord`` accessor methods accept `dict`, `~gammapy.maps.MapCoord`, and
+The ``coord`` accessor methods accept ``dict``, `~gammapy.maps.MapCoord`, and
 `~astropy.coordinates.SkyCoord` arguments in addition to the standard `tuple` of
 `~numpy.ndarray` argument.  When using a `tuple` argument a
 `~astropy.coordinates.SkyCoord` can be used instead of longitude and latitude
@@ -166,7 +166,7 @@ transformed to match the coordinate system of the map.
     m.set_by_coord((skycoord, energy), [0.5, 1.5])
     m.get_by_coord((skycoord, energy))
 
-A `~gammapy.maps.MapCoord` or `dict` argument can be used to interact with a map object
+A `~gammapy.maps.MapCoord` or ``dict`` argument can be used to interact with a map object
 without reference to the axis ordering of the map geometry:
 
 .. testcode::
@@ -188,9 +188,9 @@ MapCoord
 
 `~gammapy.maps.MapCoord` is an N-dimensional coordinate object that stores both spatial and
 non-spatial coordinates and is accepted by all ``coord`` methods. A `~gammapy.maps.MapCoord`
-can be created with or without explicitly named axes with `MapCoord.create`.
+can be created with or without explicitly named axes with `~gammapy.maps.MapCoord.create`.
 Axes of a `~gammapy.maps.MapCoord` can be accessed by index, name, or attribute.  A `~gammapy.maps.MapCoord`
-without explicit axis names can be created by calling `MapCoord.create` with a
+without explicit axis names can be created by calling `~gammapy.maps.MapCoord.create` with a
 `tuple` argument:
 
 .. testcode::
@@ -231,8 +231,8 @@ latitude.  Non-spatial axes are assigned a default name ``axis{I}`` where
 ``{I}`` is the index of the non-spatial dimension. `~gammapy.maps.MapCoord` objects created
 without named axes must have the same axis ordering as the map geometry.
 
-A `~gammapy.maps.MapCoord` with named axes can be created by calling `MapCoord.create`
-with a `dict`:
+A `~gammapy.maps.MapCoord` with named axes can be created by calling `~gammapy.maps.MapCoord.create`
+with a ``dict``:
 
 .. testcode::
 

docs/user-guide/scripts/index.rst

@@ -150,7 +150,7 @@ Write your own CLI
 This section explains how to write your own command line interface (CLI).
 
 We will focus on the command line aspect, and use a very simple example where we
-just call `gammapy.stats.CashCountsStatistics.sqrt_ts`.
+just call `gammapy.stats.CashCountsStatistic.sqrt_ts`.
 
 From the interactive Python or IPython prompt or from a Jupyter notebook you
 just import the functionality you need and call it, like this: