Merge pull request #3281 from adonath/workflow_overview

Refactor and shorten overview docs page
gammapy · Mar 23, 2021 · 3f79b2c · 3f79b2c
2 parents 9543f82 + b913a31
commit 3f79b2c
Show file tree

Hide file tree

Showing 12 changed files with 141 additions and 232 deletions.
diff --git a/docs/_static/data-flow-gammapy.png b/docs/_static/data-flow-gammapy.png
diff --git a/docs/conf.py b/docs/conf.py
@@ -24,6 +24,7 @@
 
 plot_html_show_source_link = False
 
+numfig = False
 
 # -- General configuration ----------------------------------------------------
 

diff --git a/docs/data/index.rst b/docs/data/index.rst
@@ -10,10 +10,24 @@ data - DL3 data access and observations
 
 Introduction
 ============
+IACT data is typically structured in "observations", which define a given
+time interval during with the instrument response is considered stable.
+
 
 `gammapy.data` currently contains the `~gammapy.data.EventList` class,
 as well as classes for IACT data and observation handling.
 
+
+The main classes in Gammapy to access the DL3 data library are the
+`~gammapy.data.DataStore` and `~gammapy.data.Observation`.
+They are used to store and retrieve dynamically the datasets
+relevant to any observation (event list in the form of an `~gammapy.data.EventList`,
+IRFs see :ref:`irf` and other relevant informations).
+
+Once some observation selection has been selected, the user can build a list of observations:
+a `~gammapy.data.Observations` object, which will be used for the data reduction process.
+
+
 Getting Started
 ===============
 

diff --git a/docs/datasets/index.rst b/docs/datasets/index.rst
@@ -48,6 +48,11 @@ the ``wstat`` fit statistic. The `~gammapy.datasets.FluxPointsDataset` contains
 `~gammapy.estimatorsFluxPoints` and a spectral model, the fit statistic used is
 ``chi2``.
 
+Note that in Gammapy, 2D image analyses are done with 3D cubes with a single
+energy bin, e.g. for modeling and fitting,
+see the `2D map analysis tutorial <./tutorials/image_analysis.html>`__.
+
+
 Getting Started
 ===============
 

diff --git a/docs/getting-started.rst b/docs/getting-started.rst
@@ -61,6 +61,13 @@ lists the common commands to install packages and work with environments.
 
 Use Gammapy
 -----------
+To use Gammapy you need a basic knowledge of Python, Numpy, Astropy, as well as
+matplotlib for plotting. Many standard gamma-ray analyses can be done with few
+lines of configuration and code, so you can get pretty far by copy and pasting
+and adapting the working examples from the Gammapy documentation. But
+eventually, if you want to script more complex analyses, or inspect analysis
+results or intermediate analysis products, you need to acquire a basic to
+intermediate Python skill level.
 
 Python
 ++++++

diff --git a/docs/index.rst b/docs/index.rst
@@ -9,13 +9,18 @@ Gammapy
 -------
 
 Gammapy is a community-developed, open-source Python package for gamma-ray
-astronomy. It is a prototype for the `CTA`_ science tools. This webpage contains
-the Gammapy documentation. You may also check out the `Gammapy webpage <https://gammapy.org>`_
+astronomy built on Numpy, Scipy and Astropy. It is a prototype for the `CTA`_ science tools
+and can also be used to analyse data from existing imaging atmospheric Cherenkov telescopes
+(IACTs), such as `H.E.S.S.`_, `MAGIC`_ and `VERITAS`_. It also provides some support
+for `Fermi-LAT`_ and `HAWC`_ data analysis.
+
+This webpage contains the Gammapy documentation. You may also check out the `Gammapy webpage <https://gammapy.org>`_
 where you may find more information about Gammapy, including the
 `list of releases <https://gammapy.org/news.html#releases>`_ and contact information if you
 have any questions, want to report and issue or request a feature, or need help with anything
 Gammapy-related.
 
+
 .. _gammapy_intro:
 .. toctree::
     :caption: Getting Started

diff --git a/docs/irf/index.rst b/docs/irf/index.rst
@@ -8,7 +8,11 @@ irf - Instrument response functions
 
 Introduction
 ============
-For a definition of the response function you are invited to read 
+Typically the IRFs are stored in the form of multidimensional tables giving
+the response functions such as the distribution of gamma-like events or the
+probability density functions of the reconstructed energy and position.
+
+For a more detailed definition of the response function you are invited to read
 :ref:`irf-theory`.
 
 `gammapy.irf` handles the following instrument response functions (IRFs):

diff --git a/docs/irf/plot_edisp_kernel_param.py b/docs/irf/plot_edisp_kernel_param.py
@@ -1,10 +1,19 @@
 """Plot an energy dispersion using a gaussian parametrisation"""
-import numpy as np
-import astropy.units as u
 import matplotlib.pyplot as plt
 from gammapy.irf import EDispKernel
+from gammapy.maps import MapAxis
 
-energy = np.logspace(0, 1, 101) * u.TeV
-edisp = EDispKernel.from_gauss(energy=energy, energy_true=energy, sigma=0.1, bias=0,)
+energy_axis = MapAxis.from_energy_bounds("1 TeV", "10 TeV", nbin=10)
+energy_axis_true = MapAxis.from_energy_bounds(
+    "0.5 TeV", "30 TeV", nbin=10, per_decade=True, name="energy_true"
+)
+
+
+edisp = EDispKernel.from_gauss(
+    energy_axis=energy_axis,
+    energy_axis_true=energy_axis_true,
+    sigma=0.1,
+    bias=0
+)
 edisp.peek()
 plt.show()
diff --git a/docs/makers/index.rst b/docs/makers/index.rst
@@ -278,8 +278,6 @@ offset-cut later, you can also choose a larger width of the cutout
 than `2 * offset_max`.
 
 
-
-
 Using `gammapy.makers`
 ======================