Add 1DC documentation HowTo sections

Jürgen Knödlseder
1 parent abb14b99
Showing 10 changed files with 174 additions and 5 deletions
cscripts/cstsmapsplit.par
doc/source/users/reference_manual/cstsmapsplit.rst
doc/source/users/tutorials/1dc/howto.rst
doc/source/users/tutorials/1dc/howto_display.rst
doc/source/users/tutorials/1dc/howto_lightcurve.png
doc/source/users/tutorials/1dc/howto_lightcurve.rst
doc/source/users/tutorials/1dc/howto_vo.rst
doc/source/users/tutorials/1dc/howto_vo_aladin_after.png
doc/source/users/tutorials/1dc/howto_vo_aladin_before.png
doc/source/users/tutorials/1dc/howto_vo_aladin_catalog.png
@@ -47,7 +47,6 @@ proj,      s, a, CAR, AIT|AZP|CAR|MER|MOL|STG|TAN,, &quot;Projection method&quot;
 #
 # Standard parameters
 #====================
-publish, b, h, no,,, "Publish Test Statistic map on VO Hub?"
 chatter, i, h, 2,0,4, "Chattiness of output"
 clobber, b, h, yes,,, "Overwrite existing output files with new output files?"
 debug,   b, h, no,,, "Debugging mode activated"
@@ -90,9 +90,6 @@ General parameters
 Standard parameters
 -------------------
  
-``(publish = no) [boolean]``
-    Specifies whether the TS map should be published on VO Hub.
-
 ``(chatter = 2) [integer]``
     Verbosity of the executable:
      chatter = 0: no information will be logged
@@ -9,12 +9,14 @@ issues.
 .. toctree::
    :maxdepth: 2
  
+   howto_display
    howto_ts
    howto_tsmap
    howto_ulimit
    howto_lightcurve
    howto_phasecurve
    howto_exclude
+   howto_vo
  
 If you cannot find the answer to your question, have a look at the
 :ref:`first steps with ctools <quickstart>`
+.. _1dc_howto_display:
+
+How to display the results?
+---------------------------
+
+The ctools package does not contain any tools or scripts for graphical
+display of results since results are generally written into standard FITS
+files that are readily displayed by existing astronomical tools.
+
+Nevertheless, for your convenience several scripts for graphical display are
+included in the ctools package that rely on the
+`matplotlib <http://matplotlib.org>`_
+Python module. You can find these scripts in the
+``$CTOOLS/share/examples/python`` folder. The following scripts are available:
+
++------------------------+-----------------------------+
+| Script                 | Usage                       |
++========================+=============================+
+| ``show_butterfly.py``  | Display a butterfly diagram |
++------------------------+-----------------------------+
+| ``show_lightcurve.py`` | Display a light curve       |
++------------------------+-----------------------------+
+| ``show_spectrum.py``   | Display a spectrum          |
++------------------------+-----------------------------+
@@ -3,4 +3,48 @@
 How to generate a light curve?
 ------------------------------
  
