Added energy dispersion documentation

Michael Mayer
1 parent d8fcfdf3
Showing 3 changed files with 69 additions and 7 deletions
doc/source/users/user_manual/iact_analysis/analysis.rst
doc/source/users/user_manual/iact_analysis/high_level.rst
doc/source/users/user_manual/iact_analysis/tips.rst
@@ -381,6 +381,33 @@ Depending on the required PSF precision, one could reduce the number of offset b
   $ ctpsfcube anumbins=100
+Create energy dispersion cube (optional)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+In case energy dispersion wants to be used in the analysis, the tool :ref:`ctedispcube` computes the energy
+migration response for the given observations. Analogous to the PSF cube, the Edisp cube is stored in
+a four-dimensional map. In each bin of the cube, the migration value ``E_reco/E_true`` is stored. The granularity
+of the migration histogram can be steered via the hidden parameter ``migrabins`` (default: 100). In addition, the
+maximum migration value can be set via the hidden parameter ``migramax`` (default: 2.0). Similar to the PSF cube,
+the edispcube FITS file can become quite large. Therefore, since the energy dispersion shouldn't vary too much across
+the sky region, one could reduce the spatial binning:
+
+.. code-block:: bash
+
+  $ ctedispcube
+  Input event list or observation definition XML file [NONE] selected_obs.xml 
+  Input counts cube file to extract energy dispersion cube definition [NONE] 
+  First coordinate of image center in degrees (RA or galactic l) (0-360) [83.63] 
+  Second coordinate of image center in degrees (DEC or galactic b) (-90-90) [22.01] 
+  Projection method (AIT|AZP|CAR|MER|MOL|STG|TAN) [CAR] 
+  Coordinate system (CEL - celestial, GAL - galactic) (CEL|GAL) [CEL] 
+  Image scale (in degrees/pixel) [1.0] 0.2
+  Size of the X axis in pixels [10] 20
+  Size of the Y axis in pixels [10] 20
+  Lower energy limit (TeV) [0.1] 0.5
+  Upper energy limit (TeV) [100.0] 50
+  Number of energy bins [20] 
+  Output energy dispersion cube file [edispcube.fits]
+
 Create background cube
 ^^^^^^^^^^^^^^^^^^^^^^
 Last but not least, for a binned IACT analysis a cube containing the background rate in sky coordinates and
@@ -451,6 +478,19 @@ Note that when passing an event cube to :ref:`ctlike`, the tool behaves differen
 It queries directly for the additional ingredients for the binned analysis. It is important to pass the background model
 generated by :ref:`ctbkgcube` here to ensure the proper modelling of the background in the fit.
+Running :ref:`ctlike` with energy dispersion, the hidden parameter ``edisp=yes`` needs to be specified. The tool
+will then additionally query for the energy dispersion cube described above:
+
+.. code-block:: bash
+  
+  $ ctlike debug=yes
+  Input event list, counts cube or observation definition XML file [events.fits] cntcube.fits 
+  Input exposure cube file (only needed for stacked analysis) [NONE] expcube.fits 
+  Input PSF cube file (only needed for stacked analysis) [NONE] psfcube.fits 
+  Input energy dispersion cube file (only needed for stacked analysis) [NONE] edispcube.fits 
+  Input background cube file (only needed for stacked analysis) [NONE] bkgcube.fits 
+  Input model XML file [binned_models.xml]
+  Output model XML file [binned_results.xml] 
@@ -56,7 +56,8 @@ For a direct output on the screen, pass the hidden parameter ``debug=yes`` on th
   2016-02-19T15:43:08:  Total livetime ............: 6427.52 s = 107.13 min = 1.79 h
   ... 
-Further options are described on the reference page :ref:`csobsinfo`. 
+Further options are described on the reference page :ref:`csobsinfo`. For instance, is possible to
+generate a ds9 region file including all the pointing position by specifying the hidden parameter ``ds9file``. 
 Inspecting model XML files
 --------------------------
