Johan Bregeon / ctools

Commit feaf03a9a85cdf91c2db030051e873402bfe3abc

Authored by Jürgen Knödlseder
1 parent 96b56df9

Update quickstart section for new parameter names.

Inline Side-by-side
Showing 2 changed files with 388 additions and 341 deletions
doc/source/user_manual/getting.rst
  View file @feaf03a
... ... @@ -8,15 +8,15 @@ The procedure for building and installing ctools is modeled on GNU
8 8 software distributions. You will need the following to build the
9 9 software:
10 10  
11   -- Up to TBD free disk space.
  11 +- About 25 MB of free disk space.
12 12  
13   -- ANSI C++ compiler. ctools builds well using GNU g++.
  13 +- An ANSI C++ compiler. ctools builds well using GNU g++ or clang.
14 14  
15   -- make
  15 +- make, automake, autoconf, libtools
16 16  
17 17 - gammalib (see next section).
18 18  
19   -- Python, including the Python developer package that includes the
  19 +- Python, including the Python developer package that provides the
20 20 ``Python.h`` header files. Although ctools compiles without Python and/or
21 21 the Python developer package installed, compiling with Python support
22 22 is highly recommended to enable dynamic scripting of ctools and
... ... @@ -35,45 +35,41 @@ section and continue with Section TBD that explains how to install ctools.
35 35  
36 36 You will need the following to build the gammalib:
37 37  
38   -- About 100 MB of free disk space.
  38 +- About 200 MB of free disk space.
39 39  
40 40 - An ANSI C++ compiler. We recommend building GammaLib with the GNU g++
41   - compiler.
  41 + or the clang compilers.
42 42  
43   -- GNU make
  43 +- make, automake, autoconf, libtools
44 44  
45 45 - The cfitsio library for FITS file support together with the developer
46   - package that includes the ``cfitsio.h`` header.
  46 + package that provides the ``cfitsio.h`` header.
47 47  
48   -- Python, including the Python developer package that includes the
  48 +- Python, including the Python developer package that provides the
49 49 ``Python.h`` header files. Although ctools compiles without Python and/or
50 50 the Python developer package installed, compiling with Python support
51 51 is highly recommended to enable dynamic scripting of ctools and
52 52 developing and using of cscripts.
53 53  
54   -Furthermore it is recommended to have readline and ncurses installed (including
55   -the developer packages)
  54 +Furthermore it is recommended to have readline and ncurses installed
  55 +(including the developer packages).
56 56  
57   -After downloading the gammalib tarball, save it in an appropriate location
58   -(for example ``$HOME/builds``), and type
  57 +After downloading the gammalib tarball (see :ref:`download`), save it
  58 +in an appropriate location (for example ``$HOME/builds``), and type
59 59  
60 60 .. code-block:: bash
61 61  
62   - $ tar xvfz gammalib-00-08-00.tar.gz
  62 + $ tar xvfz gammalib-1.0.0.tar.gz
63 63  
64 64 (the ``$`` symbol indicates the console prompt and is not part of the
65 65 command that you should type in).
66 66  
67   -Step in the created directory using
68   -
69   -.. code-block:: bash
70   -
71   - $ cd gammalib-00-08-00
72   -
73   -and build, check and install gammalib by typing
  67 +Step in the created directory and build, check and install gammalib by
  68 +typing
74 69  
75 70 .. code-block:: bash
76 71  
  72 + $ cd gammalib-1.0.0
77 73 $ ./configure
78 74 $ make
79 75 $ make check
... ... @@ -124,26 +120,21 @@ If you use C shell or a variant then add the following to your
124 120 Building ctools
125 121 ---------------
126 122  
127   -After downloading the ctools tarball, save it in an appropriate location
128   -(for example ``$HOME/builds``), and type
  123 +After downloading the ctools tarball (see :ref:`download`), save it in
  124 +an appropriate location (for example ``$HOME/builds``), and type
129 125  
130 126 .. code-block:: bash
131 127  
132   - $ tar xvfz ctools-00-07-00.tar.gz
  128 + $ tar xvfz ctools-1.0.0.tar.gz
133 129  
134 130 (the ``$`` symbol indicates the console prompt and is not part of the
135 131 command that you should type in).
136 132  
137   -Step in the created directory using
138   -
139   -.. code-block:: bash
140   -
141   - $ cd ctools-00-07-00
142   -
143   -and build the ctools by typing
  133 +Step in the directory and build the ctools by typing
144 134  
145 135 .. code-block:: bash
146 136  
  137 + $ cd ctools-1.0.0
147 138 $ ./configure
148 139 $ make
149 140  
... ... @@ -175,14 +166,18 @@ following output at the end of the unit testing:
175 166  
176 167 .. code-block:: bash
177 168  
  169 + PASS: test_ctools.sh
  170 + PASS: test_cscripts.sh
  171 + PASS: test_python.py
  172 + make[4]: Nothing to be done for `all'.
178 173 ============================================================================
179   - Testsuite summary for ctools 0.7.0
  174 + Testsuite summary for ctools 1.0.0
180 175 ============================================================================
181 176 # TOTAL: 3
182 177 # PASS: 3
183 178 # SKIP: 0
184 179 # XFAIL: 0
185   - # FAIL: 0
  180 + # FAIL: 0
186 181 # XPASS: 0
187 182 # ERROR: 0
188 183 ============================================================================
... ... @@ -200,6 +195,12 @@ For older automake version, you should see
200 195 Test ctmodel: ...... ok
201 196 Test ctselect: .. ok
202 197 Test ctlike: ........ ok
  198 + Test cttsmap: .. ok
  199 + Test ctexpcube: .... ok
  200 + Test ctpsfcube: .... ok
  201 + Test ctbkgcube: ...... ok
  202 + Test ctcubemask: .. ok
  203 + Test ctbutterfly: .. ok
203 204 PASS: test_ctools.sh
204 205  
205 206 *****************
... ... @@ -207,15 +208,27 @@ For older automake version, you should see
207 208 *****************
208 209 Test cspull: .. ok
209 210 Test cstsdist: .. ok
  211 + Test csresmap: .. ok
210 212 PASS: test_cscripts.sh
211 213  
212   - ***********************************
213   - * ctools Python interface testing *
214   - ***********************************
215   - Test executable analysis: ... ok
216   - Test in-memory analysis: ... ok
217   - Test diffuse map cube with constant analysis: .... ok
218   - Test diffuse map cube with power law analysis: ..... ok
  214 + ***********************
  215 + * ctools unit testing *
  216 + ***********************
  217 + Test ctobssim functionality: .......... ok
  218 + Test ctobssim on observation container: .... ok
  219 + Test ctselect functionality: ... ok
  220 + Test ctbin functionality: ... ok
  221 + Test ctlike functionality: ... ok
  222 + Test cttsmap functionality: ... ok
  223 + Test ctmodel functionality: ... ok
  224 + Test ctskymap functionality: ... ok
  225 + Test ctexpcube functionality: ... ok
  226 + Test ctpsfcube functionality: ... ok
  227 + Test ctbkgcube functionality: ... ok
  228 + Test ctcubemask functionality: ... ok
  229 + Test ctbutterfly functionality: ... ok
  230 + Test unbinned pipeline with FITS file saving: .... ok
  231 + Test unbinned in-memory pipeline: .... ok
219 232 PASS: test_python.py
220 233 ==================
221 234 All 3 tests passed
... ... @@ -322,20 +335,28 @@ by default. To make ``Python.h`` available, install the Python developer
322 335 package in your distribution. Otherwise you will not be able to use ctools
323 336 from Python.
324 337  
  338 +GammaLib and ctools release bundles come with Python wrapper files, but
  339 +these wrapper files will be deleted once you type ``make clean``. Wrapper
  340 +files will be built automatically when needed, but this required
  341 +`swig <http://www.swig.org/>`_ installed on your system. In that case,
  342 +please make sure that you swig version 2.0.4 or newer.
  343 +
  344 +
325 345 Mac OS X
326 346 ~~~~~~~~
327 347  
328   -The Python development package is not installed as default on Mac OS X,
  348 +The Python development package is not installed by default on Mac OS X,
329 349 and consequently, the ``Python.h`` header file is missing that is needed
330 350 to compile in the Python bindings. The configure script recognises this
331 351 fact and adjust the build procedure accordingly, but you will not be able
332   -to use ctools from Python. So better install the Python development package
333   -before installing ctools.
  352 +to use ctools as a Python module. So better install the Python development
  353 +package before installing ctools.
