Add On/Off analysis to ctlike reference manual (#3154)

Jürgen Knödlseder
1 parent 7da6e885
Showing 4 changed files with 47 additions and 31 deletions
ChangeLog
NEWS
doc/source/admin/release_history/1.7.rst
doc/source/users/reference_manual/ctlike.rst
@@ -5,6 +5,7 @@
  
         Add Interface Manual to User documentation (#3163)
         Adapt show_pull_histogram.py to matplotlib > 3.1.0 (#3156)
+        Add On/Off analysis to ctlike reference manual (#3154)
         Avoid negative squared standard deviations in cssrcdetect
         Update user manual for latest CTA IRF (#3075)
         Fix log file header repetition in some cscripts (#3066)
@@ -19,6 +19,8 @@ Documentation
 Add Interface Manual to User documentation that provides links to the
 ctools and GammaLib Doxygen documentation (#3163).
  
+Add On/Off analysis to ctlike reference manual (#3154).
+
 Update user manual to indicate where to get the latest CTA IRF (#3075).
  
  
@@ -29,6 +29,8 @@ Improvements
  
 * [`3163 <https://cta-redmine.irap.omp.eu/issues/3163>`_] -
   Add Interface Manual to User documentation
+* [`3154 <https://cta-redmine.irap.omp.eu/issues/3154>`_] -
+  Add On/Off analysis to ctlike reference manual
 * [`3075 <https://cta-redmine.irap.omp.eu/issues/3075>`_] -
   Update user manual for latest CTA IRF
 * [`3065 <https://cta-redmine.irap.omp.eu/issues/3065>`_] -
@@ -9,47 +9,58 @@ Perform maximum likelihood model fitting.
 Synopsis
 --------
  
-This tool performs a maximum likelihood fitting of a model to unbinned or 
-binned data. All model parameters marked with the attribute ``free="1"`` 
+This tool performs a maximum likelihood fitting of a model to unbinned, binned
+or On/Off data. All model parameters marked with the attribute ``free="1"``
 in the input model XML file will be adjusted to the value that maximises 
-the probability that the observed data have been drawn from the model.
-The tool can mix the analysis of unbinned and binned data, and is also able
-to perform a joint maximum likelihood analysis of data collected in 
-separate observations or with different instruments.
-
-:ref:`ctlike` will automatically switch between unbinned, binned and joint analysis
-on basis of the file provided on input (parameter ``inobs``). Providing an 
-event list will lead to an unbinned analysis while providing a counts cube 
-will lead to a binned analysis. If several observations have been stacked
-into a single counts cube, an exposure cube, a point spread function cube and
-a background cube need also to be provided. :ref:`ctlike` will automatically prompt
+the probability that the observed data have been drawn from the model. The tool
+can mix the analysis of unbinned, binned and On/Off data, and is also able to
+perform a joint maximum likelihood analysis of data collected in separate
+observations or with different instruments.
+
+:ref:`ctlike` will automatically switch between unbinned, binned, On/Off and joint
+analysis on basis of the file provided on input (parameter ``inobs``). Providing
+an event list will lead to an unbinned analysis while providing a counts cube
+will lead to a binned analysis. If several observations have been stacked into a
+single counts cube, an exposure cube, a point spread function cube and a
+background cube need also to be provided. :ref:`ctlike` will automatically prompt
 for these parameters in case that a counts cube is given. Answering ``NONE``
 will ignore the exposure cube, point spread function cube and background cube
 and handle the data as a single observation using the specified instrument
 response function (parameters ``caldb`` and ``irf``).
  
-Multiple observations, including data collected with different instruments,
-can be handled by specifying an observation definition file on input. Each of
-the observations will be kept separately and  associated with its appropriate
-instrument response functions, as opposed to a stacked analysis where average
-response functions, computed using :doc:`ctexpcube`, :doc:`ctpsfcube` and :doc:`ctbkgcube`,
-are used. If an observation definition file is provided, :ref:`ctlike` will use the
-joint likelihood of all the observations for parameter optimisation.
-
-By default, :ref:`ctlike` will use the Poisson statistics for likelihood computation,
-but for binned analysis also Gaussian statistics can be specified (parameter
-``stat``). Optionally, a refit can be requested after an initial fit (parameter
-``refit``), but normally this is not needed. For all model components that
-have the ``tscalc="1"`` attribute set, :ref:`ctlike` will also compute the Test
-Statistics value that is a measure of the source significance. Optionally,
-the spatial model parameters can be kept fixed during that computation
-(parameter ``fix_spat_for_ts``).
+Providing an observation definition XML file containing an On/Off observation
+will trigger an On/Off analysis. Multiple observations, including data collected
+with different instruments, can also be handled by specifying an observation
+definition XML file on input. Each of the observations will be kept separately
+and associated with its appropriate instrument response functions, as opposed to
+a stacked analysis where average response functions, computed using :doc:`ctexpcube`,
+:doc:`ctpsfcube` and :doc:`ctbkgcube`, are used. If an observation definition XML
+file is provided, :ref:`ctlike` will use the joint likelihood of all the
+observations for parameter optimisation.
+
+By default, :ref:`ctlike` will use the Poisson statistic for likelihood computation,
+but for binned analysis also Gaussian statistic can be specified (parameter
+``statistic``). In case of an On/Off analysis, data can be fitted using either the
+``CSTAT`` or the ``WSTAT`` statistic. The former will adjust a background model to
+the On and Off data, while the latter will assume that the background rates per
+solid angle are identical in the On and Off regions, and will marginalise over
+the corresponding background rates. The fit statistic can also be specified in
+the observation definition XML file for each observation using the ``statistic``
+attribute.
+
+For all model components that have the ``tscalc="1"`` attribute set in the input
+model XML file, :ref:`ctlike` will also compute the Test Statistic value that is a
+measure of the source significance. Optionally, the spatial model parameters can
+be kept fixed during that computation (parameter ``fix_spat_for_ts``).
+
+Optionally, a refit can be requested after an initial fit (parameter ``refit``),
+but normally this is not needed.
  
 :ref:`ctlike` generates an output model XML file that contains the values of the
 best fitting model parameters. For all free parameters, an ``error`` attribute
 is added that provides the statistical uncertainty in the parameter estimate.
-If computation of the Test Statistics has been requested for a model component,
-a ``ts`` attribute providing the Test Statistics value is added. The output model
+If computation of the Test Statistic has been requested for a model component,
+a ``ts`` attribute providing the Test Statistic value is added. The output model
 can be used as an input model for other ctools.
  
 In addition, the covariance matrix can be saved into a file by specifying a