Update reference manual documentation.

Jürgen Knödlseder
1 parent 50a86942
Showing 7 changed files with 72 additions and 30 deletions
doc/source/reference_manual/ctbutterfly.rst
doc/source/reference_manual/ctcubemask.rst
doc/source/reference_manual/cterror.rst
doc/source/reference_manual/cttsmap.rst
doc/source/reference_manual/ctulimit.rst
src/ctcubemask/ctcubemask.cpp
src/ctcubemask/ctcubemask.par
@@ -46,7 +46,7 @@ General parameters
     Input model XML file.
  
 ``srcname [string]``
-    Name of model component for which butterfly should be computed.
+    Name of source model for which the butterfly diagram should be computed.
  
 ``expcube [file]``
     Input exposure cube file (only needed for stacked analysis).
@@ -3,14 +3,32 @@
 ctcubemask
 ==========
  
-Filter a counts cube.
+Mask out bins of a counts cube.
  
  
 Synopsis
 --------
  
 This tool masks out specific regions from a counts cube by setting the
-corresponding pixels to negative values.
+corresponding bin values to -1. Bins with negative values will be ignored
+in a maximum likelihood analysis. A mask is applied spatially and spectrally.
+
+ctcubemask applies a spatial mask that is comprised of a circular selection
+region and a list of circular exclusion regions. The circular selection region
+is specified by the sky direction of the centre and the radius of the circle.
+The circular exclusion regions are specified by an ASCII file in ds9 format.
+The ASCII file contains one row per exclusion region, given in the format
+
+``circle(83.63, 21.5, 0.4)``
+
+where ``83.63`` and ``21.5`` are the Right Ascension and Declination of 
+the centre and ``0.4`` is the radius (in degrees) of the exclusion circle.
+
+ctcubemask also selects only counts cube energy layers that are fully comprised
+in the energy interval specified by the ``emin`` and ``emax`` parameters.
+
+ctcubemask generates a counts cube FITS file that is a copy of the input 
+counts cube and for which all masked bins have been set to -1.
  
  
 General parameters
@@ -19,9 +37,6 @@ General parameters
 ``inobs [file]``
     Input counts cube or observation definition XML file.
  
-``regfile [file]``
-    Exclusion region file in ds9 format.
-
 ``outcube [file]``
     Output counts cube or observation definition XML file.
  
@@ -41,6 +56,9 @@ General parameters
 ``rad [real]``
     Radius of circular selection region (in degrees).
  
+``regfile [file]``
+    Input exclusion region file in ds9 format.
+
 ``emin [real]``
     Lower energy limit (in TeV).
  
@@ -72,11 +90,11 @@ Standard parameters
 ``(mode = ql) [string]``
     Mode of automatic parameters (default is "ql", i.e. "query and learn").
  
-``(logfile = ctexpcube.log) [string]``
+``(logfile = ctcubemask.log) [string]``
     Name of log file.
  
  
 Related tools
 -------------
  
-None
+:doc:`ctbin`
@@ -3,15 +3,26 @@
 cterror
 =======
  
-Computes parameter errors for a specific sky model component using
-a likelihood profile method.
+Computes parameter errors for a source model from the likelihood profiles.
  
  
 Synopsis
 --------
  
-This tool computes the parameter errors for a specific sky model using
-a likelihood profile method.
+This tool computes the parameter errors for a specific source model using
+the likelihood profiles. Starting from the maximum likelihood model parameters,
+the tool finds the minimum and maximum model parameters that lead to a decrease
+of the likelihood that corresponds to a given confidence level. By default a
+confidence level of 68% is used, but this level can be adjusted using the hidden
+``confidence`` parameter.
+
+cterror 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
+as obtained from the likelihood profile. While cterror computes asymmetrical
+errors, which are written into the log file, the XML file will contain the 
+mean error that is obtained by computing the mean of the negative and the
+positive parameter errors.
  
  
 General parameters
@@ -24,7 +35,7 @@ General parameters
     Input model XML file.
  
 ``srcname [string]``
-    Name of model component for which upper limit should be computed.
+    Name of source model for which the parameter errors should be computed.
  
 ``expcube [file]``
     Input exposure cube file (only needed for stacked analysis).
@@ -89,5 +100,6 @@ Standard parameters
 Related tools
 -------------
  
+:ref:`ctlike`
 :ref:`ctulimit`
 :ref:`ctbutterfly`
@@ -3,13 +3,25 @@
 cttsmap
 =======
  