@@ -90,6 +91,8 @@ parameters that are at their limits might be of interest.
   2016-02-19T15:50:40:  Free spectral parameters ..: 2
   2016-02-19T15:50:40:  Parameters at limit .......: 0
+Similar to :ref:`csobsinfo`, a ds9 region file including all the sky model components
+can be generated by specifying the hidden parameter ``ds9file``. 
 Compute upper limit
 -------------------
@@ -120,13 +123,18 @@ source of interest. For this purpose, the tool :ref:`cterror` can be used:
 	Output model XML file [cterror_results.xml] 
 The output model does not contain asymmetric errors yet. The positive and negative uncertainties can be read from the
-logfile (or from screen) if ``debug=yes`` was specified.
+logfile (or from screen if ``debug=yes`` was specified).
 Compute spectral points
 -----------------------
 A very common task in astronomy is to compute spectral data points. To determine a spectral data point, a small energy
 range is considered and the model prefactor and its uncertainty is evaluated. The tool :ref:`csspec` works on both, binned
-and unbinned data. 
+and unbinned data. The hidden parameter ``edisp=yes`` can be specified in both cases to consider the energy migration
+matrix in the fit.
+
+.. note::
+  
+  The resulting spectral points are provided as a function of reconstructed energy. 
 Unbinned
 ^^^^^^^^
@@ -158,8 +166,7 @@ Binned
 	Number of spectral points (1-10000) [10] 
 	Lower energy limit for spectral points (TeV) [0.5] 
 	Upper energy limit for spectral points (TeV) [50.0] 
-	Output spectrum file [spectrum.fits] 
-
+	Output spectrum file [spectrum.fits]  
 Plot spectral points
 ^^^^^^^^^^^^^^^^^^^^
@@ -13,7 +13,7 @@ Create a skymap of counts
 The tool :ref:`ctskymap` allows to create a single map of counts contained inside an observation container.
 In contrast to :ref:`ctbin`, ctskymap takes into account all events that fall into the skymap energy range and spatial range.
 Since :ref:`ctbin` is intended for binned/stacked analysis, it respects energy thresholds, RoI selections etc.
-Accordingly, :ref:`ctskymap` should be used for a simple visualisation of the counts.
+Accordingly, :ref:`ctskymap` could be used for a simple visualisation of the counts.
 .. code-block:: bash
@@ -31,6 +31,15 @@ Accordingly, :ref:`ctskymap` should be used for a simple visualisation of the co
 	Size of the Y axis in pixels [200] 
 	Output skymap file [skymap.fits] 
+Alternatively, one could use count cube and collapse the maps into one single image via Python:
+
+.. code-block:: python
+ 
+   import gammalib
+   map = gammalib.GSkyMap("myCountCube.fits") # Loads the count cube
+   map.stack_maps() # Stack energy slices
+   map.save("myCountMap.fits") # Save to file
+	
 Create region file of pointings
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 In particular, one might want to know how the pointings of the observation container distribute across the sky.
@@ -77,6 +86,12 @@ to access information in python:
   info.ebounds()  # gammalib.GEbounds object of energy ranges
   info.gti()      # gammalib.GGti object containing good time intervals 
+There is also an example script to plot several information about an observation container which might be useful
+for a quick visualisation of the observations inside a container:
+
+.. code-block:: bash
+  
+  $ python $CTOOLS/examples/show_obs.py selected_obs.xml
 Visualise models
 ----------------
@@ -185,7 +200,7 @@ Not all issues can be tackled. Nevertheless, here is a list of actions that have
 * Consider switching to binned analysis if the observation time exceeds 50-100 hours.
 * Diffuse and extended sources in the RoI are computational expensive. However, in unbinned analysis they impact the speed much more.
-* Usage of energy dispersion in unbinned analysis could also cause a long fit. Try switching it off if speed is important.
+* Usage of energy dispersion could also cause a long fit. Try switching it off if speed is important. Keep in mind this will have an effect on the results.
 * Switch to a machine that supports OpenMP. This allows to parallelise the fit onto several cores.
 Compute excess maps