Andreas Specovius / ctools

Commit 527a4d1fadb89dd71d13b5671313994305b06e4f

Authored by Jürgen Knödlseder
1 parent a5d5b18e

Update reference manual documentation.

Inline Side-by-side
Showing 6 changed files with 123 additions and 31 deletions
doc/source/reference_manual/cscaldb.rst
  View file @527a4d1
1   -.. _cscaldb: cscaldb ======= Dumps all available instrument response functions into log fil. Synopsis -------- This scripts dumps all instrument response functions that are available in the calibration database into the log file. If you want the information on the screen, add the ``debug=yes`` parameter. General parameters ------------------ None Standard parameters ------------------- ``(chatter = 2) [integer]`` Verbosity of the executable: chatter = 0: no information will be logged chatter = 1: only errors will be logged chatter = 2: errors and actions will be logged chatter = 3: report about the task execution chatter = 4: detailed report about the task execution ``(clobber = yes) [boolean]`` Specifies whether an existing output counts cube should be overwritten. ``(debug = no) [boolean]`` Enables debug mode. In debug mode the executable will dump any log file output to the console. ``(mode = ql) [string]`` Mode of automatic parameters (default is "ql", i.e. "query and learn"). Related tools ------------- None
2 1 \ No newline at end of file
  2 +.. _cscaldb: cscaldb ======= Dumps all available instrument response functions into log file. Synopsis -------- This scripts dumps all instrument response functions that are available in the calibration database into the log file. If you want the information on the screen, add the ``debug=yes`` parameter. General parameters ------------------ None Standard parameters ------------------- ``(chatter = 2) [integer]`` Verbosity of the executable: chatter = 0: no information will be logged chatter = 1: only errors will be logged chatter = 2: errors and actions will be logged chatter = 3: report about the task execution chatter = 4: detailed report about the task execution ``(clobber = yes) [boolean]`` Specifies whether an existing output counts cube should be overwritten. ``(debug = no) [boolean]`` Enables debug mode. In debug mode the executable will dump any log file output to the console. ``(mode = ql) [string]`` Mode of automatic parameters (default is "ql", i.e. "query and learn"). Related tools ------------- None
3 3 \ No newline at end of file
... ...
doc/source/reference_manual/csobsdef.rst
  View file @527a4d1
... ... @@ -46,8 +46,8 @@ Here some usage examples:
46 46 Creates observation definition file with a ROI radius of 5 deg.
47 47  
48 48 ``csobsdef caldb=prod2 irf=South_50h``
49   - Creates observation definition file using the "South_50h" IRF in the
50   - "prod2" calibration database.
  49 + Creates observation definition file using the ``South_50h`` IRF in the
  50 + ``prod2`` calibration database.
51 51  
52 52  
53 53 General parameters
... ...
doc/source/reference_manual/ctbin.rst
  View file @527a4d1
... ... @@ -3,18 +3,27 @@
3 3 ctbin
4 4 =====
5 5  
6   -Generate a counts cube for binned maximum likelihood analysis.
  6 +Generate counts cube from event list(s).
7 7  
8 8  
9 9 Synopsis
10 10 --------
11 11  
12   -This tool computes the counts cube for use in a binned maximum likelihood
13   -analysis. The counts cubes are 3-dimensional data cubes spanned by Right
14   -Ascension or Galactic longitude, Declination or Galactic latitude, and energy.
15   -The energy binning may be either linear, logarithmic, or custom defined.
16   -If an observation definition XML file containing several observations is
17   -provided on input, the tool will stack all data into a single counts cube.
  12 +This tool creates a counts cube and fills it with events. A counts cube is
  13 +a 3-dimensional data cube spanned by Right Ascension or Galactic longitude,
  14 +Declination or Galactic latitude, and energy. The energy binning may be either
  15 +linear, logarithmic, or custom defined using an input file. The events are
  16 +either taken from a single event list file or from the event lists that are
  17 +specified in an observation definition file. In case that multiple event
  18 +lists are given in an observation definition file, the tool will loop over
  19 +all event lists and fill all events into a single counts cube.
  20 +
  21 +ctbin generates a counts cube FITS file comprising three extensions. The
  22 +primary extension contains a 3-dimensional image that contains the counts
  23 +cube values. The next extension named ``EBOUNDS`` contains a binary table
  24 +that defines the energy boundaries of the counts cube. The last extension
  25 +named ``GTI`` contains a binary table that defines the Good Time Intervals
  26 +of all event lists that have been filled into the counts cube.
18 27  
19 28  
20 29 General parameters
... ...
doc/source/reference_manual/ctbkgcube.rst
  View file @527a4d1