334 354  
335 355 It was also reported that adding of
336 356 ``export MACOSX_DEPLOYMENT_TARGET=10.6`` to the ``.bashrc`` file was
337 357 necessary one some Mac OS X 10.6 installations to make ctools compile.
338 358  
  359 +
339 360 Solaris
340 361 ~~~~~~~
341 362  
... ... @@ -348,6 +369,7 @@ cfitsio versions more recent than 3.250. The problems have been reported to
348 369 the cfitsio developer team, and are likely to be solved in the future. For
349 370 the time being, it is recommended to use cfitsio version 3.250 on Solaris.
350 371  
  372 +
351 373 OpenSolaris
352 374 ~~~~~~~~~~~
353 375  
... ...
doc/source/user_manual/getting_started/quickstart.rst
  View file @feaf03a
... ... @@ -27,39 +27,41 @@ The example consists of the following analysis steps:
27 27 Simulating CTA data
28 28 ~~~~~~~~~~~~~~~~~~~
29 29  
30   -CTA data are simulated by the executable ctobssim. To start the executable,
31   -type ctobssim at the console prompt (which is denoted by ``$``). ctobssim
32   -will query for a number of parameters:
  30 +CTA data are simulated using the :ref:`ctobssim` tool. To invoke the tool,
  31 +type :ref:`ctobssim` at the console prompt (which is denoted by ``$``).
  32 +:ref:`ctobssim` will query for a number of parameters:
33 33  
34 34 .. code-block:: bash
35 35  
36 36 $ ctobssim
37   - Model [$CTOOLS/share/models/crab.xml]
38 37 RA of pointing (degrees) (0-360) [83.63]
39 38 Dec of pointing (degrees) (-90-90) [22.01]
40   - Calibration database [dummy]
41   - Instrument response function [cta_dummy_irf]
42 39 Radius of FOV (degrees) (0-180) [5.0]
43 40 Start time (MET in s) (0) [0.0]
44 41 End time (MET in s) (0) [1800.0]
45 42 Lower energy limit (TeV) (0) [0.1]
46 43 Upper energy limit (TeV) (0) [100.0]
  44 + Calibration database [dummy]
  45 + Instrument response function [cta_dummy_irf]
  46 + Model [$CTOOLS/share/models/crab.xml]
47 47 Output event data file or observation definition file [events.fits]
48 48  
49   -Each line represents a query for one parameter. The line starts with a short
50   -description of the parameter, followed by the default parameter value proposed
51   -by ctobssim in squared brackets ``[ ]``. If no parameter is entered (which
52   -is the case for the majority of parameters shown here), the default parameter
53   -will be used. Otherwise, the specified parameter will overwrite the
54   -default parameter.
  49 +Each line represents a query for one parameter value.
  50 +The line starts with a short description of the parameter, followed by
  51 +the default value proposed by ctobssim in squared brackets ``[ ]``.
  52 +**If no parameter is entered the default value will be used**
  53 +(which is the case for all parameters shown here).
  54 +Otherwise, the specified value will overwrite the default value.
  55 +The round brackets ``( )`` indicate the range of possible parameter
  56 +values (if applicable).
  57 +
55 58  
56 59 You may have recognised that the environment variable ``$CTOOLS`` has
57   -been used in the path names of the first two parameters. ctools will
58   -automatically expand the environment variables.
  60 +been used in the path name of the model. ctools will automatically expand
  61 +the environment variables in parameter inputs.
59 62  
60 63 The CTA instrument properties (effective area, PSF width) are taken for
61   -the moment from a dummy performance table that is located in
62   -``$CTOOLS/share/caldb/cta``.
  64 +the moment from a dummy calibration database.
63 65  
64 66 Events are simulated based on the instrument properties and based on a
65 67 source and background model. Only events that fall within the specified
... ... @@ -96,18 +98,18 @@ The source and background model is defined by the XML file
96 98 </source>
97 99 </source_library>
98 100  
99   -The model consists of a source library that contains 2 "sources": the Crab
100   -nebula and an instrumental background model.
  101 +The model consists of a source library that contains two components:
  102 +the Crab nebula and an instrumental background model.
101 103  
102 104 The Crab nebula is modelled by a factorized sky model that has a spectral
103 105 and a spatial component (tags ``<spectrum>`` and ``<spatialModel>``,
104 106 respectively). The spectrum is modelled by a power law, which is defined by
105   -3 parameters: the ``Prefactor``, the ``Index`` and the ``Scale``.
106   -The spatial model has 2 parameters: Right Ascension in degrees (RA), and
  107 +three parameters: the ``Prefactor``, the ``Index`` and the ``Scale``.
  108 +The spatial model has two parameters: Right Ascension in degrees (RA), and
107 109 Declination in degrees (DEC). Each parameter has a value and a scale factor,
108   -the real value of the parameter being the product value * scale. Typically,
  110 +the real value of the parameter being the product ``value * scale``. Typically,
109 111 scale is chosen so that value is of the order of 1 (this is relevant for
110   -model fitting later). In addition, value is bound by a minimum (min) and
  112 +model fitting). In addition, value is bound by a minimum (min) and
111 113 maximum (max) value, and a parameter may be free (``free="1"``) or fixed
112 114 (``free="0"``). The min, max, and free attributes are not relevant here for
113 115 the simulations, but they will be important for the model fitting later.
... ... @@ -124,19 +126,21 @@ where the parameters in the XML definition have the following mappings:
124 126 * :math:`\gamma` = ``Index``
125 127 * :math:`E_0` = ``Scale``
126 128  
127   -Note that energies are given in MeV.
  129 +Note that energies are given in MeV. This is a GammaLib convention that
  130 +can not be modified. **So make sure you always use MeV as energy unit in
  131 +an XML file.**
128 132  
129 133 The instrumental background of CTA is modelled by a factorized data model
130 134 that has a spectral and a radial component (tags ``<spectrum>`` and
131 135 ``<radialModel>``, respectively). The spectral component describes the
132 136 on-axis background counting rate of CTA as function of energy in units of
133   -counts/s/sr/TeV. The radial component describes the variation of the
  137 +counts/s/sr/MeV. The radial component describes the variation of the
134 138 background rate with offset angle squared, (i.e. square of the offset angle
135 139 with respect to the pointing direction) which is modelled here by a Gaussian.
136 140 The only parameter of the radial component is the width of the Gaussian Sigma,
137 141 which is here set to 3 degrees squared.
138 142  
139   -ctobssim has a couple of hidden parameters, the most important one being
  143 +:ref:`ctobssim` has a couple of hidden parameters, the most important one being
140 144 certainly ``seed``. ``seed`` is an integer that specifies the seed value
141 145 for the random number generator, and changing this parameter will allow to
142 146 generate statistically independent Monte Carlo samples of CTA event data.
... ... @@ -146,41 +150,35 @@ To use for example a seed value of 41 you should type:
146 150  
147 151 $ ctobssim seed=41
148 152  
149   -ctobssim will write 2 files in the working directory: ``events.fits`` and
150   -``ctobssim.log``. The first file contains the simulated events in FITS
  153 +:ref:`ctobssim` will write 2 files in the working directory: ``events.fits``
  154 +and ``ctobssim.log``. The first file contains the simulated events in FITS
151 155 format and can be inspected using ``fv`` or ``ds9``. The FITS file will
152   -contain 3 extensions: an empty primary image, a binary table named
  156 +contain three extensions: an empty primary image, a binary table named
153 157 ``EVENTS`` that holds the events (one row per event), and a binary table
154 158 named ``GTI`` holding the Good Time Intervals (for the moment a single row
155 159 with 2 columns providing the start and the stop time of the simulated time
156 160 interval).
157 161  
158   -The second file produced by ctobssim is a human readable log file that
  162 +The second file produced by :ref:`ctobssim` is a human readable log file that
