Re-organize "Getting started" section of User Manual and add information about C…

…TA Instrument Response Functions.

Re-organize "Getting started" section of User Manual and add information about C…
…TA Instrument Response Functions.
Jürgen Knödlseder
1 parent dbc06261
Showing 9 changed files with 159 additions and 26 deletions
doc/source/_templates/index.html
doc/source/conf.py
doc/source/user_manual/getting_started/faq.rst
doc/source/user_manual/getting_started/index.rst
doc/source/user_manual/getting_started/models.rst
doc/source/user_manual/getting_started/python.rst
doc/source/user_manual/quickstart.rst → doc/source/user_manual/getting_started/quickstart.rst
doc/source/user_manual/getting_started/response.rst
doc/source/user_manual/index.rst
@@ -34,7 +34,7 @@ CTA format), Fermi/LAT and COMPTEL data. {%endtrans%}&lt;/p&gt;
  
 <ul>
 <li><a class="smalllink" href="{{ pathto("user_manual/getting") }}">{%trans%}Installation{%endtrans%}</a></li> 
-<li><a class="smalllink" href="{{ pathto("user_manual/quickstart") }}">{%trans%}Quickstart{%endtrans%}</a></li> 
+<li><a class="smalllink" href="{{ pathto("user_manual/getting_started/quickstart") }}">{%trans%}Quickstart{%endtrans%}</a></li> 
 <li><a class="smalllink" href="{{ pathto("user_manual/index") }}">{%trans%}User Manual{%endtrans%}</a></li> 
 <li><a class="smalllink" href="{{ pathto("documentation") }}">{%trans%}ctools reference{%endtrans%}</a></li> 
 <li><a class="smalllink" href="doxygen/index.html">{%trans%}Source code documentation (Doxygen){%endtrans%}</a></li> 
@@ -51,7 +51,7 @@ copyright = u&#39;2014, ctools developers&#39;
 version = '0.7'
  
 # The full version, including alpha/beta/rc tags.
-release = '0.7.1'
+release = '0.7.2'
  
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
@@ -165,7 +165,7 @@ html_show_copyright = False
 #html_file_suffix = None
  
 # Output file base name for HTML help builder.
-htmlhelp_basename = 'GammaLibdoc'
+htmlhelp_basename = 'ctoolsdoc'
  
  
 # -- Options for LaTeX output --------------------------------------------------