... ... @@ -3,24 +3,55 @@
3 3 ctbkgcube
4 4 =========
5 5  
6   -Generate a background cube for binned maximum likelihood analysis.
  6 +Generate background cube for a counts cube.
7 7  
8 8  
9 9 Synopsis
10 10 --------
11 11  
12   -This tool generates a background cube for use in a binned maximum
13   -likelihood analysis.
  12 +This tool generates a background cube for a counts cube based on an input
  13 +model. A background cube is a 3-dimensional cube spanned by Right Ascension
  14 +or Galactic longitude, Declination or Galactic latitude, and energy. The
  15 +energy binning may be either linear, logarithmic, or custom defined using an
  16 +input file. The input model is used to predict the expected number of
  17 +background counts in each background cube bin.
  18 +
  19 +ctbkgcube requires on input the event list or observation definition file
  20 +that has been used in the generation of the counts cube using :doc:`ctbin`.
  21 +
  22 +To assure consistency between an existing counts cube and the
  23 +corresponding background cube, it is recommended to specify the counts
  24 +cube as ``incube`` parameter. This will instruct ctbkgcube to extract the
  25 +background cube definition (such as sky coordinates and projection, number
  26 +of pixels, pixel scale, energy binning) from the counts cube.
  27 +
  28 +ctbkgcube generates a background cube FITS file comprising two extensions.
  29 +The primary extension contains a 3-dimensional image that contains the
  30 +background cube values. The next extension named ``EBOUNDS`` contains a
  31 +binary table that defines the energy boundaries of the background cube.
  32 +
  33 +ctbkgcube generates also an output model XML file that can serve as input
  34 +for a maximum likelihood analysis. The output model XML file is a copy of
  35 +the input model XML file where the input background model has been replaced
  36 +by a background model of type ``CTACubeBackground``. The ``CTACubeBackground``
  37 +background model instructs any tool analysing binned data to extract
  38 +background information from a background cube. The ``CTACubeBackground``
  39 +model has a spectral component that can be adjusted in a maximum
  40 +likelihood fit to accomodate for uncertainties in the prediction of the
  41 +energy dependence of the background rate. ctbkgcube will use a power law
  42 +as spectral component, but you can replace this by any component of your
  43 +choice.
  44 +
14 45  
15 46  
16 47 General parameters
17 48 ------------------
18 49  
19 50 ``inobs [file]``
20   - Input event list, cube or observation definition XML file.
  51 + Input event list or observation definition XML file.
21 52  
22 53 ``inmodel [file]``
23   - Input (background) model XML file.
  54 + Input model XML file.
24 55  
25 56 ``incube [file]``
26 57 Counts cube for background cube definition.
... ... @@ -28,11 +59,14 @@ General parameters
28 59 ``outcube [file]``
29 60 Output background cube file.
30 61  
  62 +``outmodel [file]``
  63 + Output model XML file.
  64 +
31 65 ``caldb [string]``
32 66 Calibration database.
33 67  
34 68 ``irf [string]``
35   - Response function.
  69 + Instrument response function.
36 70  
37 71 ``ebinalg <FILE|LIN|LOG> [string]``
38 72 Algorithm for defining energy bins.
... ... @@ -105,4 +139,4 @@ Standard parameters
105 139 Related tools
106 140 -------------
107 141  
108   -None
  142 +:doc:`ctbin`
... ...
doc/source/reference_manual/ctexpcube.rst
  View file @527a4d1
... ... @@ -3,14 +3,39 @@
3 3 ctexpcube
4 4 =========
5 5  
6   -Generate an exposure cube for binned maximum likelihood analysis.
  6 +Generate exposure cube for a counts cube.
7 7  
8 8  
9 9 Synopsis
10 10 --------
11 11  
12   -This tool generates an exposure cube for use in a binned maximum likelihood
13   -analysis.
  12 +This tool generates an exposure cube for a counts cube. An exposure cube is
  13 +a 3-dimensional cube spanned by Right Ascension or Galactic longitude,
  14 +Declination or Galactic latitude, and energy, that gives the exposure
  15 +as function of true sky direction and energy. The energy binning of the cube
  16 +may be either linear, logarithmic, or custom defined using an input file.
  17 +
  18 +ctexpcube requires on input the event list or observation definition file
  19 +that has been used in the generation of the counts cube using :doc:`ctbin`.
  20 +
  21 +For the user's convenience, the counts cube can be specified as ``incube``
  22 +parameter which will instruct ctexpcube to extract the exposure cube
  23 +definition (such as sky coordinates and projection, number of pixels, pixel
  24 +scale, energy binning) from the counts cube. Note, however, that the exposure
  25 +cube is defined in true sky coordinates and energy while the counts cube is
  26 +defined in measured sky coordinates and energy. Consequently, the sky area
  27 +and energy range covered by the exposure cube should be slightly larger than
  28 +that of the counts cube to accomodate for spill over of events due to the
  29 +point spread function and energy dispersion. By computing the exposure map
  30 +on the same grid as the counts cube, the spill over of events from sources at
  31 +the edge of cube will not be handled correctly.
  32 +
  33 +ctexpcube generates an exposure cube FITS file comprising three extensions.
  34 +The primary extension contains a 3-dimensional image that contains the
  35 +exposure values. The next extension named ``EBOUNDS`` contains a binary table
  36 +that defines the energy boundaries of the exposure cube. The last extension
  37 +named ``GTI`` contains a binary table that defines the Good Time Intervals
  38 +of the exposure cube.
