Enhance 1DC documentation

Jürgen Knödlseder
1 parent 6dfd7517
Showing 7 changed files with 128 additions and 3 deletions
doc/source/users/tutorials/1dc/first.rst
doc/source/users/tutorials/1dc/first_detect.rst
doc/source/users/tutorials/1dc/first_fitting.rst
doc/source/users/tutorials/1dc/first_select_obs.rst
doc/source/users/tutorials/1dc/first_skymap_fitted.png
doc/source/users/tutorials/1dc/first_skymap_sources.png
doc/source/users/tutorials/1dc/first_spectrum.png
@@ -21,7 +21,7 @@ If this is not the case, please read :ref:`1dc_getting`.
    first_data
    first_select_obs
    first_skymap
-   first_select_models
+   first_detect
    first_fitting
    first_residuals
    first_stacked
+.. _1dc_select_models:
+
+Detecting candidate sources
+---------------------------
+
+As next step you need to identify the location of candidate sources in the
+sky map.
+You do this using the :ref:`cssrcdetect` script:
+
+.. code-block:: bash
+
+   $ cssrcdetect
+   Input sky map file [skymap.fits]
+   Source model type (POINT) [POINT]
+   Background model type (NONE|IRF|AEFF|CUBE) [NONE] IRF
+   Detection threshold (Gaussian sigma) [5.0] 10.0
+   Output model definition XML file [models.xml]
+   Output DS9 region file [ds9.reg]
+
+This generates a
+:ref:`model definition XML file <glossary_moddef>`
+that contains point source model components for all sources that were detected
+in the sky map.
+All model components have a power law as spectral component with
+parameters that correspond to 1% of the very-high-energy spectrum of the
+Crab, which is a reasonable starting condition for a subsequent model
+fitting using the :ref:`ctlike` tool.
+To detect the sources, :ref:`cssrcdetect` employs a peak finding algorithm that
+iteratively finds all peaks in the sky map above a given threshold.
+The detection threshold was set here to ``10.0`` which means that only peaks
+are considered that are ten standard deviations above the mean value of the
+sky map pixels.
+The script generated also a `ds9 <http://ds9.si.edu>`_ region file that can
+be overlaid on the sky map.
+Due to the relatively high threshold of ten standard deviations, only two
+sources were detected.
+
+.. figure:: first_skymap_sources.png
+   :width: 600px
+   :align: center
+
+   *Background subtracted sky map of the events recorded during the Galactic Plane Survey around the Galactic Centre with the detected sources overlaid*
+
+Below is the content of the
+:ref:`model definition XML file <glossary_moddef>`
+that was generated by :ref:`cssrcdetect`.
+In addition to the two point sources the file also contains a background model
+component of type ``CTAIrfBackground``.
+This component was added since the background model type was set to ``IRF``
+in the :ref:`cssrcdetect` run.
+Having a background model component added allows to directly use the
+:ref:`model definition XML file <glossary_moddef>`
+for a model fitting with :ref:`ctlike`.
+
+.. code-block:: xml
+
+   <?xml version="1.0" encoding="UTF-8" standalone="no"?>
+   <source_library title="source library">
+     <source name="Src001" type="PointSource">
+       <spectrum type="PowerLaw">
+         <parameter name="Prefactor" value="1" error="0" scale="5.7e-18" min="0" free="1" />
+         <parameter name="Index" value="1" error="-0" scale="-2.48" min="-4.03225806451613" max="4.03225806451613" free="1" />
+         <parameter name="PivotEnergy" value="1" scale="300000" free="0" />
+       </spectrum>
+       <spatialModel type="PointSource">
+         <parameter name="RA" value="266.424004498437" error="0" scale="1" free="1" />
+         <parameter name="DEC" value="-29.0049010253548" error="0" scale="1" free="1" />
+       </spatialModel>
+     </source>
+     <source name="Src002" type="PointSource">
+       <spectrum type="PowerLaw">
+         <parameter name="Prefactor" value="1" error="0" scale="5.7e-18" min="0" free="1" />
+         <parameter name="Index" value="1" error="-0" scale="-2.48" min="-4.03225806451613" max="4.03225806451613" free="1" />
+         <parameter name="PivotEnergy" value="1" scale="300000" free="0" />
+       </spectrum>
+       <spatialModel type="PointSource">
+         <parameter name="RA" value="266.843692146479" error="0" scale="1" free="1" />
+         <parameter name="DEC" value="-28.1289200709305" error="0" scale="1" free="1" />
+       </spatialModel>
+     </source>
+     <source name="Background" type="CTAIrfBackground">
+       <spectrum type="PowerLaw">
+         <parameter name="Prefactor" value="1" error="0" scale="1" min="0" free="1" />
+         <parameter name="Index" value="0" error="0" scale="1" min="-10" max="10" free="1" />
+         <parameter name="PivotEnergy" value="1" scale="1000000" free="0" />
+       </spectrum>
+     </source>
+   </source_library>
+
@@ -9,3 +9,39 @@ Fitting the model components to the data
    Input event list, counts cube or observation definition XML file [events.fits] obs.xml
    Input model XML file [$CTOOLS/share/models/crab.xml] models.xml
    Output model XML file [crab_results.xml] results.xml
+
+
+.. figure:: first_skymap_fitted.png
+   :width: 600px
+   :align: center
+
+   *Background subtracted sky map of the events recorded during the Galactic Plane Survey around the Galactic Centre with the fitted positions of the sources shown as blue circles*
+
+.. code-block:: bash
+
+   $ ctbutterfly
+   Input event list, counts cube or observation definition XML file [events.fits] obs.xml
+   Source of interest [Crab] Src001
+   Input model XML file [$CTOOLS/share/models/crab.xml] ctlike_unbinned_bkg_3ptsrc.xml
+   Start value for first energy bin in TeV [0.1]
+   Stop value for last energy bin in TeV [100.0]
+   Output ASCII file [butterfly.txt] butterfly_src001.txt
+
+.. code-block:: bash
+
+   $ csspec
+   Input event list, counts cube, or observation definition XML file [events.fits] obs.xml
+   Input model XML file [results.xml] ctlike_unbinned_bkg_3ptsrc.xml
+   Source name [Crab] Src001
+   Binning algorithm (LIN|LOG|FILE) [LOG]
+   Lower energy limit (TeV) [0.1]
+   Upper energy limit (TeV) [100.0]
+   Number of energy bins (0=unbinned) [10]
+   Output spectrum file [spectrum.fits] spectrum_src001.fits
+
+.. figure:: first_spectrum.png
+   :width: 600px
+   :align: center
+
+   *Butterfly diagrams determined with ctbutterfly and spectral points determined with csspec for Src001 (top) and Src002 (bottom)*
+
@@ -3,8 +3,8 @@
 Selecting the relevant observations
 -----------------------------------
-Let us in the following assume that you want to analyse the Galactic Plane
-Survey data obtained with baseline arrays around the Galactic Centre.
+Let's assume that you want to analyse the Galactic Plane Survey data obtained
+with the baseline array around the Galactic Centre.
 For the purpose of this first analysis, you should create a subfolder under
 the ``1dc`` folder (or any other convenient place) that will contain the
 results for your first analysis.