From ca70096bdc4a5c4c422c94607ccd19309cea5ec4 Mon Sep 17 00:00:00 2001 From: Jürgen Knödlseder Date: Fri, 3 Feb 2017 22:53:18 +0100 Subject: [PATCH] Add 1DC documentation HowTo sections --- cscripts/cstsmapsplit.par | 1 - doc/source/users/reference_manual/cstsmapsplit.rst | 3 --- doc/source/users/tutorials/1dc/howto.rst | 2 ++ doc/source/users/tutorials/1dc/howto_display.rst | 24 ++++++++++++++++++++++++ doc/source/users/tutorials/1dc/howto_lightcurve.png | Bin 0 -> 25726 bytes doc/source/users/tutorials/1dc/howto_lightcurve.rst | 46 +++++++++++++++++++++++++++++++++++++++++++++- doc/source/users/tutorials/1dc/howto_vo.rst | 103 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/source/users/tutorials/1dc/howto_vo_aladin_after.png | Bin 0 -> 385044 bytes doc/source/users/tutorials/1dc/howto_vo_aladin_before.png | Bin 0 -> 110329 bytes doc/source/users/tutorials/1dc/howto_vo_aladin_catalog.png | Bin 0 -> 378139 bytes 10 files changed, 174 insertions(+), 5 deletions(-) create mode 100644 doc/source/users/tutorials/1dc/howto_display.rst create mode 100644 doc/source/users/tutorials/1dc/howto_lightcurve.png create mode 100644 doc/source/users/tutorials/1dc/howto_vo.rst create mode 100644 doc/source/users/tutorials/1dc/howto_vo_aladin_after.png create mode 100644 doc/source/users/tutorials/1dc/howto_vo_aladin_before.png create mode 100644 doc/source/users/tutorials/1dc/howto_vo_aladin_catalog.png diff --git a/cscripts/cstsmapsplit.par b/cscripts/cstsmapsplit.par index 639f227..af8b8ce 100644 --- a/cscripts/cstsmapsplit.par +++ b/cscripts/cstsmapsplit.par @@ -47,7 +47,6 @@ proj, s, a, CAR, AIT|AZP|CAR|MER|MOL|STG|TAN,, "Projection method" # # 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" diff --git a/doc/source/users/reference_manual/cstsmapsplit.rst b/doc/source/users/reference_manual/cstsmapsplit.rst index 40eb71e..9e519a4 100644 --- a/doc/source/users/reference_manual/cstsmapsplit.rst +++ b/doc/source/users/reference_manual/cstsmapsplit.rst @@ -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 diff --git a/doc/source/users/tutorials/1dc/howto.rst b/doc/source/users/tutorials/1dc/howto.rst index c33e010..9eb7fcd 100644 --- a/doc/source/users/tutorials/1dc/howto.rst +++ b/doc/source/users/tutorials/1dc/howto.rst @@ -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 ` diff --git a/doc/source/users/tutorials/1dc/howto_display.rst b/doc/source/users/tutorials/1dc/howto_display.rst new file mode 100644 index 0000000..d7cd65a --- /dev/null +++ b/doc/source/users/tutorials/1dc/howto_display.rst @@ -0,0 +1,24 @@ +.. _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 `_ +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 | ++------------------------+-----------------------------+ diff --git a/doc/source/users/tutorials/1dc/howto_lightcurve.png b/doc/source/users/tutorials/1dc/howto_lightcurve.png new file mode 100644 index 0000000..1dc5241 Binary files /dev/null and b/doc/source/users/tutorials/1dc/howto_lightcurve.png differ diff --git a/doc/source/users/tutorials/1dc/howto_lightcurve.rst b/doc/source/users/tutorials/1dc/howto_lightcurve.rst index d5d40f1..a44616c 100644 --- a/doc/source/users/tutorials/1dc/howto_lightcurve.rst +++ b/doc/source/users/tutorials/1dc/howto_lightcurve.rst @@ -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 ` +or a +:ref:`observation definition XML file `. +: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 `_ Python module for display. + You may reproduce the plot by typing + + .. code-block:: bash + + $ $CTOOLS/share/examples/python/show_lightcurve.py lightcurve.fits diff --git a/doc/source/users/tutorials/1dc/howto_vo.rst b/doc/source/users/tutorials/1dc/howto_vo.rst new file mode 100644 index 0000000..945aaa3 --- /dev/null +++ b/doc/source/users/tutorials/1dc/howto_vo.rst @@ -0,0 +1,103 @@ +.. _1dc_howto_vo: + +How to use Virtual Observatory tools with ctools? +------------------------------------------------- + +Several ctools can interact with Virtual Observatory tools such as +`Aladin `_ +or +`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 `_ +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 `_ +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 `_ +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 `_. + ++-------------------+--------+-------------------+ +| 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 | ++-------------------+--------+-------------------+ + + + diff --git a/doc/source/users/tutorials/1dc/howto_vo_aladin_after.png b/doc/source/users/tutorials/1dc/howto_vo_aladin_after.png new file mode 100644 index 0000000..a936d6f Binary files /dev/null and b/doc/source/users/tutorials/1dc/howto_vo_aladin_after.png differ diff --git a/doc/source/users/tutorials/1dc/howto_vo_aladin_before.png b/doc/source/users/tutorials/1dc/howto_vo_aladin_before.png new file mode 100644 index 0000000..453c104 Binary files /dev/null and b/doc/source/users/tutorials/1dc/howto_vo_aladin_before.png differ diff --git a/doc/source/users/tutorials/1dc/howto_vo_aladin_catalog.png b/doc/source/users/tutorials/1dc/howto_vo_aladin_catalog.png new file mode 100644 index 0000000..848a96b Binary files /dev/null and b/doc/source/users/tutorials/1dc/howto_vo_aladin_catalog.png differ -- libgit2 0.21.4