Update the User documentation

Jürgen Knödlseder
1 parent 54ac6307
Showing 13 changed files with 132 additions and 28 deletions
doc/source/users/reference_manual/csroot2caldb.rst
doc/source/users/reference_manual/index.rst
doc/source/users/user_manual/getting_started/index.rst
doc/source/users/user_manual/index.rst
doc/source/users/user_manual/introduction.rst
doc/source/users/user_manual/getting_started/irf-aeff.png → doc/source/users/user_manual/irf-aeff.png
doc/source/users/user_manual/getting_started/irf-file.png → doc/source/users/user_manual/irf-file.png
doc/source/users/user_manual/getting_started/irfs.jpg → doc/source/users/user_manual/irfs.jpg
doc/source/users/user_manual/getting_started/model_lightcurve.png → doc/source/users/user_manual/model_lightcurve.png
doc/source/users/user_manual/getting_started/model_phasecurve.png → doc/source/users/user_manual/model_phasecurve.png
doc/source/users/user_manual/getting_started/models.rst → doc/source/users/user_manual/models.rst
doc/source/users/user_manual/getting_started/python.rst → doc/source/users/user_manual/python.rst
doc/source/users/user_manual/getting_started/response.rst → doc/source/users/user_manual/response.rst
+.. _csroot2caldb:
+
+csroot2caldb
+============
+
+Creates a caldb entry from a ROOT performance file.
+
+
+Synopsis
+--------
+
+This script creates an entry in the local calibration database from a ROOT
+performance file.
+
+
+General parameters
+------------------
+
+``infile [file]``
+    Input ROOT performance file file.
+
+``(outdir = ) [string]``
+    Output CALDB directory.
+
+``inst [string]``
+    Instrument name.
+
+``id [string]``
+    Instrument Response Function identifier.
+
+``version [string]``
+    Instrument Response Function version.
+
+``analysis [string]``
+    Instrument Response Function analysis.
+
+``zenith [real]``
+    Zenith angle (in degrees).
+
+``azimuth [real]``
+    Azimuth angle (in degrees).
+
+``(emin = UNDEF) [real]``
+    Minimum energy threshold (TeV).
+
+``(emax = UNDEF) [real]``
+    Maximum energy threshold (TeV).
+
+``(psftype = Gauss) [string]``
+    Point spread function type.
+
+``(split = no) [boolean]``
+    Split IRF components into different files.
+
+``(norm1d = no) [boolean]``
+    Normalize on 1D histograms.
+
+``(rebin = no) [boolean]``
+    Rebin.
+
+``(eascale = 1.0) [real]``
+    Scaling factor for effective areas.
+
+``(bgdscale = 1.0) [real]``
+    Scaling factor for background rates.
+
+``(bgdoversample = 1) [integer]``
+    Spatial oversampling factor for background template.
+
+``(bgdethres = 1000.0) [real]``
+    Energy above which to replace background by power law (TeV).
+
+``(bgdinfill = no) [boolean]``
+    Infill of background template?.
+
+
+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 file 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").
+
+``(logfile = csroot2caldb.log) [filename]``
+    Log filename.
+
+
+Related tools or scripts
+------------------------
+
+:doc:`cscaldb`
@@ -53,6 +53,7 @@ cscripts
    csphasecrv --- Computes phase curve <csphasecrv>
    cspull --- Generates pull distribution <cspull>
    csresmap --- Generates residual map <csresmap>
+   csroot2caldb --- Creates a caldb entry from a ROOT file <csroot2caldb>
    cssens --- Computes CTA sensitivity <cssens>
    csspec --- Computes spectral points <csspec>
    cssrcdetect --- Detects sources in sky map <cssrcdetect>
-.. _sec_using:
-
-Using ctools
-============
-
-.. toctree::
-   :maxdepth: 1
-
-   python
-   models
-   response
-
-===========
+.. _sec_user_manual:
+
 User Manual
 ===========
@@ -6,6 +7,7 @@ User Manual
    :maxdepth: 1
    introduction
-   getting_started/index
+   response
+   models
    plotting
-
+   python
@@ -53,8 +53,7 @@ command line or used as Python classes, as illustrated below:
   >>> import cscripts
   >>> pull = cscripts.cspull()
-In this User Manual you will now learn how to install and use the ctools
-package.
+In this User Manual you will now learn how to use the ctools package.
 If you encounter any problems, please read the :ref:`sec_help` section.
 And you should read the :ref:`sec_develop` section if you would like to
 contribute to the ctools developments.
@@ -303,8 +303,9 @@ Here an example of how to use ``obsutils``:
     Number of predicted events : 0
    >>> obs.models(gammalib.GModels("${CTOOLS}/share/models/crab.xml"))
    >>> obs = obsutils.sim(obs)
-   >>> like = obsutils.fit(obs)
-   >>> print(like.obs().models())   
+   >>> like = ctools.ctlike(obs)
+   >>> like.run()
+   >>> print(like.obs().models())
    === GModels ===
     Number of models ..........: 2
     Number of parameters ......: 10
@@ -320,13 +321,10 @@ cover the 0.1-100 TeV energy range and a field of view of 5°.
 The ``South_0.5h`` IRF from the Prod2 calibration database will be used.
 A model is then appended to the observation container using the
 ``obs.models()`` method.
-The ``obsutils.sim()`` function then simulates the event data, the
-``obsutils.fit()`` function performs a maximum likelihood fit.
-
-.. note::
-
-   The ``obsutils`` module is not yet fully developed and more convenience 
-   functions will be added in the future.
+The ``obsutils.sim()`` function then simulates the event data and returns
+an observation container with the simulated observations.
+The observation container is then passed to ``ctlike`` for maximum likelihood
+fitting.
 Access analysis results
@@ -365,13 +363,21 @@ In the following it is assumed that you have a ctlike object called
   .. code-block:: python
-    like.opt().value() # Returns likelihood value
+    logL = like.opt().value() # Returns log-likelihood value
+    print(logL)
+
+  or alternatively
+
+  .. code-block:: python
+  
+    logL = like.obs().function().value() # Returns log-likelihood value
+    print(logL)
 * Curvature Matrix (aka Hessian)
   .. code-block:: python
-    curvature = like.opt().curvature().invert() # Return GMatrix object 
+    curvature = like.obs().function().curvature() # Return GMatrixSparse object
     print(curvature)
   To get the covariance matrix, the curvature matrix needs to be