159 163 contains information about the job execution. As example, the last lines
160 164 from this file are shown here:
161 165  
162 166 .. code-block:: xml
163 167  
164   - 2014-10-30T22:35:06: +======================+
165   - 2014-10-30T22:35:06: | Simulate observation |
166   - 2014-10-30T22:35:06: +======================+
167   - 2014-10-30T22:35:06: === Observation ===
168   - 2014-10-30T22:35:06: Simulation area ...........: 1.9635e+11 cm2
169   - 2014-10-30T22:35:06: Simulation cone ...........: RA=83.63 deg, Dec=22.01 deg, r=5.5 deg
170   - 2014-10-30T22:35:06: Time interval .............: 0 - 1800 s
171   - 2014-10-30T22:35:06: Photon energy range .......: 100 GeV - 100 TeV
172   - 2014-10-30T22:35:06: Event energy range ........: 100 GeV - 100 TeV
173   - 2014-10-30T22:35:06: MC source photons .........: 207547 [Crab]
174   - 2014-10-30T22:35:06: MC source events ..........: 995 [Crab]
175   - 2014-10-30T22:35:06: MC source events ..........: 995 (all source models)
176   - 2014-10-30T22:35:06: MC background events ......: 5146
177   - 2014-10-30T22:35:06: MC events .................: 6141 (all models)
178   - 2014-10-30T22:35:06:
179   - 2014-10-30T22:35:06: +==================+
180   - 2014-10-30T22:35:06: | Save observation |
181   - 2014-10-30T22:35:06: +==================+
182   - 2014-10-30T22:35:06:
183   - 2014-10-30T22:35:06: Application "ctobssim" terminated after 10 wall clock seconds, consuming 0.3604 seconds of CPU time.
  168 + 2015-02-04T15:04:56: +======================+
  169 + 2015-02-04T15:04:56: | Simulate observation |
  170 + 2015-02-04T15:04:56: +======================+
  171 + 2015-02-04T15:04:56: === Observation ===
  172 + 2015-02-04T15:04:56: Simulation area ...........: 1.9635e+11 cm2
  173 + 2015-02-04T15:04:56: Simulation cone ...........: RA=83.63 deg, Dec=22.01 deg, r=5.5 deg
  174 + 2015-02-04T15:04:56: Time interval .............: 0 - 1800 s
  175 + 2015-02-04T15:04:56: Photon energy range .......: 100 GeV - 100 TeV
  176 + 2015-02-04T15:04:56: Event energy range ........: 100 GeV - 100 TeV
  177 + 2015-02-04T15:04:56: MC source photons .........: 207547 [Crab]
  178 + 2015-02-04T15:04:56: MC source events ..........: 995 [Crab]
  179 + 2015-02-04T15:04:56: MC source events ..........: 995 (all source models)
  180 + 2015-02-04T15:04:56: MC background events ......: 5146
  181 + 2015-02-04T15:04:56: MC events .................: 6141 (all models)
184 182  
185 183 Each line starts with the UTC time at which the line has been written. In
186 184 this run, 207547 Crab photons have been thrown over an area of 19.6 square
... ... @@ -204,29 +202,35 @@ log file (the chattiness of the executable) using the hidden parameter
204 202 $ ctobssim chatter=4
205 203  
206 204 ``chatter`` can vary between 0 and 4, 0 providing no information while 4
207   -provides the most detailed information. You may also copy the log file
208   -information to the console using
  205 +provides the most detailed information. **By default, all ctools have a
  206 +chatter level of 2.**
  207 +
  208 +You may also duplicate the log file information into the console by setting
  209 +the hidden ``debug`` parameter to yes:
209 210  
210 211 .. code-block:: bash
211 212  
212 213 $ ctobssim debug=yes
213 214  
  215 +
214 216 .. _sec_binning_cta:
215 217  
216 218 Binning CTA data
217 219 ~~~~~~~~~~~~~~~~
218 220  
219   -As next analysis step you will bin the data in a counts cube using the
220   -executable ctbin. A counts cube is a 3 dimensional data cube, spanned by
  221 +As next analysis step you will bin the data in a counts cube using
  222 +:ref:`ctbin`.
  223 +A counts cube is a 3 dimensional data cube, spanned by
221 224 Right Ascension (or Galactic longitude), Declination (or Galactic latitude),
222   -and the logarithm (base 10) of energy.
  225 +and energy (typically logarithmically spaced, but this is under user
  226 +control).
223 227  
224   -ctbin is executed by typing:
  228 +:ref:`ctbin` is executed by typing:
225 229  
226 230 .. code-block:: bash
227 231  
228 232 $ ctbin
229   - Input event list or observation definition file [events.fits]
  233 + Event list or observation definition file [events.fits]
230 234 First coordinate of image center in degrees (RA or galactic l) [83.63]
231 235 Second coordinate of image center in degrees (DEC or galactic b) [22.01]
232 236 Projection method e.g. AIT|AZP|CAR|MER|STG|TAN (AIT|AZP|CAR|MER|STG|TAN) [CAR]
... ... @@ -240,13 +244,11 @@ ctbin is executed by typing:
240 244 Number of energy bins [20]
241 245 Output counts cube [cntmap.fits]
242 246  
243   -In this example we adjust the event data file name and accept all the
244   -remaining parameter defaults as they perfectly satisfy our needs. The counts
245   -cube will be centred on the location of the Crab (Right Ascension 83.63 degrees,
246   -Declination 22.01 degrees) and will be aligned in celestial coordinates. A
247   -cartesian projection has been selected. The counts cube has 200 x 200 spatial
248   -pixels of 0.02 x 0.02 degrees in size, hence it covers a total area of 4 x 4
249   -degrees.
  247 +The counts cube will be centred on the location of the Crab (Right Ascension
  248 +83.63 degrees, Declination 22.01 degrees) and will be aligned in celestial
  249 +coordinates. A cartesian projection has been selected. The counts cube has
  250 +200 x 200 spatial pixels of 0.02 x 0.02 degrees in size, hence it covers a
  251 +total area of 4 x 4 degrees.
250 252  
251 253 The counts cube will contain 20 maps, which are logarithmically spaced
252 254 in energy, and which cover the energy range from 0.1 TeV to 100 TeV. In this
... ... @@ -279,37 +281,38 @@ reproduced below:
279 281  
280 282 .. code-block:: xml
281 283  
282   - 2014-10-30T22:39:35: +====================+
283   - 2014-10-30T22:39:35: | Binned observation |
284   - 2014-10-30T22:39:35: +====================+
285   - 2014-10-30T22:39:35: === GObservations ===
286   - 2014-10-30T22:39:35: Number of observations ....: 1
287   - 2014-10-30T22:39:35: Number of predicted events : 0
288   - 2014-10-30T22:39:35: === GCTAObservation ===
289   - 2014-10-30T22:39:35: Name ......................:
290   - 2014-10-30T22:39:35: Identifier ................:
291   - 2014-10-30T22:39:35: Instrument ................: CTA
292   - 2014-10-30T22:39:35: Event file ................: events.fits
293   - 2014-10-30T22:39:35: Event type ................: CountsMap
294   - 2014-10-30T22:39:35: Statistics ................: Poisson
295   - 2014-10-30T22:39:35: Ontime ....................: 1800 s
296   - 2014-10-30T22:39:35: Livetime ..................: 1710 s
297   - 2014-10-30T22:39:35: Deadtime correction .......: 0.95
298   - 2014-10-30T22:39:35: === GCTAPointing ===
299   - 2014-10-30T22:39:35: Pointing direction ........: (RA,Dec)=(83.63,22.01)
300   - 2014-10-30T22:39:35: Response function .........: undefined
301   - 2014-10-30T22:39:35: === GCTAEventCube ===
302   - 2014-10-30T22:39:35: Number of events ..........: 5542
303   - 2014-10-30T22:39:35: Number of elements ........: 800000
304   - 2014-10-30T22:39:35: Number of pixels ..........: 40000
305   - 2014-10-30T22:39:35: Number of energy bins .....: 20
306   - 2014-10-30T22:39:35: Time interval .............: 0 - 1800 sec
307   - 2014-10-30T22:39:35:
308   - 2014-10-30T22:39:35: +==================+
309   - 2014-10-30T22:39:35: | Save observation |
310   - 2014-10-30T22:39:35: +==================+
311   - 2014-10-30T22:39:36:
312   - 2014-10-30T22:39:36: Application "ctbin" terminated after 18 wall clock seconds, consuming 0.308684 seconds of CPU time.
  284 + 2015-02-04T15:33:34: +====================+
  285 + 2015-02-04T15:33:34: | Binned observation |
  286 + 2015-02-04T15:33:34: +====================+
  287 + 2015-02-04T15:33:34: === GObservations ===
  288 + 2015-02-04T15:33:34: Number of observations ....: 1
  289 + 2015-02-04T15:33:34: Number of predicted events : 0
  290 + 2015-02-04T15:33:34: === GCTAObservation ===
  291 + 2015-02-04T15:33:34: Name ......................:
  292 + 2015-02-04T15:33:34: Identifier ................:
  293 + 2015-02-04T15:33:34: Instrument ................: CTA
  294 + 2015-02-04T15:33:34: Event file ................: events.fits
  295 + 2015-02-04T15:33:34: Event type ................: CountsMap
  296 + 2015-02-04T15:33:34: Statistics ................: Poisson
  297 + 2015-02-04T15:33:34: Ontime ....................: 1800 s
  298 + 2015-02-04T15:33:34: Livetime ..................: 1710 s
  299 + 2015-02-04T15:33:34: Deadtime correction .......: 0.95
  300 + 2015-02-04T15:33:34: User energy range .........: undefined
  301 + 2015-02-04T15:33:34: === GCTAPointing ===
  302 + 2015-02-04T15:33:34: Pointing direction ........: (RA,Dec)=(83.63,22.01)
  303 + 2015-02-04T15:33:34: Response function .........: undefined
  304 + 2015-02-04T15:33:34: === GCTAEventCube ===
  305 + 2015-02-04T15:33:34: Number of events ..........: 5542
  306 + 2015-02-04T15:33:34: Number of elements ........: 800000
  307 + 2015-02-04T15:33:34: Number of pixels ..........: 40000
  308 + 2015-02-04T15:33:34: Number of energy bins .....: 20
  309 + 2015-02-04T15:33:34: Time interval .............: 0 - 1800 sec
  310 + 2015-02-04T15:33:34:
  311 + 2015-02-04T15:33:34: +==================+
  312 + 2015-02-04T15:33:34: | Save observation |
  313 + 2015-02-04T15:33:34: +==================+
  314 + 2015-02-04T15:33:34:
  315 + 2015-02-04T15:33:34: Application "ctbin" terminated after 14 wall clock seconds, consuming 0.332675 seconds of CPU time.