14 39  
15 40  
16 41 General parameters
... ... @@ -20,7 +45,7 @@ General parameters
20 45 Input event list or observation definition XML file.
21 46  
22 47 ``incube [file]``
23   - Counts cube for PSF cube definition.
  48 + Counts cube for exposure cube definition.
24 49  
25 50 ``outcube [file]``
26 51 Output exposure cube file.
... ... @@ -29,7 +54,7 @@ General parameters
29 54 Calibration database.
30 55  
31 56 ``irf [string]``
32   - Response function.
  57 + Instrument response function.
33 58  
34 59 ``(edisp = no) [boolean]``
35 60 Apply energy dispersion for response computation?
... ... @@ -105,4 +130,4 @@ Standard parameters
105 130 Related tools
106 131 -------------
107 132  
108   -None
  133 +:doc:`ctbin`
... ...
doc/source/reference_manual/ctpsfcube.rst
  View file @527a4d1
... ... @@ -3,15 +3,39 @@
3 3 ctpsfcube
4 4 =========
5 5  
6   -Generate a point spread function cube for binned maximum likelihood
7   -analysis.
  6 +Generate point spread function cube for a counts cube.
8 7  
9 8  
10 9 Synopsis
11 10 --------
12 11  
13   -This tool generates a point spread function cube for use in a binned
14   -maximum likelihood analysis.
  12 +This tool generates a point spread function cube for a counts cube. A point
  13 +spread function cube is a 4-dimensional cube spanned by Right Ascension or
  14 +Galactic longitude, Declination or Galactic latitude, energy, and offset
  15 +angle between true and measured arrival direction of a photon. The energy
  16 +binning of the cube may be either linear, logarithmic, or custom defined
  17 +using an input file.
  18 +
  19 +ctpsfcube requires on input the event list or observation definition file
  20 +that has been used in the generation of the counts cube using :doc:`ctbin`.
  21 +
  22 +It is not recommended to use the counts cube for the point spread function
  23 +cube definition, although this is formally possibly by specifying the counts
  24 +cube as ``incube`` parameter. This leads however to a large FITS file on
  25 +output since the number of bins in the counts cube will be multiplied by
  26 +the number of offset angle bins (typically 200). Since the point spread
  27 +function varies only little over the field of fiew of the camera it is
  28 +recommended to use a rather coarse spatial binning to keep the file size
  29 +manageable (with a typical value of ``binsz=1.0``).
  30 +
  31 +ctpsfcube generates a point spread function cube FITS file comprising three
  32 +extensions. The primary extension contains a 3-dimensional image that contains
  33 +the point spread function values. The energy and offset angle dimensions
  34 +of the point spread function cube are folded into the 3rd dimension of the
  35 +FITS image. The next extension named ``EBOUNDS`` contains a binary table
  36 +that defines the energy boundaries of the exposure cube. The last extension
  37 +named ``DELTAS`` contains a binary table that defines the offset angles
  38 +between true and measured arrival direction of the photon.
15 39  
16 40  
17 41 General parameters
... ... @@ -21,16 +45,16 @@ General parameters
21 45 Input event list or observation definition XML file.
22 46  
23 47 ``incube [file]``
24   - Counts cube for PSF cube definition.
  48 + Counts cube for point spread function cube definition.
25 49  
26 50 ``outcube [file]``
27   - Output PSF cube file.
  51 + Output point spread function cube file.
28 52  
29 53 ``caldb [string]``
30 54 Calibration database.
31 55  
32 56 ``irf [string]``
33   - Response function.
  57 + Instrument response function.
34 58  
35 59 ``(edisp = no) [boolean]``
36 60 Apply energy dispersion for response computation.
... ... @@ -113,4 +137,4 @@ Standard parameters
113 137 Related tools
114 138 -------------
115 139  
116   -None
  140 +:doc:`ctbin`
... ...