From a7737cd8346843590d26adbf586baf2926bc037f Mon Sep 17 00:00:00 2001 From: Jürgen Knödlseder Date: Wed, 15 Jul 2020 12:28:37 +0200 Subject: [PATCH] Add On/Off analysis to ctlike reference manual (#3154) --- ChangeLog | 1 + NEWS | 2 ++ doc/source/admin/release_history/1.7.rst | 2 ++ doc/source/users/reference_manual/ctlike.rst | 73 ++++++++++++++++++++++++++++++++++++++++++------------------------------- 4 files changed, 47 insertions(+), 31 deletions(-) diff --git a/ChangeLog b/ChangeLog index d1743b8..c525841 100755 --- a/ChangeLog +++ b/ChangeLog @@ -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) diff --git a/NEWS b/NEWS index 272c1f0..6b55476 100755 --- a/NEWS +++ b/NEWS @@ -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). diff --git a/doc/source/admin/release_history/1.7.rst b/doc/source/admin/release_history/1.7.rst index 72a54e4..937d657 100644 --- a/doc/source/admin/release_history/1.7.rst +++ b/doc/source/admin/release_history/1.7.rst @@ -29,6 +29,8 @@ Improvements * [`3163 `_] - Add Interface Manual to User documentation +* [`3154 `_] - + Add On/Off analysis to ctlike reference manual * [`3075 `_] - Update user manual for latest CTA IRF * [`3065 `_] - diff --git a/doc/source/users/reference_manual/ctlike.rst b/doc/source/users/reference_manual/ctlike.rst index 9ce1e50..43b092e 100755 --- a/doc/source/users/reference_manual/ctlike.rst +++ b/doc/source/users/reference_manual/ctlike.rst @@ -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 -- libgit2 0.21.4