+Frequently asked questions
+--------------------------
+
+To be written ...
+Getting started
+===============
+
+.. toctree::
+   :maxdepth: 2
+
+   quickstart
+   response
+   models
+   python
+   faq
+
+Models available in ctools
+--------------------------
+
+To be written ... (you may read
+http://gammalib.sourceforge.net/user_manual/modules/model.html#spectral-models for the time being).
+Using ctools from Python
+------------------------
+
+To be written ...
-Getting started
-===============
-
 A quick ctools tutorial
 -----------------------
  
@@ -641,22 +638,3 @@ the same events for both analyses.
   2014-01-09T21:47:54: +==============+
   2014-01-09T21:47:54: 
   2014-01-09T21:47:54: Application "ctlike" terminated after 6 wall clock seconds, consuming 0.163384 seconds of CPU time.
-
-
-Models available in ctools
---------------------------
-
-To be written ... (you may read
-http://gammalib.sourceforge.net/user_manual/modules/model.html#spectral-models for the time being).
-
-
-Using ctools from Python
-------------------------
-
-To be written ...
-
-
-Frequently asked questions
---------------------------
-
-To be written ...
+CTA Instrument Response Functions
+---------------------------------
+
+.. note ::
+
+   Instrument response functions are formally not part of ctools as they
+   should be provided by the instrument teams. The GammaLib framework on
+   which ctools are built comes with a set of basic response functions, but
+   for getting the latest instrument response functions you should contact
+   the relevant instrument teams. CTA consortium members should 
+   `download 
+   <https://portal.cta-observatory.org/WG/DM/DM_wiki/DATA_Access/Pages/Science%20Tools.aspx>`_
+   the latest calibration database containing Prod1 and Prod2 instrument
+   response functions from the consortium Sharepoint site (requires 
+   password).
+
+
+What are instrument response functions?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+(will provide a general description of what are IRFs)
+
+
+Data formats
+~~~~~~~~~~~~
+
+So far the data format of the CTA instrument response functions has not
+yet been defined, and information about instrument response functions is
+provided in various ways.
+
+
+.. _sec_cta_rsp_perftable:
+
+Performance tables
+^^^^^^^^^^^^^^^^^^
+
+In the early days, the instrument performances derived from Monte-Carlo
+simulations have been summarised in what we call here Performance 
+Tables, which are ASCII files that contain as function of energy the
+on-axis performance parameters of CTA, such as effective area, point spread
+function containment radius, energy resolution, background count rate and
+differential sensitivity.
+
+Below an example of a CTA performance table::
+
+  log(E)     Area     r68     r80  ERes. BG Rate    Diff Sens
+  -1.7      261.6  0.3621  0.4908 0.5134 0.0189924  6.88237e-11
+  -1.5     5458.2  0.2712  0.3685 0.4129 0.1009715  1.72717e-11
+  -1.3    15590.0  0.1662  0.2103 0.2721 0.0575623  6.16963e-12
+  -1.1    26554.1  0.1253  0.1567 0.2611 0.0213008  2.89932e-12
+  -0.9    52100.5  0.1048  0.1305 0.1987 0.0088729  1.39764e-12
+  -0.7    66132.1  0.0827  0.1024 0.1698 0.0010976  6.03531e-13
+  -0.5   108656.8  0.0703  0.0867 0.1506 0.0004843  3.98147e-13
+  -0.3   129833.0  0.0585  0.0722 0.1338 0.0001575  3.23090e-13
+  -0.1   284604.3  0.0531  0.0656 0.1008 0.0001367  2.20178e-13
+   0.1   263175.3  0.0410  0.0506 0.0831 0.0000210  1.87452e-13
+   0.3   778048.6  0.0470  0.0591 0.0842 0.0000692  1.53976e-13
+   0.5   929818.8  0.0391  0.0492 0.0650 0.0000146  1.18947e-13
+   0.7  1078450.0  0.0335  0.0415 0.0541 0.0000116  1.51927e-13
+   0.9  1448579.1  0.0317  0.0397 0.0516 0.0000047  1.42439e-13
+   1.1  1899905.0  0.0290  0.0372 0.0501 0.0000081  1.96670e-13
+   1.3  2476403.8  0.0285  0.0367 0.0538 0.0000059  2.20695e-13
+   1.5  2832570.6  0.0284  0.0372 0.0636 0.0000073  3.22523e-13
+   1.7  3534065.3  0.0290  0.0386 0.0731 0.0000135  4.84153e-13
+   1.9  3250103.4  0.0238  0.0308 0.0729 0.0000044  6.26265e-13
+   2.1  3916071.6  0.0260  0.0354 0.0908 0.0000023  7.69921e-13
+   ---------------------------------------------
+   1) log(E) = log10(E/TeV) - bin centre
+   2) Eff Area - in square metres after background cut (no theta cut)
+   3) Ang. Res - 68% containment radius of gamma-ray PSF post cuts - in degrees
+   4) Ang. Res - 80% containment radius of gamma-ray PSF post cuts - in degrees
+   5) Fractional Energy Resolution (rms)
+   6) BG Rate  - inside point-source selection region - post call cuts - in Hz
+   7) Diff Sens - differential sensitivity for this bin expressed as E^2 dN/dE
+      - in erg cm^-2 s^-1 - for a 50 hours exposure - 5 sigma significance including
+      systematics and statistics and at least 10 photons.
+
+
+.. _sec_cta_rsp_xspec:
+
+1DC Data Format
+^^^^^^^^^^^^^^^
+
+Instrument response information for the first CTA Data Challenge (1DC) has been
+provided in a format that was heavily inspired by the 
+`RMF and ARF file formats 
+<http://heasarc.gsfc.nasa.gov/docs/heasarc/caldb/docs/memos/cal_gen_92_002/cal_gen_92_002.html>`_
+that have been introduced by
+`HEASARC <http://heasarc.gsfc.nasa.gov/>`_
+for spectral analysis of X-ray data.
+
+The Redistribution Matrix File (RMF) describes how an incoming photon with 
+a given true energy is redistributed in measured energy. In other words, it
+describes the energy dispersion of the instrument. The RMF is organised as
+a two-dimensional matrix, with the first axis being in true energies while
+the second axis represents the measured energies.
+
+The Ancillary Response File (ARF) describes the sensitivity of the 
+instrument to photons of a given true energy. The ARF gives the effective
+area of the detector system after applying an event selection cut
+(theta cut). For computing the ARF, some knowledge of the Point Spread
+Function (PSF) is needed, so that the fraction of photons that falls into
+the event selection region for a given source can be properly estimated.
+Once this is done, no further PSF information is needed for the analysis.
+
+ctools however relies on the full modelling of the instrument, including 
+the Point Spread Function, and hence, PSF information has also been 
+provided for 1DC. Two data formats have been used for this: a first that 
+is based on a simple one-dimensional vector, providing the width of a
+2-dimensional Gaussian as function of energy; and a second that is based
+on a three-component 2D Gaussian as function of energy and offset angle
+in the camera system. While the former was implement by a simply FITS 
+table with two columns, the latter was implemented by
+:ref:`sec_cta_rsp_rsptable`.
+
+
+.. _sec_cta_rsp_rsptable:
+
+Response tables
+^^^^^^^^^^^^^^^
+
+The CTA response table class ``GCTAResponseTable`` provides a generic 
+handle for multi-dimensional response information. It is based on the 
+response format used for storing response information for the
+*Fermi*/LAT telescope. In this format, all information is stored in
+a single row of a FITS binary table. Each element of the row contains
+a vector column, that describes the axes of the  multi-dimensional response
+cube and the response information. Note that this class may in the future
+be promoted to the GammaLib core, as a similar class has been implemented
+in the *Fermi*/LAT interface. 
@@ -7,7 +7,7 @@ User Manual
  
    introduction
    getting
-   quickstart
+   getting_started/index
    enhancing
    reference
    expert