Reorganise IRF description in User Manual

Jürgen Knödlseder
1 parent 2560f44f
Showing 9 changed files with 72 additions and 58 deletions
doc/source/users/user_manual/index.rst
doc/source/users/user_manual/irf.rst
doc/source/users/user_manual/response.rst → doc/source/users/user_manual/irf_cta.rst
doc/source/users/user_manual/irf-aeff.png → doc/source/users/user_manual/irf_cta_aeff.png
doc/source/users/user_manual/irf-file.png → doc/source/users/user_manual/irf_cta_file.png
doc/source/users/user_manual/irf_intro.rst
doc/source/users/user_manual/models_concept.rst
doc/source/users/user_manual/models_implementation.rst
doc/source/users/user_manual/models_spatial_bgd.rst
@@ -10,6 +10,6 @@ User Manual
    data
    likelihood
    models
-   response
+   irf
    classical
    observations
+.. _um_irf:
+
+Instrument Response Functions
+-----------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   irf_intro
+   irf_cta
-.. _um_response:
-
-Instrument Response Functions
------------------------------
-
-What are instrument response functions?
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The instrument response functions provide a mathematical description that
-links the reconstructed photon arrival direction :math:`p'`, energy :math:`E'`
-and trigger time :math:`t'` of an event to the true incident direction
-:math:`p`, energy :math:`E` and time :math:`t` of a photon. The following
-figure illustrates this relationship:
-
-.. figure:: irfs.jpg
-   :width: 70%
-
-:math:`I(p,E,t)` is the gamma-ray intensity arriving at Earth as a function of
-direction :math:`p`, energy :math:`E` and time :math:`t`. :math:`e(p',E',t')`
-is the expected event rate as function of the reconstructed direction
-:math:`p'`, energy :math:`E'` and trigger time :math:`t'`. The expected event
-rate is obtained by integrating the product of the instrumental response
-function :math:`R(p',E',t'|p,E,t)` and the emitted intensity :math:`I(p,E,t)`
-over the direction, energy and time.
-
+.. _um_irf_cta:
  
 CTA response functions
-~~~~~~~~~~~~~~~~~~~~~~
+----------------------
+
+Factorisation
+~~~~~~~~~~~~~
  
 The instrument response functions for CTA (as well as the other IACTs such as
 H.E.S.S., VERITAS and MAGIC) are factorised into