-To be written ...
+You can generate a light curve using the :ref:`cslightcrv` script which
+takes on input an
+:ref:`event list <glossary_eventlist>`
+or a
+:ref:`observation definition XML file <glossary_obsdef>`.
+:ref:`cslightcrv` divides the event list into a number of intervals and
+performs a maximum likelihood analyse for each of the intervals.
+The results are writted into a light curve FITS file.
+
+The following example illustrates how you can generate a light curve for
+``Src001`` for the time interval from 51552.5 to 51552.6 (MJD). Ten time
+intervals were chosen in this example.
+
+.. code-block:: bash
+
+   $ cslightcrv
+   Input event list or observation definition XML file [events.fits] obs.xml
+   Input model definition XML file [$CTOOLS/share/models/crab.xml] models.xml
+   Source name [Crab] Src001
+   Algorithm for defining time bins (FILE|LIN|GTI) [GTI] LIN
+   Lightcurve start time (MJD) [51544.5] 51552.5
+   Lightcurve stop time (MJD) [51544.6] 51552.6
+   Number of time bins (1-10000) [5] 10
+   Number of energy bins for binned (0=unbinned) (0-100) [0]
+   Lower energy limit of events (TeV) [0.1]
+   Upper energy limit of events (TeV) [100.0]
+   Output light curve file [lightcurve.fits]
+
+The resulting light curve is shown in the figure below.
+
+.. figure:: howto_lightcurve.png
+   :width: 600px
+   :align: center
+
+   *Light curve from 51552.5 to 51552.6 (MJD) for Src001*
+
+.. note::
+   The plot was created using the ``show_lightcurve.py`` script that is
+   located in the ctools example folder. The example script requires the
+   `matplotlib <http://matplotlib.org>`_ Python module for display.
+   You may reproduce the plot by typing
+
+   .. code-block:: bash
+
+      $ $CTOOLS/share/examples/python/show_lightcurve.py lightcurve.fits
+.. _1dc_howto_vo:
+
+How to use Virtual Observatory tools with ctools?
+-------------------------------------------------
+
+Several ctools can interact with Virtual Observatory tools such as
+`Aladin <http://aladin.u-strasbg.fr>`_
+or
+`Topcat <http://www.star.bris.ac.uk/~mbt/topcat/>`_
+for the visualisation and exploration of the analysis results.
+
+Let's take the example of generating a sky map, as explained
+:ref:`before <1dc_sky_map>`. Start with launching the
+`Aladin <http://aladin.u-strasbg.fr>`_
+application on your desktop:
+
+.. figure:: howto_vo_aladin_before.png
+   :width: 400px
+   :align: center
+
+   *Aladin application after start-up*
+
+Then use :ref:`ctskymap` to create a sky map and specify ``publish=yes``
+as argument after the tool name:
+
+.. code-block:: bash
+
+   $ ctskymap publish=yes
+   Input event list or observation definition XML file [events.fits] obs.xml
+   First coordinate of image center in degrees (RA or galactic l) (0-360) [83.63] 0.0
+   Second coordinate of image center in degrees (DEC or galactic b) (-90-90) [22.01] 0.0
+   Projection method (AIT|AZP|CAR|MER|MOL|STG|TAN) [CAR]
+   Coordinate system (CEL - celestial, GAL - galactic) (CEL|GAL) [CEL] GAL
+   Image scale (in degrees/pixel) [0.02]
+   Size of the X axis in pixels [200] 400
+   Size of the Y axis in pixels [200] 400
+   Lower energy limit (TeV) [0.1]
+   Upper energy limit (TeV) [100.0]
+   Background subtraction method (NONE|IRF) [NONE] IRF
+   Output skymap file [skymap.fits]
+
+Once :ref:`ctskymap` has terminated, the resulting sky map will automatically
+appear in the
+`Aladin <http://aladin.u-strasbg.fr>`_
+application (see below).
+
+.. figure:: howto_vo_aladin_after.png
+   :width: 400px
+   :align: center
+
+   *Aladin application after ctskymap finished execution*
+
+You can then overlay sky maps obtained at other wavelengths for comparison or
+objects extracted from a catalogue. In the example below we show the overlay
+of the
+`SIMBAD <http://simbad.u-strasbg.fr/simbad/>`_
+catalogue which allows us to identify ``Src002`` with the Galactic centre.
+
+.. figure:: howto_vo_aladin_catalog.png
+   :width: 400px
+   :align: center
+
+   *Overlay of the SIMBAD catalog over the sky map*
+
+Below the list of tools and scripts that interact with Virtual Observatory
+tools. Some tools or scripts publish tables instead of images, and the tables
+can for example by displayed and explored using
+`Topcat <http://www.star.bris.ac.uk/~mbt/topcat/>`_.
+
++-------------------+--------+-------------------+
+| Tool or script    | Object | VO tool (example) |
++===================+========+===================+
+| :ref:`cslightcrv` | Table  | Topcat            |
++-------------------+--------+-------------------+
+| :ref:`csresmap`   | Image  | Aladin            |
++-------------------+--------+-------------------+
+| :ref:`csspec`     | Table  | Topcat            |
++-------------------+--------+-------------------+
+| :ref:`csviscube`  | Image  | Aladin            |
++-------------------+--------+-------------------+
+| :ref:`ctbin`      | Image  | Aladin            |
++-------------------+--------+-------------------+
+| :ref:`ctbkgcube`  | Image  | Aladin            |
++-------------------+--------+-------------------+
+| :ref:`ctcubemask` | Image  | Aladin            |
++-------------------+--------+-------------------+
+| :ref:`ctexpcube`  | Image  | Aladin            |
++-------------------+--------+-------------------+
+| :ref:`ctmapcube`  | Image  | Aladin            |
++-------------------+--------+-------------------+
+| :ref:`ctmodel`    | Image  | Aladin            |
++-------------------+--------+-------------------+
+| :ref:`ctobssim`   | Table  | Topcat            |
++-------------------+--------+-------------------+
+| :ref:`ctselect`   | Table  | Topcat            |
++-------------------+--------+-------------------+
+| :ref:`ctskymap`   | Image  | Aladin            |
++-------------------+--------+-------------------+
+| :ref:`cttsmap`    | Image  | Aladin            |
++-------------------+--------+-------------------+
+
+
+