Karim Sabri / ctools

Commit 392c2429ccd6b225908f485809db877bd98c4bc5

Authored by Jürgen Knödlseder
1 parent adc3a676

Update reference manual documentation.

Inline Side-by-side
Showing 5 changed files with 103 additions and 47 deletions
doc/source/reference_manual/ctbkgcube.rst
  View file @392c242
... ... @@ -54,7 +54,7 @@ General parameters
54 54 Input model XML file.
55 55  
56 56 ``incube [file]``
57   - Counts cube for background cube definition.
  57 + Counts cube file to extract background cube definition.
58 58  
59 59 ``outcube [file]``
60 60 Output background cube file.
... ...
doc/source/reference_manual/ctexpcube.rst
  View file @392c242
... ... @@ -45,7 +45,7 @@ General parameters
45 45 Input event list or observation definition XML file.
46 46  
47 47 ``incube [file]``
48   - Counts cube for exposure cube definition.
  48 + Counts cube file to extract exposure cube definition.
49 49  
50 50 ``outcube [file]``
51 51 Output exposure cube file.
... ...
doc/source/reference_manual/ctlike.rst
  View file @392c242
... ... @@ -3,26 +3,54 @@
3 3 ctlike
4 4 ======
5 5  
6   -Performs binned and unbinned maximum likelihood analysis of CTA data.
  6 +Perform maximum likelihood model fitting.
7 7  
8 8  
9 9 Synopsis
10 10 --------
11 11  
12   -Determines the flux, spectral index, position or extent of gamma-ray
13   -sources using maximum likelihood model fitting of CTA data. The analysis
14   -can be done in a binned or an unbinned formulation of the log-likelihood
15   -function. For binned analysis, a counts cube produced by :doc:`ctbin` is
16   -required. If several observations have been stacked into a single counts
17   -cube, an exposure cube, a PSF cube and a background cube have to be
18   -provided. For a single observation it is sufficient to specify the
19   -instrument response function. For unbinned analysis, an event list
20   -processed by :doc:`ctselect` is required. Based on files specified on
21   -input, ctlike automatically selects between binned or unbinned analysis.
22   -The tool can also be applied to lists of observations, specified in form
23   -of an observation definition file in XML format. Events of each observation
24   -are kept separate, and are associated to their appropriate instrument
25   -response function.
  12 +This tool performs a maximum likelihood fitting of a model to unbinned or
  13 +binned data. All model parameters marked with the attribute ``free="1"``
  14 +in the input model XML file will be adjusted to the value that maximises
  15 +the probability that the observed data have been drawn from the model.
  16 +The tool can mix the analysis of unbinned and binned data, and is also able
  17 +to perform a joint maximum likelihood analysis of data collected in
  18 +separate observations or with different instruments.
  19 +
  20 +ctlike will automatically switch between unbinned, binned and joint analysis
  21 +on basis of the file provided on input (parameter ``inobs``). Providing an
  22 +event list will lead to an unbinned analysis while providing a counts cube
  23 +will lead to a binned analysis. If several observations have been stacked
  24 +into a single counts cube, an exposure cube, a point spread function cube and
  25 +a background cube need also to be provided. ctlike will automatically prompt
  26 +for these parameters in case that a counts cube is given. Answering ``NONE``
  27 +will ignore the exposure cube, point spread function cube and background cube
  28 +and handle the data as a single observation using the specified instrument
  29 +response function (parameters ``caldb`` and ``irf``).
  30 +
  31 +Multiple observations, including data collected with different instruments,
  32 +can be handled by specifying an observation definition file on input. Each of
  33 +the observations will be kept separatly and associated with its appropriate
  34 +instrument response functions, as opposed to a stacked analysis where average
  35 +response functions, computed using :doc:`ctexpcube`, :doc:`ctpsfcube` and :doc:`ctbkgcube`,
  36 +are used. If an observation definition file is provided, ctlike will use the
  37 +joint likelihood of all the observations for parameter optimisation.
  38 +
  39 +By default, ctlike will use the Poisson statistics for likelihood computation,
  40 +but for binned analysis also Gaussian statistics can be specified (parameter
  41 +``stat``). Optionally, a refit can be done after an initial fit (parameter ``refit``),
  42 +but normally this is not needed. For all model components that have the
  43 +``tscalc="1"`` attribute set, ctlike will also compute the Test Statistics
  44 +value that is a measure of the source significance. Optionally, the spatial
  45 +model parameters can be kept fixed during that computation (parameter
  46 +``fix_spat_for_ts``).
  47 +
  48 +ctlike generates an output model XML file that contains the values of the
  49 +best fitting model parameters. For all free parameters, an ``error`` attribute
  50 +is added that provides the statistical uncertainty in the parameter estimate.
  51 +If computation of the Test Statistics has been requested for a model component,
  52 +a ``ts`` attribute providing the Test Statistics value is added. The output
  53 +model can be used as an input model for other ctools.
26 54  
27 55  
28 56 General parameters
... ... @@ -32,7 +60,7 @@ General parameters
32 60 Input event list, counts cube or observation definition XML file.
33 61  
34 62 ``inmodel [string]``
35   - Source model input XML file.
  63 + Input model XML file.
36 64  
37 65 ``expcube [file]``
38 66 Exposure cube file (only needed for stacked analysis).
... ... @@ -49,16 +77,16 @@ General parameters
49 77 ``irf [string]``
50 78 Instrument response function.
51 79  
  80 +``(edisp = no) [boolean]``
  81 + Applies energy dispersion to response computation.
  82 +