@@ -50,6 +29,36 @@ and
 .. math::
    \int E_{\rm disp}(E' | p, E, t) dE' = 1
  
+
+Format
+~~~~~~
+
+Each response is stored in a single FITS file, and each component of the
+response factorisation is stored in a binary table of that FITS file.
+In addition, the response files contain an additional table that describes the
+background rate as function of energy and position in the field of view.
+An example of a CTA response file is shown below:
+
+.. figure:: irf_cta_file.png
+   :width: 100%
+
+Each table in the response file is in a standardised format that is the one
+that is also used for the Fermi/LAT telescope. As an example, the effective
+area component of the response file is shown below. Response information is
+stored in a n-dimensional cube, and each axis of this cube is described by the
+lower and upper edges of the axis bins. In this example the effective area is
+stored as a 2D matrix with the first axis being energy and the second axis
+being offaxis angle. Effective area information is stored for true
+(``EFFAREA``) and reconstructed (``EFFAREA_RECO``) energy. Vector columns are
+used to store all information.
+
+.. figure:: irf_cta_aeff.png
+   :width: 100%
+
+
+Getting CTA IRFs
+~~~~~~~~~~~~~~~~
+
 ctools are shipped with the CTA ``prod2`` response functions for the northern
 and southern arrays, and variants are available that have been optimised for
 exposure times of 0.5 hours, 5 hours and 50 hours.
@@ -82,32 +91,6 @@ In total, the following six instrument response functions are available:
    To use the prod3b-v1 response functions, specify ``prod3b-v1`` if a tool
    or script queries for the calibration database.
  
-Each response is stored in a single FITS file, and each component of
-the response factorisation is stored in a binary table of that FITS
-file.
-In addition, the response files contain an additional table that
-describes the background rate as function of energy and position in
-the field of view.
-An example of a CTA response file is shown below:
-
-.. figure:: irf-file.png
-   :width: 100%
-
-Each table in the response file is in a standardised format that is
-the one that is also used for the Fermi/LAT telescope.
-As an example, the effective area component of the response file
-is shown below.
-Response information is stored in a n-dimensional cube, and each axis
-of this cube is described by the lower and upper edges of the axis bins.
-In this example the effective area is stored as a 2D matrix with the
-first axis being energy and the second axis being offaxis angle.
-Effective area information is stored for true (``EFFAREA``) and
-reconstructed (``EFFAREA_RECO``) energy.
-Vector columns are used to store all information.
-
-.. figure:: irf-aeff.png
-   :width: 100%
-
  
 Specifying CTA response functions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. _um_irf_intro:
+
+What are instrument response functions?
+---------------------------------------
+
+The instrument response functions provide a mathematical description that
+links the reconstructed photon arrival direction :math:`p'`, energy :math:`E'`
+and trigger time :math:`t'` of an event to the true incident direction
+:math:`p`, energy :math:`E` and time :math:`t` of a photon. The following
+figure illustrates this relationship:
+
+.. figure:: irfs.jpg
+   :width: 70%
+
+:math:`I(p,E,t)` is the gamma-ray intensity arriving at Earth as a function of
+direction :math:`p`, energy :math:`E` and time :math:`t`. :math:`e(p',E',t')`
+is the expected event rate as function of the reconstructed direction
+:math:`p'`, energy :math:`E'` and trigger time :math:`t'`. The expected event
+rate is obtained by integrating the product of the instrumental response
+function :math:`R(p',E',t'|p,E,t)` and the emitted intensity :math:`I(p,E,t)`
+over the direction, energy and time.
@@ -9,7 +9,7 @@ Generally, the measured events can be separated into two distinct classes:
 events being attributed to gamma rays of celestial origin (the "source" 
 events) or events being attributed to any other kind of trigger (the 
 "background" events).
-In the first case, the :ref:`Instrument Response Functions (IRFs) <um_response>`
+In the first case, the :ref:`Instrument Response Functions (IRFs) <um_irf>`
 describe how an incident gamma-ray converts into a measured event.
 In the second case there is often no general prescription, and the 
 distribution of background events is commonly modeled directly in the data 
@@ -28,7 +28,7 @@ Model components are generally parametric, and model parameters can be
 adjusted through a maximum likelihood procedure to find the set of 
 parameters that represent best the measured data.
 Model components representing celestial sources are convolved with the 
-:ref:`IRFs <um_response>` to predict the expected number of source events in
+:ref:`IRFs <um_irf>` to predict the expected number of source events in
 the data.
 Background model components will be directly expressed as expected number 
-of background events without any :ref:`IRF <um_response>` convolution.
+of background events without any :ref:`IRF <um_irf>` convolution.
@@ -19,7 +19,7 @@ a point source at the location of the Crab nebula with a power law spectral
 shape that is constant in time.
 The background component ``Background`` is modelled using the template that is
 provided with the
-:ref:`Instrument Response Functions (IRFs) <um_response>`
+:ref:`Instrument Response Functions (IRFs) <um_irf>`
 and that is multiplied by a spectral power law function.
  
 .. code-block:: xml
@@ -246,7 +246,7 @@ Radial acceptance background
 CTA IRF background
 ^^^^^^^^^^^^^^^^^^
  
-  The :ref:`Instrument Response Functions (IRFs) <um_response>` contain a template
+  The :ref:`Instrument Response Functions (IRFs) <um_irf>` contain a template
   that predicts the background rate as function of position in the field of view
   and measured energy in units of
   :math:`{\rm events} \, {\rm s}^{-1} {\rm MeV}^{-1} {\rm sr}^{-1}`. This template