313 316  
314 317 From the 6141 events that have been simulated and stored in the
315 318 ``events.fits`` file, 5542 lie within the cube boundaries and are thus put
... ... @@ -324,8 +327,8 @@ Fitting CTA data
324 327  
325 328 Now we are ready to fit the simulated data with a model. For simplicity
326 329 we use in this example the same model that we used to simulate the data
327   -with ctobssim. Model fitting is done using the executable ctlike, and we
328   -do the fit by typing:
  330 +with :ref:`ctobssim`. Model fitting is done using the :ref:`ctlike` tool,
  331 +and we do the fit by typing:
329 332  
330 333 .. code-block:: bash
331 334  
... ... @@ -343,18 +346,18 @@ an alternative method, the so called *unbinned* mode, where the events are
343 346 not binned into a counts cube and the log-likelihood is computed directly by
344 347 summing over all events. We will explore the *unbinned* mode later.
345 348  
346   -One of the parameters given to ctlike is a source model output file
  349 +One of the parameters of :ref:`ctlike` is a source model output file
347 350 (we specified ``crab_results.xml`` in the example), and this file will be
348   -a copy of the model XML file where the parameter values have been replaced
349   -by the fit results. In addition, the statistical uncertainties are added
350   -for each fitted parameter using the attribute error. Below we show the XML
351   -result file that has been produced by the run:
  351 +a copy of the source model input XML file where the parameter values have
  352 +been replaced by the fit results. In addition, the statistical uncertainties
  353 +are added for each fitted parameter using the attribute error. Below we show
  354 +the XML result file that has been produced by the run:
352 355  
353 356 .. code-block:: xml
354 357  
355 358 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
356 359 <source_library title="source library">
357   - <source name="Crab" type="PointSource">
  360 + <source name="Crab" type="PointSource" tscalc="0">
358 361 <spectrum type="PowerLaw">
359 362 <parameter name="Prefactor" value="6.07928" error="0.204582" scale="1e-16" min="1e-07" max="1000" free="1" />
360 363 <parameter name="Index" value="2.5009" error="0.0252057" scale="-1" min="0" max="5" free="1" />
... ... @@ -380,127 +383,141 @@ Crab as well as the ``Normalization`` and ``Sigma`` parameter of the radial
380 383 acceptance model have been fitted (all parameters having the attribute
381 384 ``free="1"`` are fitted).
382 385  
  386 +.. note::
  387 +
  388 + You may have noticed that the Crab source contains an additional
  389 + ``tscalc`` attribute in the XML result file. This attribute can be
  390 + used to instruct :ref:`ctlike` to compute the Test Statistics
  391 + (which is a measure of the detection significance) of the source.
  392 + To do so, add ``tscalc="1"`` to the XML file on input
  393 + and then re-run :ref:`ctlike`. This will then give the following result:
  394 +
  395 + .. code-block:: xml
  396 +
  397 + <source name="Crab" type="PointSource" ts="6875.350" tscalc="1">
  398 +
  399 +