52 83 ``outmodel [string]``
53   - Source model result XML file with values and uncertainties updated by
  84 + Output model XML file with values and uncertainties updated by
54 85 the maximum likelihood fit.
55 86  
56 87 ``(stat = POISSON) [string]``
57 88 Fitting statistics (POISSON or GAUSSIAN; only affects binned analysis).
58 89  
59   -``(edisp = no) [boolean]``
60   - Applies energy dispersion to response computation.
61   -
62 90 ``(refit = no) [boolean]``
63 91 Perform refitting of solution after initial fit.
64 92  
... ...
doc/source/reference_manual/ctmodel.rst
  View file @392c242
... ... @@ -3,48 +3,67 @@
3 3 ctmodel
4 4 =======
5 5  
6   -Computes model counts cube.
  6 +Generate model cube.
7 7  
8 8  
9 9 Synopsis
10 10 --------
11 11  
12   -This tool computes a model counts cube based on an XML model. The counts
13   -cube is a 3-dimensional data cube spanned by Right Ascension or Galactic
14   -longitude, Declination or Galactic latitude, and energy.
  12 +This tool generates a model cube based on an input model. A model cube is
  13 +a 3-dimensional cube providing the number of predicted counts for a model as
  14 +function of Right Ascension or Galactic longitude, Declination or Galactic
  15 +latitude, and energy. The energy binning may be either linear, logarithmic,
  16 +or custom defined using an input file.
  17 +
  18 +ctmodel requires on input either a counts cube, an event list or an observation
  19 +definition file.
  20 +
  21 +If a counts cube is provided, ctmodel will use the definition of this cube
  22 +(such as sky coordinates and projection, number of pixels, pixel scale,
  23 +energy binning) to compute a model cube. In case that the counts cube combines
  24 +multiple observations (i.e. for a so-called "stacked cube"), an exposure cube,
  25 +a point spread function cube and a background cube have to be provided
  26 +(otherwise you may just enter ``NONE`` when the names of these files are
  27 +queried).
  28 +
  29 +If an event list is provided, ctmodel will query for a counts cube to
  30 +extract the model cube definition (parameter ``incube``). If no counts cube
  31 +is provided (``incube=NONE``), ctmodel tools will query for cube definition
  32 +parameters.
  33 +
  34 +If an observation definition file is provided, ctmodel will query for a counts
  35 +cube to extract the model cube definition, unless the observation definition
  36 +file contains a single binned observation (in that case, the counts cube of
  37 +that observation will be used to extract the model cube definition).
  38 +
  39 +ctmodel generates a model cube FITS file comprising three extensions. The
  40 +primary extension contains a 3-dimensional image that contains the model
  41 +cube values. The next extension named ``EBOUNDS`` contains a binary table
  42 +that defines the energy boundaries of the background cube. The last extension
  43 +named ``GTI`` contains a binary table that defines the Good Time Intervals
  44 +that are covered by the model cube.
15 45  
16 46  
17 47 General parameters
18 48 ------------------
19 49  
20   -``incube [file]``
21   - Input counts cube. If a filename is given the counts cube will be
22   - used to define the dimensions of the model cube. The content of
23   - the counts cube is not relevant.
  50 +``inobs [file]``
  51 + Input event list, counts cube or observation definition XML file.
24 52  
25 53 ``inmodel [string]``
26   - Source model XML file.
27   -
28   -``outcube [file]``
29   - Output model counts cube.
30   -
31   -``(edisp = no) [boolean]``
32   - Apply energy dispersion to response computation.
  54 + Input model XML file.
33 55  
34   -``inobs [file]``
35   - Input event list, counts cube or observation definition XML file.
36   - This information is needed to determine the observation information
37   - (number of observations, duration, liftime, pointing, eventually
38   - observation specific instrument response functions, etc.).
  56 +``incube [file]``
  57 + Input counts cube file to extract model cube definition.
39 58  
40 59 ``expcube [file]``
41   - Exposure cube file (only needed for stacked analysis).
  60 + Input exposure cube file (only needed for stacked analysis).
42 61  
43 62 ``psfcube [file]``
44   - PSF cube file (only needed for stacked analysis).
  63 + Input PSF cube file (only needed for stacked analysis).
45 64  
46 65 ``bkgcube [file]``
47   - Background cube file (only needed for stacked analysis).
  66 + Input background cube file (only needed for stacked analysis).
48 67  
49 68 ``caldb [string]``
50 69 Calibration database.
... ... @@ -52,6 +71,12 @@ General parameters
52 71 ``irf [string]``
53 72 Instrument response function.
54 73  
  74 +``(edisp = no) [boolean]``
  75 + Apply energy dispersion to response computation.
  76 +
  77 +``outcube [file]``
  78 + Output model cube file.
  79 +
55 80 ``ra [real]``
56 81 Right Ascension of pointing (J2000, in degrees).
57 82  
... ... @@ -141,4 +166,7 @@ Standard parameters
141 166 Related tools
142 167 -------------
143 168  
144   -None
  169 +:doc:`ctbin`
  170 +:doc:`ctexpcube`
  171 +:doc:`ctpsfcube`
  172 +:doc:`ctbkgcube`
... ...
doc/source/reference_manual/ctpsfcube.rst
  View file @392c242
... ... @@ -45,7 +45,7 @@ General parameters
45 45 Input event list or observation definition XML file.
46 46  
47 47 ``incube [file]``
48   - Counts cube for point spread function cube definition.
  48 + Counts cube file to extract point spread function cube definition.
49 49  
50 50 ``outcube [file]``
51 51 Output point spread function cube file.
... ...