Update reference manual documentation.

Jürgen Knödlseder
1 parent 6f76f0b7
Showing 3 changed files with 52 additions and 20 deletions
doc/source/reference_manual/ctbutterfly.rst
doc/source/reference_manual/ctulimit.rst
src/ctulimit/ctulimit.par
@@ -9,16 +9,31 @@ Computes butterfly diagram for a power law model.
 Synopsis
 --------
-Calculates the confidence band of a power law model, taking into account the
-covariance matrix resulting from a maximum likelihood fit. The tool derives
-the envelope of all power law models whose prefactor and spectral index fall
-within the error ellipse that is associated with the covariance of the 
-parameters. It outputs an ASCII file in column separated value (CSV) format
-containing the results. Each row in the result file corresponds to an energy.
-The columns give the energy in MeV, the fitted intensity in ph/cm2/s/MeV,
-and the minimum and maximum intensity that envelope the power law model 
-with a given confidence (by default a confidence level of 68% is used, but 
-the level can be adjusted using the ``confidence`` parameter).
+This tool calculates a butterfly diagram for a specific source with power law
+spectral model. The butterfly diagram is the envelope of all power law models
+that are within a given confidence limit compatible with the data. By default
+a confidence level of 68% is used, but the level can be adjusted using the 
+hidden ``confidence`` parameter. ctbutterfly computes this envelope by
+evaluating for each energy the minimum and maximum intensity of all power law
+models that fall within the error ellipse of the prefactor and index parameters.
+The error ellipse is derived from the covariance matrix of a maximum likelihood
+fit.
+
+ctbutterfly assumes that the input model (parameter ``inmodel``) has been 
+adjusted using :doc:`ctlike` to the data, but if this is not the case you 
+can request a maximum likelihood fit by setting the hidden parameter ``fit=yes``.
+
+ctbutterfly writes the butterfly diagram into an ASCII file with 4 columns 
+separated by a whitespace. Each row in the result file corresponds to a specific
+energy. The meaning of the columns are:
+
+* Energy in MeV
+* Fitted intensity for that energy in ph/cm2/s/MeV
+* Minimum intensity for that energy in ph/cm2/s/MeV
+* Maximum intensity for that energy in ph/cm2/s/MeV
+
+The butterfly diagram can be displayed using the ``show_butterfly.py`` script
+in the example folder.
 General parameters
@@ -54,8 +69,9 @@ General parameters
 ``outfile [file]``
     Output butterfly ASCII file name.
-``(refit = no) [boolean]``
-    Performs refitting of solution ignoring any provided covariance matrix.
+``(fit = no) [boolean]``
+    Performs maximum likelihood fitting of input model ignoring any provided
+    covariance matrix.
 ``(confidence = 0.68) [real]``
     Confidence level for error computation.
@@ -110,5 +126,6 @@ Standard parameters
 Related tools
 -------------
+:doc:`ctlike`
 :ref:`ctulimit`
 :ref:`cterror`
 .. _ctulimit:
 ctulimit
-===========
+========
-Computes upper limit for a specific sky model component.
+Computes upper flux limit for a source model.
 Synopsis
 --------
-Computes the upper limit flux of a given source.
+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
+using the hidden ``confidence`` parameter.
+
+ctulimit writes the differential upper flux limit at a given reference 
+energy (specified by the hidden parameter ``eref``) and the integrated 
+upper flux limit (specified by the hidden parameters ``emin`` and ``emax``)
+into the log file.
+
 General parameters
@@ -53,11 +64,14 @@ General parameters
     Maximum boundary to start searching for upper limit value.
     Number of standard deviations above best fit value  
+``(eref = 1.0) [real])``
+    Reference energy for differential limit (in TeV).
+ 	 	 
 ``(emin = 1.0) [real])``
-    Minimum energy of flux limits (in TeV).
+    Minimum energy for integral flux limit (in TeV).
 ``(emax = 100) [real]``
-    Maximum energy of flux limits (in TeV).
+    Maximum energy for integral flux limit (in TeV).
 ``(tol = 1e-5) [real]``
     Computation tolerance.
@@ -98,4 +112,5 @@ Standard parameters
 Related tools
 -------------
+:ref:`ctlike`
 :ref:`cterror`
 \ No newline at end of file
@@ -33,9 +33,9 @@ edisp,    b, h, no,,, &quot;Apply energy dispersion?&quot;
 confidence, r, h, 0.95,0.0,1.0, "Confidence level"
 sigma_min,  r, h, 0.0,,, "Start minimum value (multiple sigmas above fit value)"
 sigma_max,  r, h, 10.0,,, "Start maximum value (multiple sigmas above fit value)"
-eref,       r, h, 1.0,,, "Reference energy for differential limits (TeV)"
-emin,       r, h, 1.0,,, "Minimum energy for flux limits (TeV)"
-emax,       r, h, 100.0,,, "Maximum energy for flux limits (TeV)"
+eref,       r, h, 1.0,,, "Reference energy for differential limit (TeV)"
+emin,       r, h, 1.0,,, "Minimum energy for integral flux limit (TeV)"
+emax,       r, h, 100.0,,, "Maximum energy for integral flux limit (TeV)"
 tol,        r, h, 1e-5,,, "Computation tolerance"
 max_iter,   i, h, 50,,, "Maximum number of iterations"