383 400 To get more details about the model fitting you can inspect the log file.
384 401 Below the last lines of the ctlike.log log file that has been produced by
385 402 this run:
386 403  
387 404 .. code-block:: xml
388 405  
389   - 2014-10-30T22:41:08: +=================================+
390   - 2014-10-30T22:41:08: | Maximum likelihood optimisation |
391   - 2014-10-30T22:41:08: +=================================+
392   - 2014-10-30T22:41:09: >Iteration 0: -logL=22752.553, Lambda=1.0e-03
393   - 2014-10-30T22:41:11: >Iteration 1: -logL=22750.640, Lambda=1.0e-03, delta=1.913, max(|grad|)=-0.941594 [Index:3]
394   - 2014-10-30T22:41:12: >Iteration 2: -logL=22750.632, Lambda=1.0e-04, delta=0.008, max(|grad|)=-0.079270 [Index:3]
395   - 2014-10-30T22:41:14: >Iteration 3: -logL=22750.632, Lambda=1.0e-05, delta=0.000, max(|grad|)=-0.003073 [Index:3]
396   - 2014-10-30T22:41:16:
397   - 2014-10-30T22:41:16: +=========================================+
398   - 2014-10-30T22:41:16: | Maximum likelihood optimization results |
399   - 2014-10-30T22:41:16: +=========================================+
400   - 2014-10-30T22:41:16: === GOptimizerLM ===
401   - 2014-10-30T22:41:16: Optimized function value ..: 22750.632
402   - 2014-10-30T22:41:16: Absolute precision ........: 0.005
403   - 2014-10-30T22:41:16: Optimization status .......: converged
404   - 2014-10-30T22:41:16: Number of parameters ......: 9
405   - 2014-10-30T22:41:16: Number of free parameters .: 4
406   - 2014-10-30T22:41:16: Number of iterations ......: 3
407   - 2014-10-30T22:41:16: Lambda ....................: 1e-06
408   - 2014-10-30T22:41:16:
409   - 2014-10-30T22:41:16: +=========================================+
410   - 2014-10-30T22:41:16: | Maximum likelihood optimization results |
411   - 2014-10-30T22:41:16: +=========================================+
412   - 2014-10-30T22:41:16: === GOptimizerLM ===
413   - 2014-10-30T22:41:16: Optimized function value ..: 22750.632
414   - 2014-10-30T22:41:16: Absolute precision ........: 0.005
415   - 2014-10-30T22:41:16: Optimization status .......: converged
416   - 2014-10-30T22:41:16: Number of parameters ......: 9
417   - 2014-10-30T22:41:16: Number of free parameters .: 4
418   - 2014-10-30T22:41:16: Number of iterations ......: 3
419   - 2014-10-30T22:41:16: Lambda ....................: 1e-06
420   - 2014-10-30T22:41:16: Maximum log likelihood ....: -22750.632
421   - 2014-10-30T22:41:16: Observed events (Nobs) ...: 5542.000
422   - 2014-10-30T22:41:16: Predicted events (Npred) ..: 5542.000 (Nobs - Npred = 3.3498e-06)
423   - 2014-10-30T22:41:16: === GModels ===
424   - 2014-10-30T22:41:16: Number of models ..........: 2
425   - 2014-10-30T22:41:16: Number of parameters ......: 9
426   - 2014-10-30T22:41:16: === GModelSky ===
427   - 2014-10-30T22:41:16: Name ......................: Crab
428   - 2014-10-30T22:41:16: Instruments ...............: all
429   - 2014-10-30T22:41:16: Instrument scale factors ..: unity
430   - 2014-10-30T22:41:16: Observation identifiers ...: all
431   - 2014-10-30T22:41:16: Model type ................: PointSource
432   - 2014-10-30T22:41:16: Model components ..........: "SkyDirFunction" * "PowerLaw" * "Constant"
433   - 2014-10-30T22:41:16: Number of parameters ......: 6
434   - 2014-10-30T22:41:16: Number of spatial par's ...: 2
435   - 2014-10-30T22:41:16: RA .......................: 83.6331 [-360,360] deg (fixed,scale=1)
436   - 2014-10-30T22:41:16: DEC ......................: 22.0145 [-90,90] deg (fixed,scale=1)
437   - 2014-10-30T22:41:16: Number of spectral par's ..: 3
438   - 2014-10-30T22:41:16: Prefactor ................: 6.07928e-16 +/- 2.04582e-17 [1e-23,1e-13] ph/cm2/s/MeV (free,scale=1e-16,gradient)
439   - 2014-10-30T22:41:16: Index ....................: -2.5009 +/- 0.0252057 [-0,-5] (free,scale=-1,gradient)
440   - 2014-10-30T22:41:16: PivotEnergy ..............: 300000 [10000,1e+09] MeV (fixed,scale=1e+06,gradient)
441   - 2014-10-30T22:41:16: Number of temporal par's ..: 1
442   - 2014-10-30T22:41:16: Constant .................: 1 (relative value) (fixed,scale=1,gradient)
443   - 2014-10-30T22:41:16: === GCTAModelRadialAcceptance ===
444   - 2014-10-30T22:41:16: Name ......................: Background
445   - 2014-10-30T22:41:16: Instruments ...............: CTA
446   - 2014-10-30T22:41:16: Instrument scale factors ..: unity
447   - 2014-10-30T22:41:16: Observation identifiers ...: all
448   - 2014-10-30T22:41:16: Model type ................: "Gaussian" * "FileFunction" * "Constant"
449   - 2014-10-30T22:41:16: Number of parameters ......: 3
450   - 2014-10-30T22:41:16: Number of radial par's ....: 1
451   - 2014-10-30T22:41:16: Sigma ....................: 3.02523 +/- 0.0594117 [0.01,10] deg2 (free,scale=1,gradient)
452   - 2014-10-30T22:41:16: Number of spectral par's ..: 1
453   - 2014-10-30T22:41:16: Normalization ............: 0.990708 +/- 0.0192887 [0,1000] (free,scale=1,gradient)
454   - 2014-10-30T22:41:16: Number of temporal par's ..: 1
455   - 2014-10-30T22:41:16: Constant .................: 1 (relative value) (fixed,scale=1,gradient)
456   - 2014-10-30T22:41:16:
457   - 2014-10-30T22:41:16: +==============+
458   - 2014-10-30T22:41:16: | Save results |
459   - 2014-10-30T22:41:16: +==============+
460   - 2014-10-30T22:41:16:
461   - 2014-10-30T22:41:16: Application "ctlike" terminated after 22 wall clock seconds, consuming 8.54182 seconds of CPU time.
  406 + 2015-02-04T15:50:43: +=================================+
  407 + 2015-02-04T15:50:43: | Maximum likelihood optimisation |
  408 + 2015-02-04T15:50:43: +=================================+
  409 + 2015-02-04T15:50:44: >Iteration 0: -logL=22752.553, Lambda=1.0e-03
  410 + 2015-02-04T15:50:46: >Iteration 1: -logL=22750.640, Lambda=1.0e-03, delta=1.913, max(|grad|)=-0.941594 [Index:3]
  411 + 2015-02-04T15:50:47: >Iteration 2: -logL=22750.632, Lambda=1.0e-04, delta=0.008, max(|grad|)=-0.079270 [Index:3]
  412 + 2015-02-04T15:50:48: >Iteration 3: -logL=22750.632, Lambda=1.0e-05, delta=0.000, max(|grad|)=-0.003073 [Index:3]
  413 + 2015-02-04T15:50:49:
  414 + 2015-02-04T15:50:49: +=========================================+
  415 + 2015-02-04T15:50:49: | Maximum likelihood optimization results |
  416 + 2015-02-04T15:50:49: +=========================================+
  417 + 2015-02-04T15:50:49: === GOptimizerLM ===
  418 + 2015-02-04T15:50:49: Optimized function value ..: 22750.632
  419 + 2015-02-04T15:50:49: Absolute precision ........: 0.005
  420 + 2015-02-04T15:50:49: Acceptable value decrease .: 2
  421 + 2015-02-04T15:50:49: Optimization status .......: converged
  422 + 2015-02-04T15:50:49: Number of parameters ......: 9
  423 + 2015-02-04T15:50:49: Number of free parameters .: 4
  424 + 2015-02-04T15:50:49: Number of iterations ......: 3
  425 + 2015-02-04T15:50:49: Lambda ....................: 1e-06
  426 + 2015-02-04T15:50:49: Maximum log likelihood ....: -22750.632
  427 + 2015-02-04T15:50:49: Observed events (Nobs) ...: 5542.000
  428 + 2015-02-04T15:50:49: Predicted events (Npred) ..: 5542.000 (Nobs - Npred = 3.3498e-06)
  429 + 2015-02-04T15:50:49: === GModels ===
  430 + 2015-02-04T15:50:49: Number of models ..........: 2
  431 + 2015-02-04T15:50:49: Number of parameters ......: 9
  432 + 2015-02-04T15:50:49: === GModelSky ===
  433 + 2015-02-04T15:50:49: Name ......................: Crab
  434 + 2015-02-04T15:50:49: Instruments ...............: all
  435 + 2015-02-04T15:50:49: Instrument scale factors ..: unity
  436 + 2015-02-04T15:50:49: Observation identifiers ...: all
  437 + 2015-02-04T15:50:49: Model type ................: PointSource
  438 + 2015-02-04T15:50:49: Model components ..........: "SkyDirFunction" * "PowerLaw" * "Constant"
  439 + 2015-02-04T15:50:49: Number of parameters ......: 6
  440 + 2015-02-04T15:50:49: Number of spatial par's ...: 2
  441 + 2015-02-04T15:50:49: RA .......................: 83.6331 [-360,360] deg (fixed,scale=1)
  442 + 2015-02-04T15:50:49: DEC ......................: 22.0145 [-90,90] deg (fixed,scale=1)
  443 + 2015-02-04T15:50:49: Number of spectral par's ..: 3
  444 + 2015-02-04T15:50:49: Prefactor ................: 6.07928e-16 +/- 2.04582e-17 [1e-23,1e-13] ph/cm2/s/MeV (free,scale=1e-16,gradient)
  445 + 2015-02-04T15:50:49: Index ....................: -2.5009 +/- 0.0252057 [-0,-5] (free,scale=-1,gradient)
  446 + 2015-02-04T15:50:49: PivotEnergy ..............: 300000 [10000,1e+09] MeV (fixed,scale=1e+06,gradient)
  447 + 2015-02-04T15:50:49: Number of temporal par's ..: 1
  448 + 2015-02-04T15:50:49: Constant .................: 1 (relative value) (fixed,scale=1,gradient)
  449 + 2015-02-04T15:50:49: === GCTAModelRadialAcceptance ===
  450 + 2015-02-04T15:50:49: Name ......................: Background
  451 + 2015-02-04T15:50:49: Instruments ...............: CTA
  452 + 2015-02-04T15:50:49: Instrument scale factors ..: unity
  453 + 2015-02-04T15:50:49: Observation identifiers ...: all
  454 + 2015-02-04T15:50:49: Model type ................: "Gaussian" * "FileFunction" * "Constant"
  455 + 2015-02-04T15:50:49: Number of parameters ......: 3
  456 + 2015-02-04T15:50:49: Number of radial par's ....: 1
  457 + 2015-02-04T15:50:49: Sigma ....................: 3.02523 +/- 0.0594117 [0.01,10] deg2 (free,scale=1,gradient)
  458 + 2015-02-04T15:50:49: Number of spectral par's ..: 1
  459 + 2015-02-04T15:50:49: Normalization ............: 0.990708 +/- 0.0192887 [0,1000] (free,scale=1,gradient)
  460 + 2015-02-04T15:50:49: Number of temporal par's ..: 1
  461 + 2015-02-04T15:50:49: Constant .................: 1 (relative value) (fixed,scale=1,gradient)
  462 + 2015-02-04T15:50:49:
  463 + 2015-02-04T15:50:49: +==============+
  464 + 2015-02-04T15:50:49: | Save results |
  465 + 2015-02-04T15:50:49: +==============+
  466 + 2015-02-04T15:50:49:
  467 + 2015-02-04T15:50:49: Application "ctlike" terminated after 15 wall clock seconds, consuming 5.92686 seconds of CPU time.