-Generate a Test Statistic map.
+Generate a Test Statistic (TS) map.
  
  
 Synopsis
 --------
  
-This tool generates a Test Statistic map.
+This tool generates a Test Statistic (TS) map for a specific source model.
+cttsmap works for point, radial and elliptical source models. The tool
+displaces the specified source on a grid of sky directions and computes for
+each direction the TS value for the model. The TS value is defined as twice
+the difference between the log-likelihood obtained for the full model 
+(including the specified source) and the log-likelihood obtained for a model
+that excludes the specified source. The square-root of the TS values 
+corresponds roughly to the pre-trial detection signifiance of the source (in
+Gaussian sigma).
+
+cttsmap generates a FITS file comprising a sky map of TS values followed by 
+one extension per free parameter that contains sky maps of the fitted 
+parameter values.
  
  
 General parameters
@@ -19,11 +31,10 @@ General parameters
     Input event list, counts cube or observation definition XML file.
  
 ``inmodel [file]``
-    Input source model XML file.
+    Input model XML file.
  
 ``srcname [string]``
-    Name of the source in the source model XML file for which the Test
-    Statistic map should be computed.
+    Name of source model for which the TS map should be computed.
  
 ``expcube [file]``
     Input exposure cube file (only needed for stacked analysis).
@@ -38,7 +49,7 @@ General parameters
     Calibration database.
  
 ``irf [string]``
-    Response function.
+    Instrumental response function.
  
 ``(edisp = no) [boolean]``
     Applies energy dispersion to response computation.
@@ -13,7 +13,7 @@ This tools computes the upper flux limit for a specific source model. Except
 of the node function, all spectral models are supported. Starting from the
 maximum likelihood model parameters, the tool finds the model flux that leads
 to a decrease of the likelihood that corresponds to a given confidence level.
-By default a confidence level of 95% is used, but the level can be adjusted
+By default a confidence level of 95% is used, but this level can be adjusted
 using the hidden ``confidence`` parameter.
  
 ctulimit writes the differential upper flux limit at a given reference 
@@ -33,7 +33,7 @@ General parameters
     Input model XML file.
  
 ``srcname [string]``
-    Name of model component for which upper limit should be computed.
+    Name of source model for which the upper flux limit should be computed.
  
 ``expcube [file]``
     Input exposure cube file (only needed for stacked analysis).
@@ -113,4 +113,5 @@ Related tools
 -------------
  
 :ref:`ctlike`
-:ref:`cterror`
 \ No newline at end of file
+:ref:`cterror`
+:ref:`ctbutterfly`
@@ -384,7 +384,7 @@ void ctcubemask::get_parameters(void)
         }
     }
  
-    // Check if radius is vaild for a RoI selection
+    // Check if radius is valid for a RoI selection
     if (m_select_roi && (*this)["rad"].is_valid()) {
        m_rad = (*this)["rad"].real();
     }
@@ -18,19 +18,19 @@
 # General parameters
 #===================
 inobs,   f, a, "cntmap.fits",,, "Input counts cube or observation definition XML file"
-regfile, f, a, "NONE",,, "Exclusion region file in ds9 format"
 outcube, f, a, "filtered_cube.fits",,, "Output counts cube or observation definition XML file"
 prefix,  s, h, "filtered_",,, "Prefix for counts cube in observation definition XML file"
  
 #
 # Selection parameters
 #=====================
-usepnt, b, h, no,,, "Use pointing instead of RA/DEC parameters?"
-ra,     r, a, 83.63,0,360, "RA for ROI centre (degrees)"
-dec,    r, a, 22.01,-90,90, "Dec for ROI centre (degrees)"
-rad,    r, a, 3.0,0,180, "Radius of ROI (degrees)"
-emin,   r, a, 0.1,,, "Lower energy limit (TeV)"
-emax,   r, a, 100.0,,, "Upper energy limit (TeV)"
+usepnt,  b, h, no,,, "Use pointing instead of RA/DEC parameters?"
+ra,      r, a, 83.63,0,360, "RA for ROI centre (degrees)"
+dec,     r, a, 22.01,-90,90, "Dec for ROI centre (degrees)"
+rad,     r, a, 3.0,0,180, "Radius of ROI (degrees)"
+regfile, f, a, "NONE",,, "Input exclusion region file in ds9 format"
+emin,    r, a, 0.1,,, "Lower energy limit (TeV)"
+emax,    r, a, 100.0,,, "Upper energy limit (TeV)"
  
 #
 # Standard parameters