Update reference manual documentation.

Jürgen Knödlseder
1 parent 18e3d77f
Showing 13 changed files with 86 additions and 34 deletions
doc/source/reference_manual/cscaldb.rst
doc/source/reference_manual/ctbin.rst
doc/source/reference_manual/ctbkgcube.rst
doc/source/reference_manual/ctbutterfly.rst
doc/source/reference_manual/ctcubemask.rst
doc/source/reference_manual/cterror.rst
doc/source/reference_manual/ctexpcube.rst
doc/source/reference_manual/ctlike.rst
doc/source/reference_manual/ctmodel.rst
doc/source/reference_manual/ctobssim.rst
doc/source/reference_manual/ctpsfcube.rst
doc/source/reference_manual/ctselect.rst
doc/source/reference_manual/ctskymap.rst
-.. _cscaldb:

cscaldb
=======

Dumps all available instrument response functions into log file.


Synopsis
--------

This scripts dumps all instrument response functions that are available
in the calibration database into the log file. If you want the information
on the screen, add the ``debug=yes`` parameter.


General parameters
------------------

None
 	 	 

Standard parameters
-------------------

``(chatter = 2) [integer]``
    Verbosity of the executable:
     chatter = 0: no information will be logged
     
     chatter = 1: only errors will be logged
     
     chatter = 2: errors and actions will be logged
     
     chatter = 3: report about the task execution
     
     chatter = 4: detailed report about the task execution
 	 	 
``(clobber = yes) [boolean]``
    Specifies whether an existing output counts cube should be overwritten.
 	 	 
``(debug = no) [boolean]``
    Enables debug mode. In debug mode the executable will dump any log file output to the console.
 	 	 
``(mode = ql) [string]``
    Mode of automatic parameters (default is "ql", i.e. "query and learn").


Related tools
-------------

None
 \ No newline at end of file
+.. _cscaldb:

cscaldb
=======

Dumps all available instrument response functions into log file.


Synopsis
--------

This scripts dumps all instrument response functions that are available
in the calibration database into the log file. If you want the information
on the screen, add the ``debug=yes`` parameter.


General parameters
------------------

None
 	 	 

Standard parameters
-------------------

``(chatter = 2) [integer]``
    Verbosity of the executable:
     chatter = 0: no information will be logged
     
     chatter = 1: only errors will be logged
     
     chatter = 2: errors and actions will be logged
     
     chatter = 3: report about the task execution
     
     chatter = 4: detailed report about the task execution
 	 	 
``(clobber = yes) [boolean]``
    Specifies whether an existing output counts cube should be overwritten.
 	 	 
``(debug = no) [boolean]``
    Enables debug mode. In debug mode the executable will dump any log file output to the console.
 	 	 
``(mode = ql) [string]``
    Mode of automatic parameters (default is "ql", i.e. "query and learn").


Related tools or scripts
------------------------

None
 \ No newline at end of file
@@ -103,8 +103,8 @@ Standard parameters
     Name of log file.
-Related tools
--------------
+Related tools or scripts
+------------------------
 :doc:`ctexpcube`
 :doc:`ctpsfcube`
@@ -136,7 +136,7 @@ Standard parameters
     Name of log file.
-Related tools
--------------
+Related tools or scripts
+------------------------
 :doc:`ctbin`
@@ -123,8 +123,8 @@ Standard parameters
     Name of log file.
-Related tools
--------------
+Related tools or scripts
+------------------------
 :doc:`ctlike`
 :ref:`ctulimit`
@@ -94,7 +94,7 @@ Standard parameters
     Name of log file.
-Related tools
--------------
+Related tools or scripts
+------------------------
 :doc:`ctbin`
@@ -97,8 +97,8 @@ Standard parameters
     Name of log file.
-Related tools
--------------
+Related tools or scripts
+------------------------
 :ref:`ctlike`
 :ref:`ctulimit`
@@ -127,7 +127,7 @@ Standard parameters
     Name of log file.
-Related tools
--------------
+Related tools or scripts
+------------------------
 :doc:`ctbin`
@@ -123,7 +123,7 @@ Standard parameters
     Name of log file.
-Related tools
--------------
+Related tools or scripts
+------------------------
 None
@@ -163,8 +163,8 @@ Standard parameters
     Name of log file.