462 468  
463 469 The maximum likelihood optimizer required 3 iterations to converge. This
464 470 is pretty fast, but recall that we used the same model file for the simulation
465 471 and for fitting, hence the initial parameter values were already very close
466 472 to the best fitting values. To see the impact of the initial parameters on
467   -the fit result, you may re-run ctlike using another copy of the model XML file
468   -where you change the value attributes of the parameters that should be
  473 +the fit result, you may re-run :ref:`ctlike` using another copy of the model
  474 +XML file where you change the value attributes of the parameters that should be
469 475 fitted. You will see that the optimizer requires a couple of more iterations,
470 476 but it should converge to the same solution (provided that the initial values
471 477 are not too far of the best fitting values).
472 478  
  479 +.. note::
  480 +
  481 + As sanity check you should verify that the predicted number of events
  482 + (Npred) is equal to the observed number of events (Nobs). To facilitate
  483 + this comparison, :ref:`ctlike` provides the difference Nobs - Npred in
  484 + the log file. In real life situations, this difference may not always be
  485 + small, in particular if the source model is too constrained. You may
  486 + then free some of the model parameters so that the fit can correctly
  487 + describe the data.
  488 +
473 489  
474 490 .. _sec_unbinned_cta:
475 491  
476 492 Doing an unbinned analysis
477 493 ~~~~~~~~~~~~~~~~~~~~~~~~~~
478 494  
479   -As gamma-ray events are rare, the counts cubes generated by ctbin will in
480   -general be sparse, having many empty pixels, in particular at high energies.
  495 +As gamma-ray events are rare, the counts cubes generated by :ref:`ctbin`
  496 +will in general be sparse, having many empty pixels, in particular at
  497 +high energies.
481 498 An alternative analysis technique consists of working directly on the event
482 499 list without binning the events in a counts cube. We will see the benefit of
483   -such an analysis later once you re-run ctlike in unbinned mode.
  500 +such an analysis later once you re-run :ref:`ctlike` in unbinned mode.
484 501  
485 502 For unbinned analysis you first have to define the data space region over
486   -which the analysis is done. This is similiar to the ctbin step in binned
487   -analysis where you defined the size of the counts cube, the energy range, and
488   -the time interval. For unbinned analysis you have no such thing as a counts
489   -cube, but you have to define over which region of the data space the selected
490   -events are spread (because the ctools have to integrate over this region to
491   -compute the total number of predicted events in the data space that you
492   -analyse). Furthermore, you have to define what energy range is covered, and
493   -what time interval is spanned by the data. All this is done by the executable
494   -ctselect, which replaces the ctbin step in an unbinned analysis.
495   -
496   -ctselect performs an event selection by choosing only events within a given
497   -region-of-interest (ROI), within a given energy band, and within a given
498   -time interval from the input event list. The ROI is a circular region on
  503 +which the analysis is done. This is similiar to the :ref:`ctbin` step for
  504 +a binned analysis where you defined the size of the counts cube, the energy
  505 +range, and the time interval. For unbinned analysis you have no such thing
  506 +as a counts cube, but you have to define over which region of the data space
  507 +the selected events are spread (because the ctools have to integrate over
  508 +this region to compute the total number of predicted events in the data space
  509 +that you analyse). Furthermore, you have to define what energy range is
  510 +covered, and what time interval is spanned by the data. All this is done
  511 +by the :ref:`ctselect` tool, which replaces the :ref:`ctbin` step in an
  512 +unbinned analysis.
  513 +
  514 +:ref:`ctselect` performs an event selection by choosing only events within
  515 +a given region-of-interest (ROI), within a given energy band, and within a
  516 +given time interval from the input event list. The ROI is a circular region on
499 517 the sky, for which you define the centre (in celestial coordinates) and the
500 518 radius. Such a circular ROI is sometimes also called an acceptance cone. The
501 519 following example shows how to run ctselect:
502 520  
503   -
504 521 .. code-block:: bash
505 522  
506 523 $ ctselect
... ... @@ -512,10 +529,10 @@ following example shows how to run ctselect:
512 529 End time (CTA MET in seconds) (0) [0.0]
513 530 Lower energy limit (TeV) (0) [0.1]
514 531 Upper energy limit (TeV) (0) [100.0]
515   - Output event list or observation definition file [selected_events.fits]
  532 + Output event list or observation definition file [selected_events.fits]
516 533  
517   -ctselect takes the input event list ``events.fits``, performs an event
518   -selection, and writes the selected event into the file
  534 +:ref:`ctselect` takes the input event list ``events.fits``, performs an
  535 +event selection, and writes the selected event into the file
519 536 ``selected_events.fits``. The parameters it will query for are the centre
520 537 of the ROI, the radius of the ROI, the start and stop time (in seconds),
521 538 and the energy lower and upper limits (in TeV). The event selection information
... ... @@ -530,27 +547,51 @@ file ``selected_events.fits``:
530 547  
531 548 *Data selection keywords*
532 549  
533   -It is important for unbinned analysis that these data selection keywords
534   -exist. If they don't exist, ctlike will not execute in unbinned mode.
  550 +**It is mandatory for an unbinned analysis that these data selection keywords
  551 +exist in the FITS file.**
  552 +If they don't exist, :ref:`ctlike` will not execute in unbinned mode.
535 553  
536 554 Below some lines of the ``ctselect.log`` file that show the data selection
537 555 part:
538 556  
539 557 .. code-block:: xml
540 558  
541   - 2014-10-30T22:44:01: +=================+
542   - 2014-10-30T22:44:01: | Event selection |
543   - 2014-10-30T22:44:01: +=================+
544   - 2014-10-30T22:44:01: === Observation ===
545   - 2014-10-30T22:44:02: Requested energy range ....: 0.1 - 100 TeV
546   - 2014-10-30T22:44:02: Energy range of data ......: 0.1 - 100 TeV
547   - 2014-10-30T22:44:02: Selected energy range .....: 0.1 - 100 TeV
548   - 2014-10-30T22:44:02: Requested ROI .............: Centre(RA,DEC)=(83.63, 22.01) deg, Radius=3 deg
549   - 2014-10-30T22:44:02: ROI of data ...............: Centre(RA,DEC)=(83.63, 22.01) deg, Radius=5 deg
550   - 2014-10-30T22:44:02: Selected ROI ..............: Centre(RA,DEC)=(83.63, 22.01) deg, Radius=3 deg
551   - 2014-10-30T22:44:02: cfitsio selection .........: ENERGY >= 0.10000000 && ENERGY <= 100.00000000 && ANGSEP(83.630000,22.010000,RA,DEC) <= 3.000000
552   - 2014-10-30T22:44:02: FITS filename .............: /var/tmp/tmp.0.VSaNXN[EVENTS][ENERGY >= 0.10000000 && ENERGY <= 100.00000000 && ANGSEP(83.630000,22.010000,RA,DEC) <= 3.000000]
  559 + 2015-02-04T17:21:41: +=================+
  560 + 2015-02-04T17:21:41: | Event selection |
  561 + 2015-02-04T17:21:41: +=================+
  562 + 2015-02-04T17:21:41: === Observation ===
  563 + 2015-02-04T17:21:41: Selected energy range .....: 0.1 - 100 TeV
  564 + 2015-02-04T17:21:41: Requested ROI .............: Centre(RA,DEC)=(83.63, 22.01) deg, Radius=3 deg
  565 + 2015-02-04T17:21:41: ROI of data ...............: Centre(RA,DEC)=(83.63, 22.01) deg, Radius=5 deg
  566 + 2015-02-04T17:21:41: Selected ROI ..............: Centre(RA,DEC)=(83.63, 22.01) deg, Radius=3 deg
  567 + 2015-02-04T17:21:41: cfitsio selection .........: ENERGY >= 0.10000000 && ENERGY <= 100.00000000 && ANGSEP(83.630000,22.010000,RA,DEC) <= 3.000000
  568 + 2015-02-04T17:21:41: FITS filename .............: /var/tmp/tmp.0.pTIaTL[EVENTS][ENERGY >= 0.10000000 && ENERGY <= 100.00000000 && ANGSEP(83.630000,22.010000,RA,DEC) <= 3.000000]
