diff --git a/doc/source/users/user_manual/iact_analysis/analysis.rst b/doc/source/users/user_manual/iact_analysis/analysis.rst index 2b9e3ed..6f5b107 100644 --- a/doc/source/users/user_manual/iact_analysis/analysis.rst +++ b/doc/source/users/user_manual/iact_analysis/analysis.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] diff --git a/doc/source/users/user_manual/iact_analysis/high_level.rst b/doc/source/users/user_manual/iact_analysis/high_level.rst index 2c5bb98..95cb650 100644 --- a/doc/source/users/user_manual/iact_analysis/high_level.rst +++ b/doc/source/users/user_manual/iact_analysis/high_level.rst @@ -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 ^^^^^^^^^^^^^^^^^^^^ diff --git a/doc/source/users/user_manual/iact_analysis/tips.rst b/doc/source/users/user_manual/iact_analysis/tips.rst index db0a71d..2cfed06 100644 --- a/doc/source/users/user_manual/iact_analysis/tips.rst +++ b/doc/source/users/user_manual/iact_analysis/tips.rst @@ -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