From a36f0bd6fa24fc0860f8cb4d05e61a297a6501ac Mon Sep 17 00:00:00 2001 From: Jürgen Knödlseder Date: Mon, 1 Apr 2019 16:20:00 +0200 Subject: [PATCH] Reorganise IRF description in User Manual --- doc/source/users/user_manual/index.rst | 2 +- doc/source/users/user_manual/irf-aeff.png | Bin 3319 -> 0 bytes doc/source/users/user_manual/irf-file.png | Bin 7266 -> 0 bytes doc/source/users/user_manual/irf.rst | 10 ++++++++++ doc/source/users/user_manual/irf_cta.rst | 202 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/source/users/user_manual/irf_cta_aeff.png | Bin 0 -> 3319 bytes doc/source/users/user_manual/irf_cta_file.png | Bin 0 -> 7266 bytes doc/source/users/user_manual/irf_intro.rst | 21 +++++++++++++++++++++ doc/source/users/user_manual/models_concept.rst | 6 +++--- doc/source/users/user_manual/models_implementation.rst | 2 +- doc/source/users/user_manual/models_spatial_bgd.rst | 2 +- doc/source/users/user_manual/response.rst | 219 --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- 12 files changed, 239 insertions(+), 225 deletions(-) delete mode 100755 doc/source/users/user_manual/irf-aeff.png delete mode 100755 doc/source/users/user_manual/irf-file.png create mode 100755 doc/source/users/user_manual/irf.rst create mode 100755 doc/source/users/user_manual/irf_cta.rst create mode 100755 doc/source/users/user_manual/irf_cta_aeff.png create mode 100755 doc/source/users/user_manual/irf_cta_file.png create mode 100755 doc/source/users/user_manual/irf_intro.rst delete mode 100755 doc/source/users/user_manual/response.rst 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-aeff.png b/doc/source/users/user_manual/irf-aeff.png deleted file mode 100755 index eabbe69..0000000 Binary files a/doc/source/users/user_manual/irf-aeff.png and /dev/null differ diff --git a/doc/source/users/user_manual/irf-file.png b/doc/source/users/user_manual/irf-file.png deleted file mode 100755 index 31f1599..0000000 Binary files a/doc/source/users/user_manual/irf-file.png and /dev/null differ 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/irf_cta.rst b/doc/source/users/user_manual/irf_cta.rst new file mode 100755 index 0000000..1725b85 --- /dev/null +++ b/doc/source/users/user_manual/irf_cta.rst @@ -0,0 +1,202 @@ +.. _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 +the effective area :math:`A_{\rm eff}(p, E, t)` (units :math:`cm^2`), +the point spread function :math:`PSF(p' | p, E, t)`, +and the energy dispersion :math:`E_{\rm disp}(E' | p, E, t)` +following + +.. math:: + R(p', E', t' | p, E, t) = + A_{\rm eff}(p, E, t) \times + PSF(p' | p, E, t) \times + E_{\rm disp}(E' | p, E, t) + +where + +.. math:: + \int PSF(p' | p, E, t) dp' = 1 + +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. +In total, the following six instrument response functions are available: +``North_0.5h``, ``North_5h``, ``North_50h``, ``South_0.5h``, +``South_5h``, and ``South_50h``. + +.. note:: + If you use the CTA instrument response functions for a research project + and specifically for a presentation or publication, we ask to add the + following acknowledgement to the presentation or publication: + + *This research has made use of the CTA instrument response functions + provided by the CTA Consortium and Observatory.* + + The latest CTA reponse function (prod3b-v1) can be downloaded from + `this link `_. To install the response function, type + + .. code-block:: bash + + $ tar xvfz CTA-Performance-prod3b-v1-FITS1.tar.gz -C $CTOOLS/share + + or + + .. code-block:: bash + + $ sudo tar xvfz CTA-Performance-prod3b-v1-FITS1.tar.gz -C $CTOOLS/share + + if you need root priviledges to install in your ``$CTOOLS`` directory. + To use the prod3b-v1 response functions, specify ``prod3b-v1`` if a tool + or script queries for the calibration database. + + +Specifying CTA response functions +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The specification of the CTA Instrument Response Functions depends on the +way how ctools are used. Common to all methods is that the IRFs are +defined by a response name and a calibration database name. +ctools makes use of HEASARC's CALDB format to index and store +IRFs, and specification of the database and response names is +sufficient to access the response. + + +Specifying the response function as input parameters +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +ctools that require instrument response functions have two parameters +to specify the calibration database name and the response function name. +The following example shows a ``ctobssim`` run using the ``prod2`` +calibration database and the ``South_0.5h`` response function: + +.. code-block:: bash + + $ ctobssim + RA of pointing (degrees) (0-360) [83.63] + Dec of pointing (degrees) (-90-90) [22.51] + Radius of FOV (degrees) (0-180) [5.0] + Start time (UTC string, JD, MJD or MET in seconds) [2020-01-01T00:00:00] + Stop time (UTC string, JD, MJD or MET in seconds) [2020-01-01T00:30:00] + Lower energy limit (TeV) [0.1] + Upper energy limit (TeV) [100.0] + Calibration database [prod2] + Instrument response function [South_0.5h] + Input model XML file [$CTOOLS/share/models/crab.xml] + Output event data file or observation definition XML file [events.fits] + +Running the other tools is equivalent. + + +Specifying the response function in an observation definition file +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +In the above example, only a single global response function can be +used for all CTA observations. If you need to specify response functions +per observation you can add the information directly in the XML observation +definition file: + +.. code-block:: xml + + + + + + + + +The ``Calibration`` parameter specifies the calibration database and +response name. You can then pass this file directly to, e.g., ``ctlike``: + +.. code-block:: bash + + $ ctlike + Input event list, counts cube or observation definition XML file [events.fits] obs_irf.xml + Input model XML file [$CTOOLS/share/models/crab.xml] + Output model XML file [crab_results.xml] + +Note that ``ctlike`` does not ask for the calibration database and +response name as it found the relevant information in the XML file. + +.. _sec_cta_rsp_abspath: + + +Specifying individual instrument response files +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you need even more control over individual response files, you can +specify them individually in the XML observation file as follows: + +.. code-block:: xml + + + + + + + + + + + + +From within a Python script +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following example illustrates how to set the calibration database +and response name from within Python: + +.. code-block:: python + + >>> import gammalib + >>> obs = gammalib.GCTAObservation() + >>> caldb = gammalib.GCaldb("cta", "prod2") + >>> irf = "South_0.5h" + >>> obs.response(irf, caldb) + +The calibration database is set by creating a ``GCaldb`` object. The +constructor takes as argument the mission (always ``cta``) and the +database name, in our case ``prod2``. The response function is then set +by passing the response name (here ``South_0.5h``) and the calibration +database object to the ``response`` method. diff --git a/doc/source/users/user_manual/irf_cta_aeff.png b/doc/source/users/user_manual/irf_cta_aeff.png new file mode 100755 index 0000000..eabbe69 Binary files /dev/null and b/doc/source/users/user_manual/irf_cta_aeff.png differ diff --git a/doc/source/users/user_manual/irf_cta_file.png b/doc/source/users/user_manual/irf_cta_file.png new file mode 100755 index 0000000..31f1599 Binary files /dev/null and b/doc/source/users/user_manual/irf_cta_file.png differ 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 diff --git a/doc/source/users/user_manual/response.rst b/doc/source/users/user_manual/response.rst deleted file mode 100755 index 65e83a5..0000000 --- a/doc/source/users/user_manual/response.rst +++ /dev/null @@ -1,219 +0,0 @@ -.. _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. - - -CTA response functions -~~~~~~~~~~~~~~~~~~~~~~ - -The instrument response functions for CTA (as well as the other IACTs such as -H.E.S.S., VERITAS and MAGIC) are factorised into -the effective area :math:`A_{\rm eff}(p, E, t)` (units :math:`cm^2`), -the point spread function :math:`PSF(p' | p, E, t)`, -and the energy dispersion :math:`E_{\rm disp}(E' | p, E, t)` -following - -.. math:: - R(p', E', t' | p, E, t) = - A_{\rm eff}(p, E, t) \times - PSF(p' | p, E, t) \times - E_{\rm disp}(E' | p, E, t) - -where - -.. math:: - \int PSF(p' | p, E, t) dp' = 1 - -and - -.. math:: - \int E_{\rm disp}(E' | p, E, t) dE' = 1 - -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. -In total, the following six instrument response functions are available: -``North_0.5h``, ``North_5h``, ``North_50h``, ``South_0.5h``, -``South_5h``, and ``South_50h``. - -.. note:: - If you use the CTA instrument response functions for a research project - and specifically for a presentation or publication, we ask to add the - following acknowledgement to the presentation or publication: - - *This research has made use of the CTA instrument response functions - provided by the CTA Consortium and Observatory.* - - The latest CTA reponse function (prod3b-v1) can be downloaded from - `this link `_. To install the response function, type - - .. code-block:: bash - - $ tar xvfz CTA-Performance-prod3b-v1-FITS1.tar.gz -C $CTOOLS/share - - or - - .. code-block:: bash - - $ sudo tar xvfz CTA-Performance-prod3b-v1-FITS1.tar.gz -C $CTOOLS/share - - if you need root priviledges to install in your ``$CTOOLS`` directory. - 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 -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The specification of the CTA Instrument Response Functions depends on the -way how ctools are used. Common to all methods is that the IRFs are -defined by a response name and a calibration database name. -ctools makes use of HEASARC's CALDB format to index and store -IRFs, and specification of the database and response names is -sufficient to access the response. - - -Specifying the response function as input parameters -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -ctools that require instrument response functions have two parameters -to specify the calibration database name and the response function name. -The following example shows a ``ctobssim`` run using the ``prod2`` -calibration database and the ``South_0.5h`` response function: - -.. code-block:: bash - - $ ctobssim - RA of pointing (degrees) (0-360) [83.63] - Dec of pointing (degrees) (-90-90) [22.51] - Radius of FOV (degrees) (0-180) [5.0] - Start time (UTC string, JD, MJD or MET in seconds) [2020-01-01T00:00:00] - Stop time (UTC string, JD, MJD or MET in seconds) [2020-01-01T00:30:00] - Lower energy limit (TeV) [0.1] - Upper energy limit (TeV) [100.0] - Calibration database [prod2] - Instrument response function [South_0.5h] - Input model XML file [$CTOOLS/share/models/crab.xml] - Output event data file or observation definition XML file [events.fits] - -Running the other tools is equivalent. - - -Specifying the response function in an observation definition file -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -In the above example, only a single global response function can be -used for all CTA observations. If you need to specify response functions -per observation you can add the information directly in the XML observation -definition file: - -.. code-block:: xml - - - - - - - - -The ``Calibration`` parameter specifies the calibration database and -response name. You can then pass this file directly to, e.g., ``ctlike``: - -.. code-block:: bash - - $ ctlike - Input event list, counts cube or observation definition XML file [events.fits] obs_irf.xml - Input model XML file [$CTOOLS/share/models/crab.xml] - Output model XML file [crab_results.xml] - -Note that ``ctlike`` does not ask for the calibration database and -response name as it found the relevant information in the XML file. - -.. _sec_cta_rsp_abspath: - - -Specifying individual instrument response files -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -If you need even more control over individual response files, you can -specify them individually in the XML observation file as follows: - -.. code-block:: xml - - - - - - - - - - - - -From within a Python script -^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -The following example illustrates how to set the calibration database -and response name from within Python: - -.. code-block:: python - - >>> import gammalib - >>> obs = gammalib.GCTAObservation() - >>> caldb = gammalib.GCaldb("cta", "prod2") - >>> irf = "South_0.5h" - >>> obs.response(irf, caldb) - -The calibration database is set by creating a ``GCaldb`` object. The -constructor takes as argument the mission (always ``cta``) and the -database name, in our case ``prod2``. The response function is then set -by passing the response name (here ``South_0.5h``) and the calibration -database object to the ``response`` method. -- libgit2 0.21.4