553 569  
  570 +.. note::
  571 +
  572 + :ref:`ctobssim` will also write data selection keywords in the event
  573 + list FITS file, hence you can run :ref:`ctlike` directly on a FITS file
  574 + produced by :ref:`ctobssim`. Any selection performed by :ref:`ctselect`
  575 + needs to be fully enclosed within any previous selection, e.g. the ROI
  576 + needs to be fully enclosed in the acceptance cone used for event
  577 + simulation, the energy selection must be fully comprised in the
  578 + range of simulated energies, the same applies for the temporal selection.
  579 + :ref:`ctselect` will automatically adjust
  580 + the selection parameters to guarantee full enclosure. To keep track of
  581 + this adjustment, the :ref:`ctselect` log file quotes the requested
  582 + selection, and existing selections, and the selection that was finally
  583 + applied.
  584 +
  585 +.. note::
  586 +
  587 + :ref:`ctselect` may of course also be used for event selection prior to
  588 + binned analysis, for example to select events for a given period in
  589 + time. **If you use** :ref:`ctselect` **however to make a spatial or energy
  590 + selection, make sure that the counts cube is fully enclosed in the
  591 + selection intervals.** Otherwise you will get empty zones in the counts
  592 + cube of which the ctools are not aware of, and the subsequent analysis
  593 + results will be wrong.
  594 +
554 595 Now that you have selected the events of interest, you can run ctlike in
555 596 unbinned mode. To do this you have to specify the selected event list
556 597 instead of the counts cube:
... ... @@ -564,8 +605,9 @@ instead of the counts cube:
564 605 Source model [$CTOOLS/share/models/crab.xml]
565 606 Source model output file [crab_results.xml]
566 607  
567   -You will recognise that ctlike runs much faster in unbinned mode compared
568   -to binned mode. This is understandable as the selected event list contains
  608 +You will recognise that :ref:`ctlike` runs much faster in unbinned mode
  609 +compared to binned mode.
  610 +This is understandable as the selected event list contains
569 611 only 6127 events, while the binned counts cube we used before had
570 612 200 x 200 x 20 = 800000 pixels. As unbinned maximum likelihood fitting loops
571 613 over the events (while binned maximum likelihood loops over the pixels),
... ... @@ -573,9 +615,9 @@ there are much less operations to perform in unbinned than in binned mode
573 615 (there is some additional overhead in unbinned mode that comes from
574 616 integrating the models over the region of interest, yet this is negligible
575 617 compared to the operations needed when looping over the pixels). So as long
576   -as you work with short event lists, unbinned mode is faster. Unbinned ctlike
577   -should also be more precise as no binning is performed, hence there is no
578   -loss of information due to histogramming.
  618 +as you work with short event lists, unbinned mode is faster.
  619 +Unbinned :ref:`ctlike` should also be more precise as no binning is performed,
  620 +hence there is no loss of information due to histogramming.