-Related tools
--------------
+Related tools or scripts
+------------------------
 :doc:`ctbin`
 :doc:`ctexpcube`
@@ -3,14 +3,39 @@
 ctobssim
 ========
-Simulates CTA events.
+Simulate event list(s).
 Synopsis
 --------
-Generate photon events from astrophysical sources and background events 
-from an instrumental background model.
+This tool simulates event list(s) using the instrument characteristics 
+specified by the instrument response function(s) and an input model. The 
+simulation includes photon events from astrophysical sources and background
+events from an instrumental background model.
+
+By default, ctobssim creates a single event list. ctobssim queries a pointing
+direction, the radius of the simulation region, a time interval, an energy
+interval, an instrumental response function, and an input model. ctobssim uses
+a numerical random number generator for the simulations with a seed value
+provided by the hidden ``seed`` parameter. Changing this parameter for
+subsequent runs will lead to different event samples.
+
+ctobssim performs a safety check on the maximum photon rate for all model 
+components to avoid that the tool locks up and requests huge memory 
+ressources, which may happen if a mistake was made in setting up the input 
+model (for example if an error in the flux units is made). The maximum allowed
+photon rate is controlled by the hidden ``maxrate`` parameter, which by default 
+is set to 1e6.
+
+ctobssim can also generate multiple event lists if an observation definition 
+file is specified on input using the hidden ``inobs`` parameter. In that 
+case, simulation information will be gathered from the file, and for each 
+observation an event list will be created.
+
+For each event file, the simulation parameters will be written as data
+selection keywords to the FITS header. These keywords are mandatory for any
+unbinned maximum likelihood analysis of the event data.
 General parameters
@@ -106,7 +131,7 @@ Standard parameters
     Name of log file.
-Related tools
--------------
+Related tools or scripts
+------------------------
-None
+:doc:`csobsdef`
@@ -134,7 +134,7 @@ Standard parameters
     Name of log file.
-Related tools
--------------
+Related tools or scripts
+------------------------
 :doc:`ctbin`
@@ -3,14 +3,36 @@
 ctselect
 ========
-Performs sub-selections of event data.
+Select events from event list(s).
 Synopsis
 --------
-Creates a new FITS file of selected events from an input event list based
-on spatial, temporal, and energy cuts.
+This tool selects events from one or several event lists. Event selection 
+is based on a circular acceptance region, a time interval and an energy 
+interval. In addition, any expression following the cfitsio syntax can be 
+used for event selection.
+
+Optionally, ctselect may also apply energy thresholds. If ``usethres=DEFAULT``
+is specified, ctselect will extract any save thresholds from the instrument
+response functions, and if they exist, will apply them to the respective 
+event list. Alternatively, if ``usethres=USER`` is specified, ctselect will
+extract any user thresholds from the observation definition file (attributes
+``emin`` and ``emax``), and if either of the attributes exists, will apply
+them to the respective event list.
+
+If an event list is provided on input, ctselect creates a new FITS file on 
+output that contains only the selected events. In case that an observation 
+definition file is specified on input, ctselect creates for each event file
+referenced in the observation definition file a new FITS file with the value
+of ``prefix`` prepended to the file name that contains only the selected
+events. In addition, a new observation definition file will be written 
+that references the new FITS files.
+
+For each event file, the event selection parameters will be writted as data
+selection keywords to the FITS header. These keywords are mandatory for any
+unbinned maximum likelihood analysis of the event data.
 General parameters
@@ -98,7 +120,7 @@ Standard parameters
     Name of log file.
-Related tools
--------------
+Related tools or scripts
+------------------------
 None
@@ -3,13 +3,18 @@
 ctskymap
 ========
-Computes sky map from CTA data.
+Generate sky map from event list(s).
 Synopsis
 --------
-This tool generates a sky map from CTA data.
+This tool creates a sky map from either a single event list or event lists
+provided in an observation definition file. The tool will loop over all event
+lists that are provided and fill all events into a single sky map. Only events
+within an energy interval spanned by ``emin`` and ``emax`` are considered.
+
+ctskymap generates a FITS file comprising a sky map as primary extension.
 General parameters
@@ -80,7 +85,7 @@ Standard parameters
     Name of log file.
-Related tools
--------------
+Related tools or scripts
+------------------------
 None