diff --git a/doc/source/users/user_manual/index.rst b/doc/source/users/user_manual/index.rst index 97aee49..5655219 100755 --- a/doc/source/users/user_manual/index.rst +++ b/doc/source/users/user_manual/index.rst @@ -10,6 +10,6 @@ User Manual data likelihood models - response + irf classical observations diff --git a/doc/source/users/user_manual/irf.rst b/doc/source/users/user_manual/irf.rst new file mode 100755 index 0000000..787994b --- /dev/null +++ b/doc/source/users/user_manual/irf.rst @@ -0,0 +1,10 @@ +.. _um_irf: + +Instrument Response Functions +----------------------------- + +.. toctree:: + :maxdepth: 1 + + irf_intro + irf_cta diff --git a/doc/source/users/user_manual/response.rst b/doc/source/users/user_manual/irf_cta.rst index 65e83a5..1725b85 100755 --- a/doc/source/users/user_manual/response.rst +++ b/doc/source/users/user_manual/irf_cta.rst @@ -1,31 +1,10 @@ -.. _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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/doc/source/users/user_manual/irf-aeff.png b/doc/source/users/user_manual/irf_cta_aeff.png index eabbe69..eabbe69 100755 --- a/doc/source/users/user_manual/irf-aeff.png +++ b/doc/source/users/user_manual/irf_cta_aeff.png diff --git a/doc/source/users/user_manual/irf-file.png b/doc/source/users/user_manual/irf_cta_file.png index 31f1599..31f1599 100755 --- a/doc/source/users/user_manual/irf-file.png +++ b/doc/source/users/user_manual/irf_cta_file.png diff --git a/doc/source/users/user_manual/irf_intro.rst b/doc/source/users/user_manual/irf_intro.rst new file mode 100755 index 0000000..21618d3 --- /dev/null +++ b/doc/source/users/user_manual/irf_intro.rst @@ -0,0 +1,21 @@ +.. _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. diff --git a/doc/source/users/user_manual/models_concept.rst b/doc/source/users/user_manual/models_concept.rst index 2ade405..47590e9 100644 --- a/doc/source/users/user_manual/models_concept.rst +++ b/doc/source/users/user_manual/models_concept.rst @@ -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) ` +In the first case, the :ref:`Instrument Response Functions (IRFs) ` 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 ` to predict the expected number of source events in +:ref:`IRFs ` 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 ` convolution. +of background events without any :ref:`IRF ` convolution. diff --git a/doc/source/users/user_manual/models_implementation.rst b/doc/source/users/user_manual/models_implementation.rst index 121e420..a53241a 100644 --- a/doc/source/users/user_manual/models_implementation.rst +++ b/doc/source/users/user_manual/models_implementation.rst @@ -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) ` +:ref:`Instrument Response Functions (IRFs) ` and that is multiplied by a spectral power law function. .. code-block:: xml diff --git a/doc/source/users/user_manual/models_spatial_bgd.rst b/doc/source/users/user_manual/models_spatial_bgd.rst index 709a3e6..7381765 100644 --- a/doc/source/users/user_manual/models_spatial_bgd.rst +++ b/doc/source/users/user_manual/models_spatial_bgd.rst @@ -246,7 +246,7 @@ Radial acceptance background CTA IRF background ^^^^^^^^^^^^^^^^^^ - The :ref:`Instrument Response Functions (IRFs) ` contain a template + The :ref:`Instrument Response Functions (IRFs) ` 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