579 621  
580 622 Below you see the corresponding output from the ctlike.log file. The fitted
581 623 parameters are essentially identical to the ones found in binned mode.
... ... @@ -587,68 +629,68 @@ the same events for both analyses.
587 629  
588 630 .. code-block:: xml
589 631  
590   - 2014-10-31T14:45:29: +=================================+
591   - 2014-10-31T14:45:29: | Maximum likelihood optimisation |
592   - 2014-10-31T14:45:29: +=================================+
593   - 2014-10-31T14:45:29: >Iteration 0: -logL=44395.244, Lambda=1.0e-03
594   - 2014-10-31T14:45:29: Iteration 1: -logL=44396.223, Lambda=1.0e-03, delta=-0.979, max(|grad|)=9.644743 [Sigma:6] (stalled)
595   - 2014-10-31T14:45:29: >Iteration 2: -logL=44396.162, Lambda=1.0e-02, delta=0.061, max(|grad|)=-0.309683 [Normalization:7]
596   - 2014-10-31T14:45:29: >Iteration 3: -logL=44396.162, Lambda=1.0e-03, delta=0.000, max(|grad|)=-0.008931 [Index:3]
597   - 2014-10-31T14:45:29:
598   - 2014-10-31T14:45:29: +=========================================+
599   - 2014-10-31T14:45:29: | Maximum likelihood optimization results |
600   - 2014-10-31T14:45:29: +=========================================+
601   - 2014-10-31T14:45:29: === GOptimizerLM ===
602   - 2014-10-31T14:45:29: Optimized function value ..: 44396.162
603   - 2014-10-31T14:45:29: Absolute precision ........: 0.005
604   - 2014-10-31T14:45:29: Acceptable value decrease .: 1
605   - 2014-10-31T14:45:29: Optimization status .......: converged
606   - 2014-10-31T14:45:29: Number of parameters ......: 9
607   - 2014-10-31T14:45:29: Number of free parameters .: 4
608   - 2014-10-31T14:45:29: Number of iterations ......: 3
609   - 2014-10-31T14:45:29: Lambda ....................: 0.0001
610   - 2014-10-31T14:45:29: Maximum log likelihood ....: -44396.162
611   - 2014-10-31T14:45:29: Observed events (Nobs) ...: 6127.000
612   - 2014-10-31T14:45:29: Predicted events (Npred) ..: 6127.000 (Nobs - Npred = 0.000303534)
613   - 2014-10-31T14:45:29: === GModels ===
614   - 2014-10-31T14:45:29: Number of models ..........: 2
615   - 2014-10-31T14:45:29: Number of parameters ......: 9
616   - 2014-10-31T14:45:29: === GModelSky ===
617   - 2014-10-31T14:45:29: Name ......................: Crab
618   - 2014-10-31T14:45:29: Instruments ...............: all
619   - 2014-10-31T14:45:29: Instrument scale factors ..: unity
620   - 2014-10-31T14:45:29: Observation identifiers ...: all
621   - 2014-10-31T14:45:29: Model type ................: PointSource
622   - 2014-10-31T14:45:29: Model components ..........: "SkyDirFunction" * "PowerLaw" * "Constant"
623   - 2014-10-31T14:45:29: Number of parameters ......: 6
624   - 2014-10-31T14:45:29: Number of spatial par's ...: 2
625   - 2014-10-31T14:45:29: RA .......................: 83.6331 [-360,360] deg (fixed,scale=1)
626   - 2014-10-31T14:45:29: DEC ......................: 22.0145 [-90,90] deg (fixed,scale=1)
627   - 2014-10-31T14:45:29: Number of spectral par's ..: 3
628   - 2014-10-31T14:45:29: Prefactor ................: 6.13325e-16 +/- 2.05738e-17 [1e-23,1e-13] ph/cm2/s/MeV (free,scale=1e-16,gradient)
629   - 2014-10-31T14:45:29: Index ....................: -2.5057 +/- 0.0250818 [-0,-5] (free,scale=-1,gradient)
630   - 2014-10-31T14:45:29: PivotEnergy ..............: 300000 [10000,1e+09] MeV (fixed,scale=1e+06,gradient)
631   - 2014-10-31T14:45:29: Number of temporal par's ..: 1
632   - 2014-10-31T14:45:29: Constant .................: 1 (relative value) (fixed,scale=1,gradient)
633   - 2014-10-31T14:45:29: === GCTAModelRadialAcceptance ===
634   - 2014-10-31T14:45:29: Name ......................: Background
635   - 2014-10-31T14:45:29: Instruments ...............: CTA
636   - 2014-10-31T14:45:29: Instrument scale factors ..: unity
637   - 2014-10-31T14:45:29: Observation identifiers ...: all
638   - 2014-10-31T14:45:29: Model type ................: "Gaussian" * "FileFunction" * "Constant"
639   - 2014-10-31T14:45:29: Number of parameters ......: 3
640   - 2014-10-31T14:45:29: Number of radial par's ....: 1
641   - 2014-10-31T14:45:29: Sigma ....................: 3.04429 +/- 0.0330227 [0.01,10] deg2 (free,scale=1,gradient)
642   - 2014-10-31T14:45:29: Number of spectral par's ..: 1
643   - 2014-10-31T14:45:29: Normalization ............: 0.996767 +/- 0.0175227 [0,1000] (free,scale=1,gradient)
644   - 2014-10-31T14:45:29: Number of temporal par's ..: 1
645   - 2014-10-31T14:45:29: Constant .................: 1 (relative value) (fixed,scale=1,gradient)
646   - 2014-10-31T14:45:29:
647   - 2014-10-31T14:45:29: +==============+
648   - 2014-10-31T14:45:29: | Save results |
649   - 2014-10-31T14:45:29: +==============+
650   - 2014-10-31T14:45:29:
651   - 2014-10-31T14:45:29: Application "ctlike" terminated after 2 wall clock seconds, consuming 0.255421 seconds of CPU time.
  632 + 2015-02-04T17:31:58: +=================================+
  633 + 2015-02-04T17:31:58: | Maximum likelihood optimisation |
  634 + 2015-02-04T17:31:58: +=================================+
  635 + 2015-02-04T17:31:58: >Iteration 0: -logL=44395.244, Lambda=1.0e-03
  636 + 2015-02-04T17:31:58: Iteration 1: -logL=44396.223, Lambda=1.0e-03, delta=-0.979, max(|grad|)=9.644743 [Sigma:6] (stalled)
  637 + 2015-02-04T17:31:58: >Iteration 2: -logL=44396.162, Lambda=1.0e-02, delta=0.061, max(|grad|)=-0.309683 [Normalization:7]
  638 + 2015-02-04T17:31:59: >Iteration 3: -logL=44396.162, Lambda=1.0e-03, delta=0.000, max(|grad|)=-0.008931 [Index:3]
  639 + 2015-02-04T17:31:59:
  640 + 2015-02-04T17:31:59: +=========================================+
  641 + 2015-02-04T17:31:59: | Maximum likelihood optimization results |
  642 + 2015-02-04T17:31:59: +=========================================+
  643 + 2015-02-04T17:31:59: === GOptimizerLM ===
  644 + 2015-02-04T17:31:59: Optimized function value ..: 44396.162
  645 + 2015-02-04T17:31:59: Absolute precision ........: 0.005
  646 + 2015-02-04T17:31:59: Acceptable value decrease .: 2
  647 + 2015-02-04T17:31:59: Optimization status .......: converged
  648 + 2015-02-04T17:31:59: Number of parameters ......: 9
  649 + 2015-02-04T17:31:59: Number of free parameters .: 4
  650 + 2015-02-04T17:31:59: Number of iterations ......: 3
  651 + 2015-02-04T17:31:59: Lambda ....................: 0.0001
  652 + 2015-02-04T17:31:59: Maximum log likelihood ....: -44396.162
  653 + 2015-02-04T17:31:59: Observed events (Nobs) ...: 6127.000
  654 + 2015-02-04T17:31:59: Predicted events (Npred) ..: 6127.000 (Nobs - Npred = 0.000303534)
  655 + 2015-02-04T17:31:59: === GModels ===
  656 + 2015-02-04T17:31:59: Number of models ..........: 2
  657 + 2015-02-04T17:31:59: Number of parameters ......: 9
  658 + 2015-02-04T17:31:59: === GModelSky ===
  659 + 2015-02-04T17:31:59: Name ......................: Crab
  660 + 2015-02-04T17:31:59: Instruments ...............: all
  661 + 2015-02-04T17:31:59: Instrument scale factors ..: unity
  662 + 2015-02-04T17:31:59: Observation identifiers ...: all
  663 + 2015-02-04T17:31:59: Model type ................: PointSource
  664 + 2015-02-04T17:31:59: Model components ..........: "SkyDirFunction" * "PowerLaw" * "Constant"
  665 + 2015-02-04T17:31:59: Number of parameters ......: 6
  666 + 2015-02-04T17:31:59: Number of spatial par's ...: 2
  667 + 2015-02-04T17:31:59: RA .......................: 83.6331 [-360,360] deg (fixed,scale=1)
  668 + 2015-02-04T17:31:59: DEC ......................: 22.0145 [-90,90] deg (fixed,scale=1)
  669 + 2015-02-04T17:31:59: Number of spectral par's ..: 3
  670 + 2015-02-04T17:31:59: Prefactor ................: 6.13325e-16 +/- 2.05738e-17 [1e-23,1e-13] ph/cm2/s/MeV (free,scale=1e-16,gradient)
  671 + 2015-02-04T17:31:59: Index ....................: -2.5057 +/- 0.0250818 [-0,-5] (free,scale=-1,gradient)
  672 + 2015-02-04T17:31:59: PivotEnergy ..............: 300000 [10000,1e+09] MeV (fixed,scale=1e+06,gradient)
  673 + 2015-02-04T17:31:59: Number of temporal par's ..: 1
  674 + 2015-02-04T17:31:59: Constant .................: 1 (relative value) (fixed,scale=1,gradient)
  675 + 2015-02-04T17:31:59: === GCTAModelRadialAcceptance ===
  676 + 2015-02-04T17:31:59: Name ......................: Background
  677 + 2015-02-04T17:31:59: Instruments ...............: CTA
  678 + 2015-02-04T17:31:59: Instrument scale factors ..: unity
  679 + 2015-02-04T17:31:59: Observation identifiers ...: all
  680 + 2015-02-04T17:31:59: Model type ................: "Gaussian" * "FileFunction" * "Constant"
  681 + 2015-02-04T17:31:59: Number of parameters ......: 3
  682 + 2015-02-04T17:31:59: Number of radial par's ....: 1
  683 + 2015-02-04T17:31:59: Sigma ....................: 3.04429 +/- 0.0330227 [0.01,10] deg2 (free,scale=1,gradient)
  684 + 2015-02-04T17:31:59: Number of spectral par's ..: 1
  685 + 2015-02-04T17:31:59: Normalization ............: 0.996767 +/- 0.0175227 [0,1000] (free,scale=1,gradient)
  686 + 2015-02-04T17:31:59: Number of temporal par's ..: 1
  687 + 2015-02-04T17:31:59: Constant .................: 1 (relative value) (fixed,scale=1,gradient)
  688 + 2015-02-04T17:31:59:
  689 + 2015-02-04T17:31:59: +==============+
  690 + 2015-02-04T17:31:59: | Save results |
  691 + 2015-02-04T17:31:59: +==============+
  692 + 2015-02-04T17:31:59:
  693 + 2015-02-04T17:31:59: Application "ctlike" terminated after 8 wall clock seconds, consuming 0.21275 seconds of CPU time.
652 694  
653 695  
654 696 .. _sec_butterfly_cta:
... ... @@ -657,8 +699,9 @@ Calculate and visualise butterfly
657 699 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
658 700  
659 701 To visualise the analysis results retrieved above, one can calculate the
660   -confidence band of the spectral fit. The tool ctbutterfly takes the optimised
661   -source model as input. It takes the covariance matrix from the fit to conduct a
  702 +confidence band of the spectral fit.
  703 +The :ref:`ctbutterfly` tool takes the optimised source model as input.
  704 +It takes the covariance matrix from the fit to conduct a
662 705 Gaussian error propagation for each energy value. It will write the
663 706 butterfly information into an ASCII file.
664 707 The following example shows how to compute such a butterfly from the command
... ... @@ -676,24 +719,6 @@ line.
676 719 Stop value for last energy bin in TeV [100.0]
677 720 Output ascii file [butterfly.txt]
678 721  
679   -Below some lines of the ``ctbutterfly.log``:
680   -
681   -.. code-block:: xml
682   -
683   - 2014-10-30T17:51:39: +===========================+
684   - 2014-10-30T17:51:39: | Compute covariance matrix |
685   - 2014-10-30T17:51:39: +===========================+
686   - 2014-10-30T17:51:39:
687   - 2014-10-30T17:51:39: +====================+
688   - 2014-10-30T17:51:39: | Generate butterfly |
689   - 2014-10-30T17:51:39: +====================+
690   - 2014-10-30T17:51:39:
691   - 2014-10-30T17:51:39: +========================+
692   - 2014-10-30T17:51:39: | Save Butterfly to file |
693   - 2014-10-30T17:51:39: +========================+
694   - 2014-10-30T17:51:39:
695   - 2014-10-30T17:51:39: Application "ctbutterfly" terminated after 15 wall clock seconds, consuming 0.051253 seconds of CPU time.
696   -
697 722 Now that you have computed the confidence band of the spectral fit and
698 723 that you will have an ASCII file named ``butterfly.txt`` on disk you can
699 724 visualise the butterfly using the script ``show_butterfly.py`` that is
... ...