Implement Luigi's comments on User Manual

Jürgen Knödlseder
1 parent 92a171b6
Showing 6 changed files with 46 additions and 9 deletions
doc/source/users/user_manual/data.rst
doc/source/users/user_manual/introduction.rst
doc/source/users/user_manual/likelihood.rst
doc/source/users/user_manual/models_implementation.rst
doc/source/users/user_manual/models_spatial_src.rst
doc/source/users/user_manual/models_temporal.rst
@@ -16,7 +16,7 @@ is shown below.
 Metadata, such as the telescope pointing direction, the live time, or any other
 information that may be relevant for data processing, is stored in the FITS
-header of the event list binary table. An exemple for the metadata that is
+header of the event list binary table. An example for the metadata that is
 included in the header of the H.E.S.S. Collaboration event lists is shown
 below.
@@ -27,7 +27,7 @@ below.
 Every event list needs to be accompanied by a table with so-called
 :ref:`Good Time Intervals (GTIs) <glossary_gti>` where each row corresponds
 to a time interval of continuous data taking, and the two columns correspond
-to the start and stop times of these time intervals. An exemple for the GTIs
+to the start and stop times of these time intervals. An example for the GTIs
 of the H.E.S.S. event lists comprising a single GTI is shown below.
 .. figure:: gti.png
@@ -39,3 +39,7 @@ and that the zero-point of the MET is specified by the ``MJDREFI`` and
 ``MJDREFF`` keywords as the integer and fraction part of a Modified Julian Date
 (MJD) in the header of the GTI. The same holds also for the trigger times in
 the event list.
+
+For further information on the data format we recommend to read the
+`Data formats for gamma-ray astronomy <https://gamma-astro-data-formats.readthedocs.io/en/latest/>`_
+document.
@@ -53,9 +53,8 @@ ctools are available through the ``ctools`` module, cscripts through the
 ``cscripts`` module. The following example illustrates how data can be simulated
 from Python:
-.. code-block:: bash
+.. code-block:: python
-   $ python
    >>> import ctools
    >>> sim = ctools.ctobssim()
    >>> sim["ra"]  = 83.63
@@ -65,9 +64,8 @@ from Python:
 And here an example for generating a light curve from Python:
-.. code-block:: bash
+.. code-block:: python
-   $ python
    >>> import cslightcrv
    >>> lightcrv = cscripts.cslightcrv()
    >>> lightcrv.execute()
@@ -94,4 +92,27 @@ execution of a tool a new copy of the par file will be stored in the folder. If
 for some reason a parameter file got corrupt, simply delete it from ``$HOME/pfiles``
 and start again.
+There are two types of user parameters: those that will be queried when starting
+a tool and those that are hidden and not queried. Hidden parameters serve to
+define default values that normally need not to be changed, but exposing the
+parameters in the interface allows to change them by the user for fine tuning
+of a tool. An example for a hidden parameter of :ref:`ctobssim` is the ``seed``
+parameter to set the initial seed value of the random number generator. To set
+a hidden parameter its value has to be specified on the command line. For
+example
+
+.. code-block:: bash
+
+  $ ctobssim seed=41
+will run :ref:`ctobssim` with a seed value of 41. Multiple hidden parameters
+specified on the command line need to be separated by a white space. In the
+Python interface, values of hidden parameters are specified in the same way as
+values of queried parameters, e.g.
+
+.. code-block:: python
+
+   >>> import ctools
+   >>> sim = ctools.ctobssim()
+   >>> sim["seed"] = 41
+   ...
@@ -136,6 +136,8 @@ where
    \alpha = \frac{\int_\mathrm{on} d\Omega}{\int_\mathrm{off} d\Omega}
 is the ratio between the solid angles of the On region and the Off region.
+The terms in the last row are added so that :math:`-2 \ln L(M_s)` follows a
+:math:`\chi^2` distribution.
 Some special cases need to be handled separately in ``wstat``.
 If :math:`n^\mathrm{on}_i = 0` but :math:`n^\mathrm{off}_i > 0` the
@@ -13,7 +13,7 @@ a spatial (tags ``&lt;spatialModel&gt;`` or ``&lt;radialModel&gt;``), and
 a temporal component (tag ``<temporal>``).
 .. math::
-  M(x,y,E,t) = M_{\rm spatial}(x,y|E) \times M_{\rm spectral}(E) \times M_{\rm temporal}(t)
+   M(p,E,t) = M_{\rm spatial}(p|E) \times M_{\rm spectral}(E) \times M_{\rm temporal}(t)
 In this specific example, the source component ``Crab`` describes 
 a point source at the location of the Crab nebula with a power law spectral
@@ -347,8 +347,8 @@ Composite model
   which implements
   .. math::
-     M_{\rm spatial}(x,y|E) = \frac{1}{N} \sum_{i=0}^{N-1} M_{\rm spatial}^{(i)}(x,y|E)
+     M_{\rm spatial}(p|E) = \frac{1}{N} \sum_{i=0}^{N-1} M_{\rm spatial}^{(i)}(p|E)
-  where :math:`M_{\rm spatial}^{(i)}(x,y|E)` is any spatial model component
+  where :math:`M_{\rm spatial}^{(i)}(p|E)` is any spatial model component
   (including another composite model), and :math:`N` is the number of
   model components that are combined.
@@ -6,6 +6,16 @@ Temporal model components
 The following sections present the temporal model components that are available 
 in ctools.
+.. warning::
+   Recall that the model is factorised according to
+
+   .. math::
+      M(p,E,t) = M_{\rm spatial}(p|E) \times M_{\rm spectral}(E) \times M_{\rm temporal}(t)
+
+   which implies that the temporal model component is multiplied with the
+   spectral model component.
+
+
 Constant
 ^^^^^^^^