Update reference manual documentation.

Jürgen Knödlseder
1 parent adc3a676
Showing 5 changed files with 103 additions and 47 deletions
doc/source/reference_manual/ctbkgcube.rst
doc/source/reference_manual/ctexpcube.rst
doc/source/reference_manual/ctlike.rst
doc/source/reference_manual/ctmodel.rst
doc/source/reference_manual/ctpsfcube.rst
@@ -54,7 +54,7 @@ General parameters
     Input model XML file.
 ``incube [file]``
-    Counts cube for background cube definition.
+    Counts cube file to extract background cube definition.
 ``outcube [file]``
     Output background cube file.
@@ -45,7 +45,7 @@ General parameters
     Input event list or observation definition XML file.
 ``incube [file]``
-    Counts cube for exposure cube definition.
+    Counts cube file to extract exposure cube definition.
 ``outcube [file]``
     Output exposure cube file.
@@ -3,26 +3,54 @@
 ctlike
 ======
-Performs binned and unbinned maximum likelihood analysis of CTA data.
+Perform maximum likelihood model fitting.
 Synopsis
 --------
-Determines the flux, spectral index, position or extent of gamma-ray
-sources using maximum likelihood model fitting of CTA data. The analysis
-can be done in a binned or an unbinned formulation of the log-likelihood
-function. For binned analysis, a counts cube produced by :doc:`ctbin` is
-required. If several observations have been stacked into a single counts
-cube, an exposure cube, a PSF cube and a background cube have to be
-provided. For a single observation it is sufficient to specify the
-instrument response function. For unbinned analysis, an event list
-processed by :doc:`ctselect` is required. Based on files specified on
-input, ctlike automatically selects between binned or unbinned analysis.
-The tool can also be applied to lists of observations, specified in form
-of an observation definition file in XML format. Events of each observation
-are kept separate, and are associated to their appropriate instrument 
-response function.
+This tool performs a maximum likelihood fitting of a model to unbinned or 
+binned 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.
+
+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. 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 separatly 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, ctlike will use the
+joint likelihood of all the observations for parameter optimisation.
+
+By default, 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 done after an initial fit (parameter ``refit``),
+but normally this is not needed. For all model components that have the
+``tscalc="1"`` attribute set, 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``).
+
+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 can be used as an input model for other ctools.
 General parameters
@@ -32,7 +60,7 @@ General parameters
     Input event list, counts cube or observation definition XML file.
 ``inmodel [string]``
-    Source model input XML file.
+    Input model XML file.
 ``expcube [file]``
     Exposure cube file (only needed for stacked analysis).
@@ -49,16 +77,16 @@ General parameters
 ``irf [string]``
     Instrument response function.
+``(edisp = no) [boolean]``
+    Applies energy dispersion to response computation.
+
 ``outmodel [string]``
-    Source model result XML file with values and uncertainties updated by
+    Output model XML file with values and uncertainties updated by
     the maximum likelihood fit.
 ``(stat = POISSON) [string]``
     Fitting statistics (POISSON or GAUSSIAN; only affects binned analysis).
-``(edisp = no) [boolean]``
-    Applies energy dispersion to response computation.
-
 ``(refit = no) [boolean]``
     Perform refitting of solution after initial fit.
@@ -3,48 +3,67 @@
 ctmodel
 =======
-Computes model counts cube.
+Generate model cube.
 Synopsis
 --------
-This tool computes a model counts cube based on an XML model. The counts
-cube is a 3-dimensional data cube spanned by Right Ascension or Galactic
-longitude, Declination or Galactic latitude, and energy.
+This tool generates a model cube based on an input model. A model cube is
+a 3-dimensional cube providing the number of predicted counts for a model as 
+function of Right Ascension or Galactic longitude, Declination or Galactic
+latitude, and energy. The energy binning may be either linear, logarithmic,
+or custom defined using an input file.
+
+ctmodel requires on input either a counts cube, an event list or an observation
+definition file.
+
+If a counts cube is provided, ctmodel will use the definition of this cube
+(such as sky coordinates and projection, number of pixels, pixel scale,
+energy binning) to compute a model cube. In case that the counts cube combines
+multiple observations (i.e. for a so-called "stacked cube"), an exposure cube,
+a point spread function cube and a background cube have to be provided
+(otherwise you may just enter ``NONE`` when the names of these files are
+queried).
+
+If an event list is provided, ctmodel will query for a counts cube to 
+extract the model cube definition (parameter ``incube``). If no counts cube
+is  provided (``incube=NONE``), ctmodel tools will query for cube definition
+parameters.
+
+If an observation definition file is provided, ctmodel will query for a counts
+cube to extract the model cube definition, unless the observation definition
+file contains a single binned observation (in that case, the counts cube of
+that observation will be used to extract the model cube definition).
+
+ctmodel generates a model cube FITS file comprising three extensions. The
+primary extension contains a 3-dimensional image that contains the model 
+cube values. The next extension named ``EBOUNDS`` contains a binary table
+that defines the energy boundaries of the background cube. The last extension
+named ``GTI`` contains a binary table that defines the Good Time Intervals
+that are covered by the model cube.
 General parameters
 ------------------
-``incube [file]``
-    Input counts cube. If a filename is given the counts cube will be
-    used to define the dimensions of the model cube. The content of
-    the counts cube is not relevant.
+``inobs [file]``
+    Input event list, counts cube or observation definition XML file.
 ``inmodel [string]``
-    Source model XML file.
-
-``outcube [file]``
-    Output model counts cube.
- 	 	 
-``(edisp = no) [boolean]``
-    Apply energy dispersion to response computation.
+    Input model XML file.
-``inobs [file]``
-    Input event list, counts cube or observation definition XML file.
-    This information is needed to determine the observation information
-    (number of observations, duration, liftime, pointing, eventually
-    observation specific instrument response functions, etc.).
+``incube [file]``
+    Input counts cube file to extract model cube definition.
 ``expcube [file]``
-    Exposure cube file (only needed for stacked analysis).
+    Input exposure cube file (only needed for stacked analysis).
 ``psfcube [file]``
-    PSF cube file (only needed for stacked analysis).
+    Input PSF cube file (only needed for stacked analysis).
 ``bkgcube [file]``
-    Background cube file (only needed for stacked analysis).
+    Input background cube file (only needed for stacked analysis).
 ``caldb [string]``
     Calibration database.
@@ -52,6 +71,12 @@ General parameters
 ``irf [string]``
     Instrument response function.
+``(edisp = no) [boolean]``
+    Apply energy dispersion to response computation.
+
+``outcube [file]``
+    Output model cube file.
+ 	 	 
 ``ra [real]``
     Right Ascension of pointing (J2000, in degrees).
@@ -141,4 +166,7 @@ Standard parameters
 Related tools
 -------------
-None
+:doc:`ctbin`
+:doc:`ctexpcube`
+:doc:`ctpsfcube`
+:doc:`ctbkgcube`
@@ -45,7 +45,7 @@ General parameters
     Input event list or observation definition XML file.
 ``incube [file]``
-    Counts cube for point spread function cube definition.
+    Counts cube file to extract point spread function cube definition.
 ``outcube [file]``
     Output point spread function cube file.