Karim Sabri / ctools

Commit c1b6ac1b03ef28ec29f57db5b6366b3b424cec76

Authored by Jürgen Knödlseder
1 parent bf06528d

Update ctools documentation.

Inline Side-by-side
Showing 24 changed files with 1259 additions and 1258 deletions
doc/source/download.rst
  View file @c1b6ac1
... ... @@ -13,7 +13,7 @@ bugs.
13 13 Releases
14 14 --------
15 15  
16   -The latest ctools release is ``ctools-0.10.0`` (1 November 2015).
  16 +The latest ctools release is ``ctools-1.0.0`` (6 December 2015).
17 17  
18 18 Below a table of ctools releases. Please note that at this stage of the
19 19 project there is a strict link between the ctools and gammalib versions.
... ... @@ -28,6 +28,9 @@ gammalib.
28 28 * - `ctools <http://cta.irap.omp.eu/ctools/releases/ctools/ChangeLog>`_
29 29 - `gammalib <http://cta.irap.omp.eu/ctools/releases/gammalib/ChangeLog>`_
30 30 - Mac OS X package
  31 + * - `1.0.0 <http://cta.irap.omp.eu/ctools/releases/ctools/ctools-1.0.0.tar.gz>`_
  32 + - `1.0.0 <http://cta.irap.omp.eu/ctools/releases/gammalib/gammalib-1.0.0.tar.gz>`_
  33 + - `ctools-1.0.0-macosx10.3.dmg <http://cta.irap.omp.eu/ctools/releases/ctools/ctools-1.0.0-macosx10.3.dmg>`_
31 34 * - `0.10.0 <http://cta.irap.omp.eu/ctools/releases/ctools/ctools-0.10.0.tar.gz>`_
32 35 - `0.11.0 <http://cta.irap.omp.eu/ctools/releases/gammalib/gammalib-0.11.0.tar.gz>`_
33 36 - `ctools-0.10.0-macosx10.3.dmg <http://cta.irap.omp.eu/ctools/releases/ctools/ctools-0.10.0-macosx10.3.dmg>`_
... ...
doc/source/user_manual/enhancing.rst deleted
View file @bf06528
1   -Enhancing ctools
2   -================
3   -
4   -Most ctools users will run the existing ctools or cscripts,
5   -which cover the most common simulation and analysis needs.
6   -
7   -Advanced users and developers can write their own tools and scripts.
8   -The following C++ and Python examples can help get you started:
9   -
10   -* :doxy:`ctlike`
11   -* :doxy:`obsutils`
12   -* :doxy:`cstsdist`
13   -
14   -Building your own cscripts
15   ---------------------------
16   -
17   -To be written ...
18   -
19   -
20   -Building your own ctools
21   -------------------------
22   -
23   -To be written ...
doc/source/user_manual/expert.rst deleted
View file @bf06528
1   -Behind the scenes
2   -=================
3   -
4   -CTA data structure
5   -------------------
6   -
7   -To be written ...
8   -
9   -
10   -Instrument response functions
11   ------------------------------
12   -
13   -To be written ...
14   -
15   -
16   -Maximum likelihood fitting
17   ---------------------------
18   -
19   -To be written ...
doc/source/user_manual/getting.rst
  View file @c1b6ac1
... ... @@ -29,15 +29,15 @@ No system administrator privileges are needed to install ctools.
29 29  
30 30 .. _sec_installing_gammalib:
31 31  
32   -Installing gammalib
  32 +Installing GammaLib
33 33 -------------------
34 34  
35   -ctools is built on top of gammalib, hence gammalib needs to be built,
  35 +ctools is built on top of GammaLib, hence GammaLib needs to be built,
36 36 installed and configured before ctools can be installed. In case that
37 37 ctools is already installed on your system you may skip reading this
38 38 section and continue with the :ref:`sec_building_ctools` section.
39 39  
40   -You will need the following to build the gammalib:
  40 +You will need the following to build the GammaLib:
41 41  
42 42 - About 200 MB of free disk space.
43 43  
... ... @@ -58,12 +58,12 @@ You will need the following to build the gammalib:
58 58 Furthermore it is recommended to have readline and ncurses installed
59 59 (including the developer packages).
60 60  
61   -After downloading the gammalib tarball (see :ref:`download`), save it
  61 +After downloading the GammaLib tarball (see :ref:`download`), save it
62 62 in an appropriate location (for example ``$HOME/builds``), and type
63 63  
64 64 .. code-block:: bash
65 65  
66   - $ tar xvfz gammalib-0.11.0.tar.gz
  66 + $ tar xvfz gammalib-1.0.0.tar.gz
67 67  
68 68 (the ``$`` symbol indicates the console prompt and is not part of the
69 69 command that you should type in).
... ... @@ -73,7 +73,7 @@ typing
73 73  
74 74 .. code-block:: bash
75 75  
76   - $ cd gammalib-0.11.0
  76 + $ cd gammalib-1.0.0
77 77 $ ./configure
78 78 $ make
79 79 $ make check
... ... @@ -82,6 +82,8 @@ typing
82 82 The last step may require system administator privileges. In this case,
83 83 use
84 84  
  85 +.. code-block:: bash
  86 +
85 87 $ sudo make install
86 88  
87 89 If you do not have system administrator privileges, change the install
... ... @@ -133,7 +135,7 @@ an appropriate location (for example ``$HOME/builds``), and type
133 135  
134 136 .. code-block:: bash
135 137  
136   - $ tar xvfz ctools-0.10.0.tar.gz
  138 + $ tar xvfz ctools-1.0.0.tar.gz
137 139  
138 140 (the ``$`` symbol indicates the console prompt and is not part of the
139 141 command that you should type in).
... ... @@ -142,7 +144,7 @@ Step in the directory and build the ctools by typing
142 144  
143 145 .. code-block:: bash
144 146  
145   - $ cd ctools-0.10.0
  147 + $ cd ctools-1.0.0
146 148 $ ./configure
147 149 $ make
148 150  
... ... @@ -181,7 +183,7 @@ following output at the end of the unit testing:
181 183 PASS: test_python.py
182 184 make[4]: Nothing to be done for `all'.
183 185 ============================================================================
184   - Testsuite summary for ctools 0.10.0
  186 + Testsuite summary for ctools 1.0.0
185 187 ============================================================================
186 188 # TOTAL: 3
187 189 # PASS: 3
... ... @@ -345,19 +347,8 @@ As a quick check that your setup is okay you can run ``csinfo check``:
345 347 ===> Your Gammalib / ctools setup is OK.
346 348  
347 349 If the setup is not okay, run the ``csinfo info`` command to print
348   -detailed information about your setup.
349   -There's also a ``csinfo list`` command to quickly list the available tools:
350   -
351   -.. code-block:: bash
352   -
353   - $ csinfo
354   -
355   - Print info about Gammalib and ctools to the console.
356   -
357   - Available commands:
358   - csinfo list List available ctools and cscripts
359   - csinfo check Check Gammalib / ctools setup
360   - csinfo info Print Gammalib / ctools setup info
  350 +detailed information about your setup. There's also a ``csinfo list``
  351 +command to quickly list the available tools.
361 352  
362 353  
363 354 .. _sec_known_problems:
... ...
doc/source/user_manual/getting_started/beyond.rst
  View file @c1b6ac1
... ... @@ -3,12 +3,12 @@
3 3 Beyond the first steps
4 4 ----------------------
5 5  
6   -Assuming that you have read the :ref:`quickstart <quickstart>` tutorial,
7   -here now some chapters to read if you intend to do more complex
8   -analyses.
9   -Once you have gone through these chapters you should have a pretty complete
  6 +Now that you are familiar with the ctools basics, here are some sections
  7 +to read if you intend to do more complex analyses.
  8 +Once you have gone through these sections you should have a pretty complete
10 9 picture about the capabilities of ctools.
11   -And you should be ready for doing your own cutting edge analyses.
  10 +And you should be ready for doing your own cutting edge CTA science data
  11 +analyses.
12 12  
13 13 .. toctree::
14 14 :maxdepth: 2
... ... @@ -19,11 +19,3 @@ And you should be ready for doing your own cutting edge analyses.
19 19 beyond_residual
20 20 beyond_irf
21 21 beyond_model
22   -
23   -
24   -
25   -
26   -
27   -
28   -
29   -
... ...
doc/source/user_manual/getting_started/beyond_combine.rst
  View file @c1b6ac1
... ... @@ -25,9 +25,9 @@ nebula, each offset by 0.5 deg from the nebula in opposite directions:
25 25 Lower energy limit (TeV) [0.1]
26 26 Upper energy limit (TeV) [100.0]
27 27 Calibration database [prod2]
28   - Instrument response function [South_50h]
29   - Model [$CTOOLS/share/models/crab.xml]
30   - Output event data file or observation definition file [events.fits] events1.fits
  28 + Instrument response function [South_0.5h]
  29 + Input model XML file [$CTOOLS/share/models/crab.xml]
  30 + Output event data file or observation definition XML file [events.fits] events1.fits
31 31  
32 32 .. code-block:: bash
33 33  
... ... @@ -40,16 +40,16 @@ nebula, each offset by 0.5 deg from the nebula in opposite directions:
40 40 Lower energy limit (TeV) [0.1]
41 41 Upper energy limit (TeV) [100.0]
42 42 Calibration database [prod2]
43   - Instrument response function [South_50h]
44   - Model [$CTOOLS/share/models/crab.xml]
45   - Output event data file or observation definition file [events1.fits] events2.fits
  43 + Instrument response function [South_0.5h]
  44 + Input model XML file [$CTOOLS/share/models/crab.xml]
  45 + Output event data file or observation definition XML file [events1.fits] events2.fits
46 46  
47 47 This will produce the two event files ``events1.fits`` and ``events2.fits``
48 48 on disk.
49 49  
50   -As next step we have to create an **observation definition XML file** that
  50 +As next step you have to create an **observation definition XML file** that
51 51 collects both observations in a list.
52   -Here is how such a file would look like:
  52 +Here is how that file looks like:
53 53  
54 54 .. code-block:: xml
55 55  
... ... @@ -86,116 +86,140 @@ ctools knows which instrument specific functions need to be called.**
86 86 Imaging Air Cherenkov Telescope in a joint analysis.
87 87 **Please recall that instrument strings are case sensitive.**
88 88  
89   -Now we are ready to do a joint maximum likelihood analysis using
90   -:ref:`ctlike`:
  89 +Now you are ready to do a joint maximum likelihood analysis using
  90 +:ref:`ctlike`. Type:
91 91  
92 92 .. code-block:: bash
93 93  
94   - $ ctlike
95   - Event list, counts cube or observation definition file [selected_events.fits] obs.xml
  94 + $ ctlike chatter=3
  95 + Input event list, counts cube or observation definition XML file [events.fits] obs.xml
96 96 Calibration database [prod2]
97   - Instrument response function [South_50h]
98   - Source model [$CTOOLS/share/models/crab.xml]
99   - Source model output file [crab_results.xml]
  97 + Instrument response function [South_0.5h]
  98 + Input model XML file [$CTOOLS/share/models/crab.xml]
  99 + Output model XML file [crab_results.xml]
100 100  
101   -Instead of providing an event list or a counts cube, we now provided the
  101 +Instead of providing an event list or a counts cube, you now provided the
102 102 filename of the observation definition XML file (here ``obs.xml``) as input
103   -parameter.
104   -:ref:`ctlike` recognises this format and automatically performs a
105   -joint analysis, as indicated in the log file:
  103 +parameter. :ref:`ctlike` recognises this format and automatically performs a
  104 +joint analysis. To see the result of this you needed to specify the
  105 +``chatter=3`` parameter so that the chattiness is increased in the log
  106 +file:
106 107  
107 108 .. code-block:: xml
108 109  
109   - 2015-05-22T20:17:07: +==============+
110   - 2015-05-22T20:17:07: | Observations |
111   - 2015-05-22T20:17:07: +==============+
112   - 2015-05-22T20:17:07: === GObservations ===
113   - 2015-05-22T20:17:07: Number of observations ....: 2
114   - 2015-05-22T20:17:07: Number of predicted events : 0
115   - 2015-05-22T20:17:07: === GCTAObservation ===
116   - 2015-05-22T20:17:07: Name ......................:
117   - 2015-05-22T20:17:07: Identifier ................: 00001
118   - 2015-05-22T20:17:07: Instrument ................: CTA
119   - 2015-05-22T20:17:07: Event file ................: events1.fits
120   - 2015-05-22T20:17:07: Event type ................: EventList
121   - 2015-05-22T20:17:07: Statistics ................: Poisson
122   - 2015-05-22T20:17:07: Ontime ....................: 1800 s
123   - 2015-05-22T20:17:07: Livetime ..................: 1710 s
124   - 2015-05-22T20:17:07: Deadtime correction .......: 0.95
125   - 2015-05-22T20:17:07: User energy range .........: undefined
126   - 2015-05-22T20:17:07: === GCTAPointing ===
127   - 2015-05-22T20:17:07: Pointing direction ........: (RA,Dec)=(83.63,21.51)
  110 + 2015-12-07T21:23:07: +==============+
  111 + 2015-12-07T21:23:07: | Observations |
  112 + 2015-12-07T21:23:07: +==============+
  113 + 2015-12-07T21:23:07: === GObservations ===
  114 + 2015-12-07T21:23:07: Number of observations ....: 2
  115 + 2015-12-07T21:23:07: Number of models ..........: 2
  116 + 2015-12-07T21:23:07: Number of predicted events : 0
  117 + 2015-12-07T21:23:07: === GCTAObservation ===
  118 + 2015-12-07T21:23:07: Name ......................: Crab
  119 + 2015-12-07T21:23:07: Identifier ................: 00001
  120 + 2015-12-07T21:23:07: Instrument ................: CTA
  121 + 2015-12-07T21:23:07: Event file ................: events1.fits
  122 + 2015-12-07T21:23:07: Event type ................: EventList
  123 + 2015-12-07T21:23:07: Statistics ................: Poisson
  124 + 2015-12-07T21:23:07: Ontime ....................: 1800 s
  125 + 2015-12-07T21:23:07: Livetime ..................: 1710 s
  126 + 2015-12-07T21:23:07: Deadtime correction .......: 0.95
  127 + 2015-12-07T21:23:07: User energy range .........: undefined
  128 + 2015-12-07T21:23:07: === GCTAPointing ===
  129 + 2015-12-07T21:23:07: Pointing direction ........: (RA,Dec)=(83.63,21.51)
  130 + 2015-12-07T21:23:07: === GCTAResponseIrf ===
  131 + 2015-12-07T21:23:07: Caldb mission .............: cta
  132 + 2015-12-07T21:23:07: Caldb instrument ..........: prod2
  133 + 2015-12-07T21:23:07: Response name .............: South_0.5h
  134 + 2015-12-07T21:23:07: Energy dispersion .........: Not used
  135 + 2015-12-07T21:23:07: Save energy range .........: undefined
  136 + 2015-12-07T21:23:07: === GCTAEventList ===
  137 + 2015-12-07T21:23:07: Number of events ..........: 22593
  138 + 2015-12-07T21:23:07: Time interval .............: 51544.5 - 51544.5 days
  139 + 2015-12-07T21:23:07: Energy interval ...........: 0.1 - 100 TeV
  140 + 2015-12-07T21:23:07: Region of interest ........: RA=83.63, DEC=21.51 [0,0] Radius=5 deg
  141 + 2015-12-07T21:23:07: === GCTAObservation ===
  142 + 2015-12-07T21:23:07: Name ......................: Crab
  143 + 2015-12-07T21:23:07: Identifier ................: 00002
  144 + 2015-12-07T21:23:07: Instrument ................: CTA
  145 + 2015-12-07T21:23:07: Event file ................: events2.fits
  146 + 2015-12-07T21:23:07: Event type ................: EventList
  147 + 2015-12-07T21:23:07: Statistics ................: Poisson
  148 + 2015-12-07T21:23:07: Ontime ....................: 1800 s
  149 + 2015-12-07T21:23:07: Livetime ..................: 1710 s
  150 + 2015-12-07T21:23:07: Deadtime correction .......: 0.95
  151 + 2015-12-07T21:23:07: User energy range .........: undefined
  152 + 2015-12-07T21:23:07: === GCTAPointing ===
  153 + 2015-12-07T21:23:07: Pointing direction ........: (RA,Dec)=(83.63,22.51)
  154 + 2015-12-07T21:23:07: === GCTAResponseIrf ===
  155 + 2015-12-07T21:23:07: Caldb mission .............: cta
  156 + 2015-12-07T21:23:07: Caldb instrument ..........: prod2
  157 + 2015-12-07T21:23:07: Response name .............: South_0.5h
  158 + 2015-12-07T21:23:07: Energy dispersion .........: Not used
  159 + 2015-12-07T21:23:07: Save energy range .........: undefined
  160 + 2015-12-07T21:23:07: === GCTAEventList ===
  161 + 2015-12-07T21:23:07: Number of events ..........: 22529
  162 + 2015-12-07T21:23:07: Time interval .............: 51544.5 - 51544.5 days
  163 + 2015-12-07T21:23:07: Energy interval ...........: 0.1 - 100 TeV
  164 + 2015-12-07T21:23:07: Region of interest ........: RA=83.63, DEC=22.51 [0,0] Radius=5 deg
128 165 ...
129   - 2015-05-22T20:17:07: === GCTAObservation ===
130   - 2015-05-22T20:17:07: Name ......................:
131   - 2015-05-22T20:17:07: Identifier ................: 00002
132   - 2015-05-22T20:17:07: Instrument ................: CTA
133   - 2015-05-22T20:17:07: Event file ................: events2.fits
134   - 2015-05-22T20:17:07: Event type ................: EventList
135   - 2015-05-22T20:17:07: Statistics ................: Poisson
136   - 2015-05-22T20:17:07: Ontime ....................: 1800 s
137   - 2015-05-22T20:17:07: Livetime ..................: 1710 s
138   - 2015-05-22T20:17:07: Deadtime correction .......: 0.95
139   - 2015-05-22T20:17:07: User energy range .........: undefined
140   - 2015-05-22T20:17:07: === GCTAPointing ===
141   - 2015-05-22T20:17:07: Pointing direction ........: (RA,Dec)=(83.63,22.51)
  166 + 2015-12-07T21:23:07: +=================================+
  167 + 2015-12-07T21:23:07: | Maximum likelihood optimisation |
  168 + 2015-12-07T21:23:07: +=================================+
  169 + 2015-12-07T21:23:07: >Iteration 0: -logL=304176.886, Lambda=1.0e-03
  170 + 2015-12-07T21:23:08: >Iteration 1: -logL=304161.799, Lambda=1.0e-03, delta=15.088, max(|grad|)=12.922804 [Index:3]
  171 + 2015-12-07T21:23:08: >Iteration 2: -logL=304161.783, Lambda=1.0e-04, delta=0.015, max(|grad|)=0.098155 [Index:3]
  172 + 2015-12-07T21:23:08: >Iteration 3: -logL=304161.783, Lambda=1.0e-05, delta=0.000, max(|grad|)=0.000598 [Index:3]
142 173 ...
143   - 2015-05-22T20:17:07: +=================================+
144   - 2015-05-22T20:17:07: | Maximum likelihood optimisation |
145   - 2015-05-22T20:17:07: +=================================+
146   - 2015-05-22T20:17:07: >Iteration 0: -logL=201836.657, Lambda=1.0e-03
147   - 2015-05-22T20:17:07: >Iteration 1: -logL=201829.438, Lambda=1.0e-03, delta=7.220, max(|grad|)=22.756507 [Index:7]
148   - 2015-05-22T20:17:07: >Iteration 2: -logL=201829.432, Lambda=1.0e-04, delta=0.005, max(|grad|)=0.086395 [Index:3]
149   - 2015-05-22T20:17:07: >Iteration 3: -logL=201829.432, Lambda=1.0e-05, delta=0.000, max(|grad|)=0.001287 [Index:3]
150   - 2015-05-22T20:17:07:
151   - 2015-05-22T20:17:07: +=========================================+
152   - 2015-05-22T20:17:07: | Maximum likelihood optimization results |
153   - 2015-05-22T20:17:07: +=========================================+
154   - 2015-05-22T20:17:07: === GOptimizerLM ===
155   - 2015-05-22T20:17:07: Optimized function value ..: 201829.432
156   - 2015-05-22T20:17:07: Absolute precision ........: 0.005
157   - 2015-05-22T20:17:07: Acceptable value decrease .: 2
158   - 2015-05-22T20:17:07: Optimization status .......: converged
159   - 2015-05-22T20:17:07: Number of parameters ......: 10
160   - 2015-05-22T20:17:07: Number of free parameters .: 4
161   - 2015-05-22T20:17:07: Number of iterations ......: 3
162   - 2015-05-22T20:17:07: Lambda ....................: 1e-06
163   - 2015-05-22T20:17:07: Maximum log likelihood ....: -201829.432
164   - 2015-05-22T20:17:07: Observed events (Nobs) ...: 31799.000
165   - 2015-05-22T20:17:07: Predicted events (Npred) ..: 31799.000 (Nobs - Npred = 2.67544e-06)
166   - 2015-05-22T20:17:07: === GModels ===
167   - 2015-05-22T20:17:07: Number of models ..........: 2
168   - 2015-05-22T20:17:07: Number of parameters ......: 10
169   - 2015-05-22T20:17:07: === GModelSky ===
170   - 2015-05-22T20:17:07: Name ......................: Crab
171   - 2015-05-22T20:17:07: Instruments ...............: all
172   - 2015-05-22T20:17:07: Instrument scale factors ..: unity
173   - 2015-05-22T20:17:07: Observation identifiers ...: all
174   - 2015-05-22T20:17:07: Model type ................: PointSource
175   - 2015-05-22T20:17:07: Model components ..........: "SkyDirFunction" * "PowerLaw" * "Constant"
176   - 2015-05-22T20:17:07: Number of parameters ......: 6
177   - 2015-05-22T20:17:07: Number of spatial par's ...: 2
178   - 2015-05-22T20:17:07: RA .......................: 83.6331 [-360,360] deg (fixed,scale=1)
179   - 2015-05-22T20:17:07: DEC ......................: 22.0145 [-90,90] deg (fixed,scale=1)
180   - 2015-05-22T20:17:07: Number of spectral par's ..: 3
181   - 2015-05-22T20:17:07: Prefactor ................: 5.8727e-16 +/- 8.04314e-18 [1e-23,1e-13] ph/cm2/s/MeV (free,scale=1e-16,gradient)
182   - 2015-05-22T20:17:07: Index ....................: -2.49825 +/- 0.0118418 [-0,-5] (free,scale=-1,gradient)
183   - 2015-05-22T20:17:07: PivotEnergy ..............: 300000 [10000,1e+09] MeV (fixed,scale=1e+06,gradient)
184   - 2015-05-22T20:17:07: Number of temporal par's ..: 1
185   - 2015-05-22T20:17:07: Normalization ............: 1 (relative value) (fixed,scale=1,gradient)
186   - 2015-05-22T20:17:07: === GCTAModelIrfBackground ===
187   - 2015-05-22T20:17:07: Name ......................: CTABackgroundModel
188   - 2015-05-22T20:17:07: Instruments ...............: CTA
189   - 2015-05-22T20:17:07: Instrument scale factors ..: unity
190   - 2015-05-22T20:17:07: Observation identifiers ...: all
191   - 2015-05-22T20:17:07: Model type ................: "PowerLaw" * "Constant"
192   - 2015-05-22T20:17:07: Number of parameters ......: 4
193   - 2015-05-22T20:17:07: Number of spectral par's ..: 3
194   - 2015-05-22T20:17:07: Prefactor ................: 1.01608 +/- 0.0152751 [0.001,1000] ph/cm2/s/MeV (free,scale=1,gradient)
195   - 2015-05-22T20:17:07: Index ....................: 0.0226023 +/- 0.0086794 [-5,5] (free,scale=1,gradient)
196   - 2015-05-22T20:17:07: PivotEnergy ..............: 1e+06 [10000,1e+09] MeV (fixed,scale=1e+06,gradient)
197   - 2015-05-22T20:17:07: Number of temporal par's ..: 1
198   - 2015-05-22T20:17:07: Normalization ............: 1 (relative value) (fixed,scale=1,gradient)
  174 +
  175 + 2015-12-07T21:23:08: +=========================================+
  176 + 2015-12-07T21:23:08: | Maximum likelihood optimisation results |
  177 + 2015-12-07T21:23:08: +=========================================+
  178 + 2015-12-07T21:23:08: === GOptimizerLM ===
  179 + 2015-12-07T21:23:08: Optimized function value ..: 304161.783
  180 + 2015-12-07T21:23:08: Absolute precision ........: 0.005
  181 + 2015-12-07T21:23:08: Acceptable value decrease .: 2
  182 + 2015-12-07T21:23:08: Optimization status .......: converged
  183 + 2015-12-07T21:23:08: Number of parameters ......: 10
  184 + 2015-12-07T21:23:08: Number of free parameters .: 4
  185 + 2015-12-07T21:23:08: Number of iterations ......: 3
  186 + 2015-12-07T21:23:08: Lambda ....................: 1e-06
  187 + 2015-12-07T21:23:08: Maximum log likelihood ....: -304161.783
  188 + 2015-12-07T21:23:08: Observed events (Nobs) ...: 45122.000
  189 + 2015-12-07T21:23:08: Predicted events (Npred) ..: 45122.000 (Nobs - Npred = 1.04131e-06)
  190 + 2015-12-07T21:23:08: === GModels ===
  191 + 2015-12-07T21:23:08: Number of models ..........: 2
  192 + 2015-12-07T21:23:08: Number of parameters ......: 10
  193 + 2015-12-07T21:23:08: === GModelSky ===
  194 + 2015-12-07T21:23:08: Name ......................: Crab
  195 + 2015-12-07T21:23:08: Instruments ...............: all
  196 + 2015-12-07T21:23:08: Instrument scale factors ..: unity
  197 + 2015-12-07T21:23:08: Observation identifiers ...: all
  198 + 2015-12-07T21:23:08: Model type ................: PointSource
  199 + 2015-12-07T21:23:08: Model components ..........: "SkyDirFunction" * "PowerLaw" * "Constant"
  200 + 2015-12-07T21:23:08: Number of parameters ......: 6
  201 + 2015-12-07T21:23:08: Number of spatial par's ...: 2
  202 + 2015-12-07T21:23:08: RA .......................: 83.6331 [-360,360] deg (fixed,scale=1)
  203 + 2015-12-07T21:23:08: DEC ......................: 22.0145 [-90,90] deg (fixed,scale=1)
  204 + 2015-12-07T21:23:08: Number of spectral par's ..: 3
  205 + 2015-12-07T21:23:08: Prefactor ................: 5.78382e-16 +/- 7.27218e-18 [1e-23,1e-13] ph/cm2/s/MeV (free,scale=1e-16,gradient)
  206 + 2015-12-07T21:23:08: Index ....................: -2.5314 +/- 0.0112546 [-0,-5] (free,scale=-1,gradient)
  207 + 2015-12-07T21:23:08: PivotEnergy ..............: 300000 [10000,1e+09] MeV (fixed,scale=1e+06,gradient)
  208 + 2015-12-07T21:23:08: Number of temporal par's ..: 1
  209 + 2015-12-07T21:23:08: Normalization ............: 1 (relative value) (fixed,scale=1,gradient)
  210 + 2015-12-07T21:23:08: === GCTAModelIrfBackground ===
  211 + 2015-12-07T21:23:08: Name ......................: CTABackgroundModel
  212 + 2015-12-07T21:23:08: Instruments ...............: CTA
  213 + 2015-12-07T21:23:08: Instrument scale factors ..: unity
  214 + 2015-12-07T21:23:08: Observation identifiers ...: all
  215 + 2015-12-07T21:23:08: Model type ................: "PowerLaw" * "Constant"
  216 + 2015-12-07T21:23:08: Number of parameters ......: 4
  217 + 2015-12-07T21:23:08: Number of spectral par's ..: 3
  218 + 2015-12-07T21:23:08: Prefactor ................: 1.0008 +/- 0.00839192 [0.001,1000] ph/cm2/s/MeV (free,scale=1,gradient)
  219 + 2015-12-07T21:23:08: Index ....................: 0.0102998 +/- 0.0051965 [-5,5] (free,scale=1,gradient)
  220 + 2015-12-07T21:23:08: PivotEnergy ..............: 1e+06 [10000,1e+09] MeV (fixed,scale=1e+06,gradient)
  221 + 2015-12-07T21:23:08: Number of temporal par's ..: 1
  222 + 2015-12-07T21:23:08: Normalization ............: 1 (relative value) (fixed,scale=1,gradient)
199 223  
200 224 The log file indicates that the fit converged quickly, the spectral
201 225 parameters of the Crab nebula have now been constrained using the events
... ...
doc/source/user_manual/getting_started/beyond_irf.rst
  View file @c1b6ac1
... ... @@ -6,9 +6,9 @@ Connecting observations to dedicated instrument response functions
6 6 So far the same instrument response function has been used for all
7 7 observations in our analysis examples.
8 8 You may have recognised that we always specified the calibration database
9   -``prod2`` and the instrument response function ``South_50h`` that
  9 +``prod2`` and the instrument response function ``South_0.5h`` that
10 10 are shipped with ctools.
11   -When combining multiple observations in a joint analysis we may however
  11 +When combining multiple observations in a joint analysis you may however
12 12 need to specify dedicated instrument response functions for the
13 13 different observations.
14 14  
... ... @@ -26,40 +26,40 @@ the northern array and the other with the southern array:
26 26 Lower energy limit (TeV) [0.1]
27 27 Upper energy limit (TeV) [100.0]
28 28 Calibration database [prod2]
29   - Instrument response function [South_50h] North_50h
30   - Model [$CTOOLS/share/models/crab.xml]
31   - Output event data file or observation definition file [events.fits] events1.fits
  29 + Instrument response function [South_0.5h] North_0.5h
  30 + Input model XML file [$CTOOLS/share/models/crab.xml]
  31 + Output event data file or observation definition XML file [events.fits] north.fits
32 32  
33 33 .. code-block:: bash
34 34  
35 35 $ ctobssim
36 36 RA of pointing (degrees) (0-360) [83.63]
37   - Dec of pointing (degrees) (-90-90) [22.01] 22.51
  37 + Dec of pointing (degrees) (-90-90) [21.51] 22.51
38 38 Radius of FOV (degrees) (0-180) [5.0]
39 39 Start time (MET in s) [0.0]
40 40 End time (MET in s) [1800.0]
41 41 Lower energy limit (TeV) [0.1]
42 42 Upper energy limit (TeV) [100.0]
43 43 Calibration database [prod2]
44   - Instrument response function [North_50h] South_50h
45   - Model [$CTOOLS/share/models/crab.xml]
46   - Output event data file or observation definition file [events1.fits] events2.fits
  44 + Instrument response function [North_0.5h] South_0.5h
  45 + Input model XML file [$CTOOLS/share/models/crab.xml]
  46 + Output event data file or observation definition XML file [north.fits] south.fits
47 47  
48   -Now we combine the information about these two observations in an
  48 +You now need to combine the information about these two observations in an
49 49 observation definition XML file:
50 50  
51 51 .. code-block:: xml
52 52  
53   - <?xml version="1.0" standalone="no"?>
54   - <observation_list title="observation library">
55   - <observation name="Crab" id="00001" instrument="CTA">
56   - <parameter name="EventList" file="events1.fits"/>
57   - <parameter name="Calibration" database="prod2" response="North_50h"/>
58   - </observation>
59   - <observation name="Crab" id="00002" instrument="CTA">
60   - <parameter name="EventList" file="events2.fits"/>
61   - <parameter name="Calibration" database="prod2" response="South_50h"/>
62   - </observation>
  53 + <?xml version="1.0" standalone="no"?>
  54 + <observation_list title="observation library">
  55 + <observation name="Crab" id="00001" instrument="CTA">
  56 + <parameter name="EventList" file="north.fits"/>
  57 + <parameter name="Calibration" database="prod2" response="North_0.5h"/>
  58 + </observation>
  59 + <observation name="Crab" id="00002" instrument="CTA">
  60 + <parameter name="EventList" file="south.fits"/>
  61 + <parameter name="Calibration" database="prod2" response="South_0.5h"/>
  62 + </observation>
63 63 </observation_list>
64 64  
65 65 Each observation now has a ``Calibration`` parameter with the attributes
... ... @@ -97,126 +97,136 @@ Within this database there are six response functions:
97 97 ``North_0.5h``, ``North_5h``, ``North_50h``,
98 98 ``South_0.5h``, ``South_5h``, and ``South_50h``.
99 99  
100   -We now jointly fit both observations using :ref:`ctlike`:
  100 +You now jointly fit both observations using :ref:`ctlike`:
101 101  
102 102 .. code-block:: bash
103 103  
104   - $ ctlike
105   - Event list, counts cube or observation definition file [obs.xml] obs_irf.xml
106   - Source model [$CTOOLS/share/models/crab.xml]
107   - Source model output file [crab_results.xml]
  104 + $ ctlike chatter=3
  105 + Input event list, counts cube or observation definition XML file [events.fits] obs_irf.xml
  106 + Input model XML file [$CTOOLS/share/models/crab.xml]
  107 + Output model XML file [crab_results.xml]
108 108  
109 109 To see the usage of the individual response functions you may inspect the
110   -log file. You will notice that each observation now has a specific response
  110 +log file (you need to set ``chatter=3`` to see the details of the
  111 +observations in the log file).
  112 +You will notice that each observation now has a specific response
111 113 function and that the filename of the response information differs for
112 114 both observations.
113 115  
114 116 .. code-block:: xml
115 117  
116   - 2015-05-22T22:06:43: +==============+
117   - 2015-05-22T22:06:43: | Observations |
118   - 2015-05-22T22:06:43: +==============+
119   - 2015-05-22T22:06:43: === GObservations ===
120   - 2015-05-22T22:06:43: Number of observations ....: 2
121   - 2015-05-22T22:06:43: Number of predicted events : 0
122   - 2015-05-22T22:06:43: === GCTAObservation ===
123   - 2015-05-22T22:06:43: Name ......................:
124   - 2015-05-22T22:06:43: Identifier ................: 00001
125   - 2015-05-22T22:06:43: Instrument ................: CTA
126   - 2015-05-22T22:06:43: Event file ................: events1.fits
127   - 2015-05-22T22:06:43: Event type ................: EventList
128   - 2015-05-22T22:06:43: Statistics ................: Poisson
129   - 2015-05-22T22:06:43: Ontime ....................: 1800 s
130   - 2015-05-22T22:06:43: Livetime ..................: 1710 s
131   - 2015-05-22T22:06:43: Deadtime correction .......: 0.95
132   - 2015-05-22T22:06:43: User energy range .........: undefined
133   - 2015-05-22T22:06:43: === GCTAPointing ===
134   - 2015-05-22T22:06:43: Pointing direction ........: (RA,Dec)=(83.63,21.51)
135   - 2015-05-22T22:06:43: === GCTAResponseIrf ===
136   - 2015-05-22T22:06:43: Caldb mission .............: cta
137   - 2015-05-22T22:06:43: Caldb instrument ..........: prod2
138   - 2015-05-22T22:06:43: Response name .............: North_50h
139   - 2015-05-22T22:06:43: Energy dispersion .........: Not used
140   - 2015-05-22T22:06:43: Save energy range .........: undefined
  118 + 2015-12-07T22:22:18: +==============+
  119 + 2015-12-07T22:22:18: | Observations |
  120 + 2015-12-07T22:22:18: +==============+
  121 + 2015-12-07T22:22:18: === GObservations ===
  122 + 2015-12-07T22:22:18: Number of observations ....: 2
  123 + 2015-12-07T22:22:18: Number of models ..........: 2
  124 + 2015-12-07T22:22:18: Number of predicted events : 0
  125 + 2015-12-07T22:22:18: === GCTAObservation ===
  126 + 2015-12-07T22:22:18: Name ......................: Crab
  127 + 2015-12-07T22:22:18: Identifier ................: 00001
  128 + 2015-12-07T22:22:18: Instrument ................: CTA
  129 + 2015-12-07T22:22:18: Event file ................: north.fits
  130 + 2015-12-07T22:22:18: Event type ................: EventList
  131 + 2015-12-07T22:22:18: Statistics ................: Poisson
  132 + 2015-12-07T22:22:18: Ontime ....................: 1800 s
  133 + 2015-12-07T22:22:18: Livetime ..................: 1710 s
  134 + 2015-12-07T22:22:18: Deadtime correction .......: 0.95
  135 + 2015-12-07T22:22:18: User energy range .........: undefined
  136 + 2015-12-07T22:22:18: === GCTAPointing ===
  137 + 2015-12-07T22:22:18: Pointing direction ........: (RA,Dec)=(83.63,21.51)
  138 + 2015-12-07T22:22:18: === GCTAResponseIrf ===
  139 + 2015-12-07T22:22:18: Caldb mission .............: cta
  140 + 2015-12-07T22:22:18: Caldb instrument ..........: prod2
  141 + 2015-12-07T22:22:18: Response name .............: North_0.5h
  142 + 2015-12-07T22:22:18: Energy dispersion .........: Not used
  143 + 2015-12-07T22:22:18: Save energy range .........: undefined
  144 + 2015-12-07T22:22:18: === GCTAEventList ===
  145 + 2015-12-07T22:22:18: Number of events ..........: 8469
  146 + 2015-12-07T22:22:18: Time interval .............: 51544.5 - 51544.5 days
  147 + 2015-12-07T22:22:18: Energy interval ...........: 0.1 - 100 TeV
  148 + 2015-12-07T22:22:18: Region of interest ........: RA=83.63, DEC=21.51 [0,0] Radius=5 deg
  149 + 2015-12-07T22:22:18: === GCTAObservation ===
  150 + 2015-12-07T22:22:18: Name ......................: Crab
  151 + 2015-12-07T22:22:18: Identifier ................: 00002
  152 + 2015-12-07T22:22:18: Instrument ................: CTA
  153 + 2015-12-07T22:22:18: Event file ................: south.fits
  154 + 2015-12-07T22:22:18: Event type ................: EventList
  155 + 2015-12-07T22:22:18: Statistics ................: Poisson
  156 + 2015-12-07T22:22:18: Ontime ....................: 1800 s
  157 + 2015-12-07T22:22:18: Livetime ..................: 1710 s
  158 + 2015-12-07T22:22:18: Deadtime correction .......: 0.95
  159 + 2015-12-07T22:22:18: User energy range .........: undefined
  160 + 2015-12-07T22:22:18: === GCTAPointing ===
  161 + 2015-12-07T22:22:18: Pointing direction ........: (RA,Dec)=(83.63,22.51)
  162 + 2015-12-07T22:22:18: === GCTAResponseIrf ===
  163 + 2015-12-07T22:22:18: Caldb mission .............: cta
  164 + 2015-12-07T22:22:18: Caldb instrument ..........: prod2
  165 + 2015-12-07T22:22:18: Response name .............: South_0.5h
  166 + 2015-12-07T22:22:18: Energy dispersion .........: Not used
  167 + 2015-12-07T22:22:18: Save energy range .........: undefined
  168 + 2015-12-07T22:22:18: === GCTAEventList ===
  169 + 2015-12-07T22:22:18: Number of events ..........: 22529
  170 + 2015-12-07T22:22:18: Time interval .............: 51544.5 - 51544.5 days
  171 + 2015-12-07T22:22:18: Energy interval ...........: 0.1 - 100 TeV
  172 + 2015-12-07T22:22:18: Region of interest ........: RA=83.63, DEC=22.51 [0,0] Radius=5 deg
141 173 ...
142   - 2015-05-22T22:06:43: === GCTAObservation ===
143   - 2015-05-22T22:06:43: Name ......................:
144   - 2015-05-22T22:06:43: Identifier ................: 00002
145   - 2015-05-22T22:06:43: Instrument ................: CTA
146   - 2015-05-22T22:06:43: Event file ................: events2.fits
147   - 2015-05-22T22:06:43: Event type ................: EventList
148   - 2015-05-22T22:06:43: Statistics ................: Poisson
149   - 2015-05-22T22:06:43: Ontime ....................: 1800 s
150   - 2015-05-22T22:06:43: Livetime ..................: 1710 s
151   - 2015-05-22T22:06:43: Deadtime correction .......: 0.95
152   - 2015-05-22T22:06:43: User energy range .........: undefined
153   - 2015-05-22T22:06:43: === GCTAPointing ===
154   - 2015-05-22T22:06:43: Pointing direction ........: (RA,Dec)=(83.63,22.51)
155   - 2015-05-22T22:06:43: === GCTAResponseIrf ===
156   - 2015-05-22T22:06:43: Caldb mission .............: cta
157   - 2015-05-22T22:06:43: Caldb instrument ..........: prod2
158   - 2015-05-22T22:06:43: Response name .............: South_50h
159   - 2015-05-22T22:06:43: Energy dispersion .........: Not used
160   - 2015-05-22T22:06:43: Save energy range .........: undefined
  174 + 2015-12-07T22:22:18: +=================================+
  175 + 2015-12-07T22:22:18: | Maximum likelihood optimisation |
  176 + 2015-12-07T22:22:18: +=================================+
  177 + 2015-12-07T22:22:18: >Iteration 0: -logL=214691.468, Lambda=1.0e-03
  178 + 2015-12-07T22:22:18: >Iteration 1: -logL=214679.380, Lambda=1.0e-03, delta=12.088, max(|grad|)=9.713100 [Index:3]
  179 + 2015-12-07T22:22:18: >Iteration 2: -logL=214679.365, Lambda=1.0e-04, delta=0.015, max(|grad|)=0.092975 [Index:3]
  180 + 2015-12-07T22:22:18: >Iteration 3: -logL=214679.365, Lambda=1.0e-05, delta=0.000, max(|grad|)=0.000749 [Index:3]
161 181 ...
162   - 2015-05-22T22:06:43: +=================================+
163   - 2015-05-22T22:06:43: | Maximum likelihood optimisation |
164   - 2015-05-22T22:06:43: +=================================+
165   - 2015-05-22T22:06:43: >Iteration 0: -logL=138039.472, Lambda=1.0e-03
166   - 2015-05-22T22:06:43: >Iteration 1: -logL=138035.501, Lambda=1.0e-03, delta=3.971, max(|grad|)=16.203761 [Index:7]
167   - 2015-05-22T22:06:43: >Iteration 2: -logL=138035.496, Lambda=1.0e-04, delta=0.005, max(|grad|)=-0.053284 [Index:7]
168   - 2015-05-22T22:06:43: >Iteration 3: -logL=138035.496, Lambda=1.0e-05, delta=0.000, max(|grad|)=0.001386 [Index:7]
169   - 2015-05-22T22:06:44:
170   - 2015-05-22T22:06:44: +=========================================+
171   - 2015-05-22T22:06:44: | Maximum likelihood optimization results |
172   - 2015-05-22T22:06:44: +=========================================+
173   - 2015-05-22T22:06:44: === GOptimizerLM ===
174   - 2015-05-22T22:06:44: Optimized function value ..: 138035.496
175   - 2015-05-22T22:06:44: Absolute precision ........: 0.005
176   - 2015-05-22T22:06:44: Acceptable value decrease .: 2
177   - 2015-05-22T22:06:44: Optimization status .......: converged
178   - 2015-05-22T22:06:44: Number of parameters ......: 10
179   - 2015-05-22T22:06:44: Number of free parameters .: 4
180   - 2015-05-22T22:06:44: Number of iterations ......: 3
181   - 2015-05-22T22:06:44: Lambda ....................: 1e-06
182   - 2015-05-22T22:06:44: Maximum log likelihood ....: -138035.496
183   - 2015-05-22T22:06:44: Observed events (Nobs) ...: 20814.000
184   - 2015-05-22T22:06:44: Predicted events (Npred) ..: 20814.000 (Nobs - Npred = 2.67698e-06)
185   - 2015-05-22T22:06:44: === GModels ===
186   - 2015-05-22T22:06:44: Number of models ..........: 2
187   - 2015-05-22T22:06:44: Number of parameters ......: 10
188   - 2015-05-22T22:06:44: === GModelSky ===
189   - 2015-05-22T22:06:44: Name ......................: Crab
190   - 2015-05-22T22:06:44: Instruments ...............: all
191   - 2015-05-22T22:06:44: Instrument scale factors ..: unity
192   - 2015-05-22T22:06:44: Observation identifiers ...: all
193   - 2015-05-22T22:06:44: Model type ................: PointSource
194   - 2015-05-22T22:06:44: Model components ..........: "SkyDirFunction" * "PowerLaw" * "Constant"
195   - 2015-05-22T22:06:44: Number of parameters ......: 6
196   - 2015-05-22T22:06:44: Number of spatial par's ...: 2
197   - 2015-05-22T22:06:44: RA .......................: 83.6331 [-360,360] deg (fixed,scale=1)
198   - 2015-05-22T22:06:44: DEC ......................: 22.0145 [-90,90] deg (fixed,scale=1)
199   - 2015-05-22T22:06:44: Number of spectral par's ..: 3
200   - 2015-05-22T22:06:44: Prefactor ................: 5.9184e-16 +/- 9.68924e-18 [1e-23,1e-13] ph/cm2/s/MeV (free,scale=1e-16,gradient)
201   - 2015-05-22T22:06:44: Index ....................: -2.49569 +/- 0.0145376 [-0,-5] (free,scale=-1,gradient)
202   - 2015-05-22T22:06:44: PivotEnergy ..............: 300000 [10000,1e+09] MeV (fixed,scale=1e+06,gradient)
203   - 2015-05-22T22:06:44: Number of temporal par's ..: 1
204   - 2015-05-22T22:06:44: Normalization ............: 1 (relative value) (fixed,scale=1,gradient)
205   - 2015-05-22T22:06:44: === GCTAModelIrfBackground ===
206   - 2015-05-22T22:06:44: Name ......................: CTABackgroundModel
207   - 2015-05-22T22:06:44: Instruments ...............: CTA
208   - 2015-05-22T22:06:44: Instrument scale factors ..: unity
209   - 2015-05-22T22:06:44: Observation identifiers ...: all
210   - 2015-05-22T22:06:44: Model type ................: "PowerLaw" * "Constant"
211   - 2015-05-22T22:06:44: Number of parameters ......: 4
212   - 2015-05-22T22:06:44: Number of spectral par's ..: 3
213   - 2015-05-22T22:06:44: Prefactor ................: 1.02524 +/- 0.0182054 [0.001,1000] ph/cm2/s/MeV (free,scale=1,gradient)
214   - 2015-05-22T22:06:44: Index ....................: 0.0229728 +/- 0.0104713 [-5,5] (free,scale=1,gradient)
215   - 2015-05-22T22:06:44: PivotEnergy ..............: 1e+06 [10000,1e+09] MeV (fixed,scale=1e+06,gradient)
216   - 2015-05-22T22:06:44: Number of temporal par's ..: 1
217   - 2015-05-22T22:06:44: Normalization ............: 1 (relative value) (fixed,scale=1,gradient)
218   -
219   -
  182 + 2015-12-07T22:22:18: +=========================================+
  183 + 2015-12-07T22:22:18: | Maximum likelihood optimisation results |
  184 + 2015-12-07T22:22:18: +=========================================+
  185 + 2015-12-07T22:22:18: === GOptimizerLM ===
  186 + 2015-12-07T22:22:18: Optimized function value ..: 214679.365
  187 + 2015-12-07T22:22:18: Absolute precision ........: 0.005
  188 + 2015-12-07T22:22:18: Acceptable value decrease .: 2
  189 + 2015-12-07T22:22:18: Optimization status .......: converged
  190 + 2015-12-07T22:22:18: Number of parameters ......: 10
  191 + 2015-12-07T22:22:18: Number of free parameters .: 4
  192 + 2015-12-07T22:22:18: Number of iterations ......: 3
  193 + 2015-12-07T22:22:18: Lambda ....................: 1e-06
  194 + 2015-12-07T22:22:18: Maximum log likelihood ....: -214679.365
  195 + 2015-12-07T22:22:18: Observed events (Nobs) ...: 30998.000
  196 + 2015-12-07T22:22:18: Predicted events (Npred) ..: 30998.000 (Nobs - Npred = 1.02755e-06)
  197 + 2015-12-07T22:22:18: === GModels ===
  198 + 2015-12-07T22:22:18: Number of models ..........: 2
  199 + 2015-12-07T22:22:18: Number of parameters ......: 10
  200 + 2015-12-07T22:22:18: === GModelSky ===
  201 + 2015-12-07T22:22:18: Name ......................: Crab
  202 + 2015-12-07T22:22:18: Instruments ...............: all
  203 + 2015-12-07T22:22:18: Instrument scale factors ..: unity
  204 + 2015-12-07T22:22:18: Observation identifiers ...: all
  205 + 2015-12-07T22:22:18: Model type ................: PointSource
  206 + 2015-12-07T22:22:18: Model components ..........: "SkyDirFunction" * "PowerLaw" * "Constant"
  207 + 2015-12-07T22:22:18: Number of parameters ......: 6
  208 + 2015-12-07T22:22:18: Number of spatial par's ...: 2
  209 + 2015-12-07T22:22:18: RA .......................: 83.6331 [-360,360] deg (fixed,scale=1)
  210 + 2015-12-07T22:22:18: DEC ......................: 22.0145 [-90,90] deg (fixed,scale=1)
  211 + 2015-12-07T22:22:18: Number of spectral par's ..: 3
  212 + 2015-12-07T22:22:18: Prefactor ................: 5.81237e-16 +/- 8.63534e-18 [1e-23,1e-13] ph/cm2/s/MeV (free,scale=1e-16,gradient)
  213 + 2015-12-07T22:22:18: Index ....................: -2.53954 +/- 0.0137432 [-0,-5] (free,scale=-1,gradient)
  214 + 2015-12-07T22:22:18: PivotEnergy ..............: 300000 [10000,1e+09] MeV (fixed,scale=1e+06,gradient)
  215 + 2015-12-07T22:22:18: Number of temporal par's ..: 1
  216 + 2015-12-07T22:22:18: Normalization ............: 1 (relative value) (fixed,scale=1,gradient)
  217 + 2015-12-07T22:22:18: === GCTAModelIrfBackground ===
  218 + 2015-12-07T22:22:18: Name ......................: CTABackgroundModel
  219 + 2015-12-07T22:22:18: Instruments ...............: CTA
  220 + 2015-12-07T22:22:18: Instrument scale factors ..: unity
  221 + 2015-12-07T22:22:18: Observation identifiers ...: all
  222 + 2015-12-07T22:22:18: Model type ................: "PowerLaw" * "Constant"
  223 + 2015-12-07T22:22:18: Number of parameters ......: 4
  224 + 2015-12-07T22:22:18: Number of spectral par's ..: 3
  225 + 2015-12-07T22:22:18: Prefactor ................: 1.01067 +/- 0.0103997 [0.001,1000] ph/cm2/s/MeV (free,scale=1,gradient)
  226 + 2015-12-07T22:22:18: Index ....................: 0.0135414 +/- 0.0064452 [-5,5] (free,scale=1,gradient)
  227 + 2015-12-07T22:22:18: PivotEnergy ..............: 1e+06 [10000,1e+09] MeV (fixed,scale=1e+06,gradient)
  228 + 2015-12-07T22:22:18: Number of temporal par's ..: 1
  229 + 2015-12-07T22:22:18: Normalization ............: 1 (relative value) (fixed,scale=1,gradient)
220 230  
221 231 A more fine grained control over the response function can be achieved by
222 232 specifying individual filenames for the various response components.
... ... @@ -228,18 +238,18 @@ This is definitely expert mode, to be used with utmost care.
228 238 <?xml version="1.0" standalone="no"?>
229 239 <observation_list title="observation library">
230 240 <observation name="Crab" id="00001" instrument="CTA">
231   - <parameter name="EventList" file="events1.fits"/>
232   - <parameter name="EffectiveArea" file="$(CALDB)/data/cta/prod2/bcf/North_50h/irf_file.fits.gz"/>
233   - <parameter name="PointSpreadFunction" file="$(CALDB)/data/cta/prod2/bcf/North_50h/irf_file.fits.gz"/>
234   - <parameter name="EnergyDispersion" file="$(CALDB)/data/cta/prod2/bcf/North_50h/irf_file.fits.gz"/>
235   - <parameter name="Background" file="$(CALDB)/data/cta/prod2/bcf/North_50h/irf_file.fits.gz"/>
  241 + <parameter name="EventList" file="north.fits"/>
  242 + <parameter name="EffectiveArea" file="$(CALDB)/data/cta/prod2/bcf/North_0.5h/irf_file.fits.gz"/>
  243 + <parameter name="PointSpreadFunction" file="$(CALDB)/data/cta/prod2/bcf/North_0.5h/irf_file.fits.gz"/>
  244 + <parameter name="EnergyDispersion" file="$(CALDB)/data/cta/prod2/bcf/North_0.5h/irf_file.fits.gz"/>
  245 + <parameter name="Background" file="$(CALDB)/data/cta/prod2/bcf/North_0.5h/irf_file.fits.gz"/>
236 246 </observation>
237 247 <observation name="Crab" id="00002" instrument="CTA">
238   - <parameter name="EventList" file="events2.fits"/>
239   - <parameter name="EffectiveArea" file="$(CALDB)/data/cta/prod2/bcf/South_50h/irf_file.fits.gz"/>
240   - <parameter name="PointSpreadFunction" file="$(CALDB)/data/cta/prod2/bcf/South_50h/irf_file.fits.gz"/>
241   - <parameter name="EnergyDispersion" file="$(CALDB)/data/cta/prod2/bcf/South_50h/irf_file.fits.gz"/>
242   - <parameter name="Background" file="$(CALDB)/data/cta/prod2/bcf/South_50h/irf_file.fits.gz"/>
  248 + <parameter name="EventList" file="south.fits"/>
  249 + <parameter name="EffectiveArea" file="$(CALDB)/data/cta/prod2/bcf/South_0.5h/irf_file.fits.gz"/>
  250 + <parameter name="PointSpreadFunction" file="$(CALDB)/data/cta/prod2/bcf/South_0.5h/irf_file.fits.gz"/>
  251 + <parameter name="EnergyDispersion" file="$(CALDB)/data/cta/prod2/bcf/South_0.5h/irf_file.fits.gz"/>
  252 + <parameter name="Background" file="$(CALDB)/data/cta/prod2/bcf/South_0.5h/irf_file.fits.gz"/>
243 253 </observation>
244 254 </observation_list>
245 255  
... ... @@ -264,5 +274,3 @@ file is given below:
264 274 <parameter name="BkgCube" file="bkgcube2.fits"/>
265 275 </observation>
266 276 </observation_list>
267   -
268   -
... ...
doc/source/user_manual/getting_started/beyond_model.rst
  View file @c1b6ac1
... ... @@ -26,20 +26,15 @@ specified by the following observation definition XML file:
26 26 </observation>
27 27 </observation_list>
28 28  
29   -Each observation has a **unique identifier string** and we can use this
30   -unique string to connect that observation to a specific model component.
  29 +Each observation has a **unique identifier string** and you can use this
  30 +unique string to connect an observation to a specific model component.
31 31 This is illustrated in the model XML file below that now has two background
32 32 components.
33   -**Model components in a XML file need to have a unique name**, for this
34   -reason we have named the components ``Background_00001`` and
35   -``Background_00002``.
36   -Both components now have an ``id`` attribute that ties the model to
37   -an observation.
38   -In other words, the model is only applicable to a specific observation
39   -(it will be ignored for all other observations).
40   -In our case, model ``Background_00001`` applies to the ``events1.fits``
41   -event list while model ``Background_00002`` applies to the ``events2.fits``
42   -event list.
  33 +Both components have an ``id`` attribute that ties the model to a specific
  34 +observation.
  35 +Using ``id="00001"``, the first background model is tied to the
  36 +``events1.fits`` file, using ``id="00002"``, the second background model is
  37 +tied to the ``events2.fits`` file.
43 38  
44 39 .. code-block:: xml
45 40  
... ... @@ -72,13 +67,21 @@ event list.
72 67 </source>
73 68 </source_library>
74 69  
75   -Note that both background model components distinguish in their event rate;
76   -component ``Background_00002`` has a ten times larger background rate than
77   -component ``Background_00001``.
78   -To illustrate this difference, we simulated two observations offset by
79   -+/- 2 degrees from the Crab nebulae using :ref:`ctobssim`.
80   -We then performed a joint fit of the observations using :ref:`ctlike`
81   -and created a resdiual map using :ref:`csresmap` that is shown below.
  70 +.. note::
  71 +
  72 + **Model components in a XML file need to have a unique name.**
  73 + For this reason the components are named here ``Background_00001``
  74 + and ``Background_00002``.
  75 +
  76 +Note that both background model components distinguish in their event rate.
  77 +``Background_00002`` has a ten times larger background rate than
  78 +``Background_00001``.
  79 +To illustrate this difference, two observations offset by +/- 2 degrees from
  80 +the Crab nebulae have been simulated using :ref:`ctobssim`.
  81 +A joint fit of the observations is then performed using :ref:`ctlike` and
  82 +a residual map is created using :ref:`csresmap`.
  83 +
  84 +The result is shown below.
82 85 Obviously, the upper observation has larger residuals owing to the ten
83 86 times larger background rate that was used in the simulation of the
84 87 associated data.
... ...
doc/source/user_manual/getting_started/beyond_residual.rst
  View file @c1b6ac1
... ... @@ -22,11 +22,11 @@ Suppose that you have done the following unbinned ``ctlike`` analysis:
22 22 .. code-block:: bash
23 23  
24 24 $ ctlike
25   - Event list, counts cube or observation definition file [events.fits] obs.xml
  25 + Input event list, counts cube or observation definition XML file [events.fits] obs.xml
26 26 Calibration database [prod2]
27   - Instrument response function [South_50h]
28   - Source model [$CTOOLS/share/models/crab.xml]
29   - Source model output file [crab_results.xml]
  27 + Instrument response function [South_0.5h]
  28 + Input model XML file [$CTOOLS/share/models/crab.xml]
  29 + Output model XML file [crab_results.xml]
30 30  
31 31 The :ref:`csresmap` script is then used as follows:
32 32  
... ... @@ -34,18 +34,19 @@ The :ref:`csresmap` script is then used as follows:
34 34  
35 35 $ csresmap
36 36 Parfile csresmap.par not found. Create default parfile.
37   - Event list, counts cube, or observation definition file [events.fits] obs.xml
  37 + Input event list, counts cube, or observation definition XML file [events.fits] obs.xml
38 38 Calibration database [prod2]
39   - Instrument response function [South_50h]
40   - Source model [$CTOOLS/share/models/crab.xml] crab_results.xml
41   - Output residual map [resmap.fits]
42   - First coordinate of image center in degrees (RA or galactic l) [83.63]
43   - Second coordinate of image center in degrees (DEC or galactic b) [22.01]
  39 + Instrument response function [South_0.5h]
  40 + Input model XML file [$CTOOLS/share/models/crab.xml] crab_results.xml
  41 + First coordinate of image center in degrees (RA or galactic l) (0-360) [83.63]
  42 + Second coordinate of image center in degrees (DEC or galactic b) (-90-90) [22.01]
44 43 Coordinate System (CEL|GAL) [CEL]
45   - Projection method e.g. AIT|AZP|CAR|MER|MOL|STG|TAN (AIT|AZP|CAR|MER|MOL|STG|TAN) [CAR]
  44 + Projection method (AIT|AZP|CAR|MER|MOL|STG|TAN) [CAR]
46 45 Size of the X axis in pixels [200]
47 46 Size of the Y axis in pixels [200]
48 47 Pixel size (deg/pixel) [0.02]
  48 + Output residual map file [resmap.fits]
  49 + Residual map computation algorithm (SUB|SUBDIV|SUBDIVSQRT) [SUBDIV]
49 50  
50 51 In our example, the map will cover a field of 4 x 4 degrees centred on the
51 52 Crab nebula at a pixel scale of 0.02 degrees per pixel.
... ...
doc/source/user_manual/getting_started/beyond_stacked.rst
  View file @c1b6ac1
... ... @@ -6,16 +6,15 @@ Performing a stacked analysis
6 6 A stacked analysis is a binned analysis where all data from multiple
7 7 observations are stacked into a single counts cube.
8 8 The event stacking is done using the :ref:`ctbin` tool.
9   -Instead of providing to :ref:`ctbin` an event list we
10   -now specify the observation definition XML file ``obs.xml``
11   -on input.
  9 +Instead of providing to :ref:`ctbin` an event list you should now
  10 +specify the observation definition XML file ``obs.xml`` on input.
12 11 :ref:`ctbin` will then loop over all observations and collect all events
13 12 into a single counts cube:
14 13  
15 14 .. code-block:: bash
16 15  
17 16 $ ctbin
18   - Event list or observation definition file [events.fits] obs.xml
  17 + Input event list or observation definition XML file [events.fits] obs.xml
19 18 First coordinate of image center in degrees (RA or galactic l) (0-360) [83.63]
20 19 Second coordinate of image center in degrees (DEC or galactic b) (-90-90) [22.01]
21 20 Projection method (AIT|AZP|CAR|MER|MOL|STG|TAN) [CAR]
... ... @@ -27,37 +26,37 @@ into a single counts cube:
27 26 Start value for first energy bin in TeV [0.1]
28 27 Stop value for last energy bin in TeV [100.0]
29 28 Number of energy bins [20]
30   - Output counts cube [cntcube.fits]
  29 + Output counts cube file [cntcube.fits]
31 30  
32   -We now have a stacked counts cube ``cntcube.fits`` on disk.
33   -Before we can use that counts cube in a maximum likelihood
34   -analysis, we have to compute the instrument response and the
  31 +You now have a stacked counts cube ``cntcube.fits`` on disk.
  32 +Before you can use that counts cube in a maximum likelihood
  33 +analysis, you have to compute the instrument response and the
35 34 background model that are needed to describe the stacked data.
36 35  
37   -For the former, we have to compute the total exposure for the stacked
  36 +For the former, you have to compute the total exposure for the stacked
38 37 cube (i.e. the sum of the effective areas for each observation multiplied
39 38 by the corresponding livetimes) and an effective point spread function
40 39 (i.e. the point spread function of the different observations weighted by
41 40 the corresponding exposures).
42   -To get both informations we use the :ref:`ctexpcube` and
  41 +To get both informations you use the :ref:`ctexpcube` and
43 42 :ref:`ctpsfcube` tools:
44 43  
45 44 .. code-block:: bash
46 45  
47 46 $ ctexpcube
48   - Event list or observation definition file [NONE] obs.xml
  47 + Input event list or observation definition XML file [NONE] obs.xml
49 48 Calibration database [prod2]
50   - Instrument response function [South_50h]
51   - Counts cube for exposure cube definition [NONE] cntcube.fits
  49 + Instrument response function [South_0.5h]
  50 + Input counts cube file to extract exposure cube definition [NONE] cntcube.fits
52 51 Output exposure cube file [expcube.fits]
53 52  
54 53 .. code-block:: bash
55 54  
56 55 $ ctpsfcube
57   - Event list or observation definition file [NONE] obs.xml
  56 + Input event list or observation definition XML file [NONE] obs.xml
58 57 Calibration database [prod2]
59   - Instrument response function [South_50h]
60   - Counts cube for psf cube definition [NONE]
  58 + Instrument response function [South_0.5h]
  59 + Input counts cube file to extract PSF cube definition [NONE]
61 60 First coordinate of image center in degrees (RA or galactic l) (0-360) [83.63]
62 61 Second coordinate of image center in degrees (DEC or galactic b) (-90-90) [22.01]
63 62 Projection method (AIT|AZP|CAR|MER|MOL|STG|TAN) [CAR]
... ... @@ -68,42 +67,41 @@ To get both informations we use the :ref:`ctexpcube` and
68 67 Lower energy limit (TeV) [0.1]
69 68 Upper energy limit (TeV) [100.0]
70 69 Number of energy bins [20]
71   - Output psf cube file [psfcube.fits]
72   -
73   -We provide the ``obs.xml`` file on input to inform both tools which
74   -observations have been combined.
75   -For :ref:`ctexpcube` we further provide the counts cube so that the
76   -tool can copy the exposure cube definition (number of spatial pixels
77   -and pixel size, number of energy bins) from the counts cube.
78   -This minimises the number of further user parameters that need to be
79   -provided and assures an exposure cube that is compatible with the counts
80   -cube.
81   -For :ref:`ctpsfcube` we do not use the counts cube for the PSF cube
82   -definition as this would lead to a hugh file owing to the fine spatial
  70 + Output PSF cube file [psfcube.fits]
  71 +
  72 +The ``obs.xml`` file has been provided on input to specify for both tools
  73 +which observations have been combined.
  74 +You further provided the counts cube on input so that :ref:`ctexpcube` can
  75 +read the cub definition from that file and apply it to the exposure cube.
  76 +This is a trick to reduce the number of user parameters that you need to
  77 +provide.
  78 +
  79 +You do not apply this trick when using :ref:`ctpsfcube` as this
  80 +would lead to a hugh output file owing to the fine spatial
83 81 pixelisation of the counts cube.
84   -Since the PSF evolves only slowly over the field of fiew, we provide a
85   -rather coarse spatial binning of 1 degree covering a grid of 10 x 10
86   -degrees around the centre of the counts cube.
87   -For the energy binning, we use the same logarithmic binning that has
88   -also been used for the counts cube.
  82 +Such a fine binning is not needed for the PSF cube, as the PSF evolves
  83 +only slowly over the field of view.
  84 +It is thus sufficient to compute a PSF cube with a rather coarse spatial
  85 +binning; here you used a spatial binning of 1 degree covering a grid of
  86 +10 x 10 degrees.
89 87  
90   -As final step of the analysis preparation, we need to generate a
  88 +As final step of the analysis preparation, you need to generate a
91 89 background cube using the :ref:`ctbkgcube` tool:
92 90  
93 91 .. code-block:: bash
94 92  
95 93 $ ctbkgcube
96   - Input event list or observation definition file [NONE] obs.xml
  94 + Input event list or observation definition XML file [NONE] obs.xml
97 95 Calibration database [prod2]
98   - Instrument response function [South_50h]
99   - Counts cube for background cube definition [NONE] cntcube.fits
  96 + Instrument response function [South_0.5h]
  97 + Input counts cube file to extract background cube definition [NONE] cntcube.fits
100 98 Input model XML file [NONE] $CTOOLS/share/models/crab.xml
101 99 Output background cube file [bkgcube.fits]
102 100 Output model XML file [NONE] model.xml
103 101  
104 102 The usage of :ref:`ctbkgcube` is very similar to that of :ref:`ctexpcube`,
105 103 yet it takes the model XML file as an additional input parameter.
106   -We here use the usual ``$CTOOLS/share/models/crab.xml`` model
  104 +You used here the usual ``$CTOOLS/share/models/crab.xml`` model
107 105 file that is shipped with the ctools.
108 106 :ref:`ctbkgcube` provides on output the background cube file
109 107 ``bkgcube.fits`` and the model XML file ``model.xml`` that can
... ... @@ -115,7 +113,7 @@ modelling works:
115 113  
116 114 <?xml version="1.0" encoding="UTF-8" standalone="no"?>
117 115 <source_library title="source library">
118   - <source name="Crab" type="PointSource" tscalc="0">
  116 + <source name="Crab" type="PointSource">
119 117 <spectrum type="PowerLaw">
120 118 <parameter name="Prefactor" value="5.7" error="0" scale="1e-16" min="1e-07" max="1000" free="1" />
121 119 <parameter name="Index" value="2.48" error="0" scale="-1" min="0" max="5" free="1" />
... ... @@ -157,88 +155,88 @@ as an appropriate multiplicator to the background cube.
157 155 Using the same binning for the exposure cube, the background cube and
158 156 the counts cube is only a convenience.
159 157  
160   -Now we have all files at hand to launch a stacked maximum likelihood
  158 +Now you have all files at hand to perform a stacked maximum likelihood
161 159 analysis using the :ref:`ctlike` tool:
162 160  
163 161 .. code-block:: bash
164 162  
165 163 $ ctlike
166   - Event list, counts cube or observation definition file [obs.xml] cntcube.fits
167   - Exposure cube file (only needed for stacked analysis) [NONE] expcube.fits
168   - PSF cube file (only needed for stacked analysis) [NONE] psfcube.fits
169   - Background cube file (only needed for stacked analysis) [NONE] bkgcube.fits
170   - Source model [$CTOOLS/share/models/crab.xml] model.xml
171   - Source model output file [crab_results.xml]
  164 + Input event list, counts cube or observation definition XML file [obs.xml] cntcube.fits
  165 + Input exposure cube file (only needed for stacked analysis) [NONE] expcube.fits
  166 + Input PSF cube file (only needed for stacked analysis) [NONE] psfcube.fits
  167 + Input background cube file (only needed for stacked analysis) [NONE] bkgcube.fits
  168 + Input model XML file [$CTOOLS/share/models/crab.xml] model.xml
  169 + Output model XML file [crab_results.xml]
172 170  
173 171 :ref:`ctlike` recognises that a counts cube should be analysed and queries
174 172 for the exposure cube, the PSF cube, and the background cube file names.
175   -We specified the names of the files produced by the :ref:`ctexpcube`,
  173 +You specified here the names of the files produced by the :ref:`ctexpcube`,
176 174 the :ref:`ctpsfcube` and the :ref:`ctbkgcube` tools.
177   -Furthermore we provided as model the ``model.xml`` file that has been
  175 +Furthermore you provided as model the ``model.xml`` file that has been
178 176 generated by the :ref:`ctbkgcube` tool.
179 177  
180 178 The log file of the :ref:`ctlike` run is shown below.
181 179 Note that the spectral model that is multiplied with the background
182   -cube has a Prefactor of 1.09 +/- 0.02 and an Index of 0.03 +/- 0.01,
  180 +cube has a Prefactor of 0.998 +/- 0.011 and an Index of 0.006 +/- 0.007,
183 181 indicating a very small correction to the actual spectrum of the background
184 182 cube.
185 183 Real life situations may of course require larger correction factors.
186 184  
187 185 .. code-block:: xml
188 186  
189   - 2015-05-22T21:10:09: +=================================+
190   - 2015-05-22T21:10:09: | Maximum likelihood optimisation |
191   - 2015-05-22T21:10:09: +=================================+
192   - 2015-05-22T21:10:10: >Iteration 0: -logL=60663.798, Lambda=1.0e-03
193   - 2015-05-22T21:10:11: >Iteration 1: -logL=60642.413, Lambda=1.0e-03, delta=21.385, max(|grad|)=120.031102 [Index:7]
194   - 2015-05-22T21:10:13: >Iteration 2: -logL=60642.233, Lambda=1.0e-04, delta=0.180, max(|grad|)=1.139187 [Index:7]
195   - 2015-05-22T21:10:14: >Iteration 3: -logL=60642.233, Lambda=1.0e-05, delta=0.000, max(|grad|)=-0.001247 [Index:7]
196   - 2015-05-22T21:10:16:
197   - 2015-05-22T21:10:16: +=========================================+
198   - 2015-05-22T21:10:16: | Maximum likelihood optimization results |
199   - 2015-05-22T21:10:16: +=========================================+
200   - 2015-05-22T21:10:16: === GOptimizerLM ===
201   - 2015-05-22T21:10:16: Optimized function value ..: 60642.233
202   - 2015-05-22T21:10:16: Absolute precision ........: 0.005
203   - 2015-05-22T21:10:16: Acceptable value decrease .: 2
204   - 2015-05-22T21:10:16: Optimization status .......: converged
205   - 2015-05-22T21:10:16: Number of parameters ......: 10
206   - 2015-05-22T21:10:16: Number of free parameters .: 4
207   - 2015-05-22T21:10:16: Number of iterations ......: 3
208   - 2015-05-22T21:10:16: Lambda ....................: 1e-06
209   - 2015-05-22T21:10:16: Maximum log likelihood ....: -60642.233
210   - 2015-05-22T21:10:16: Observed events (Nobs) ...: 25963.000
211   - 2015-05-22T21:10:16: Predicted events (Npred) ..: 25963.000 (Nobs - Npred = 1.5749e-05)
212   - 2015-05-22T21:10:16: === GModels ===
213   - 2015-05-22T21:10:16: Number of models ..........: 2
214   - 2015-05-22T21:10:16: Number of parameters ......: 10
215   - 2015-05-22T21:10:16: === GModelSky ===
216   - 2015-05-22T21:10:16: Name ......................: Crab
217   - 2015-05-22T21:10:16: Instruments ...............: all
218   - 2015-05-22T21:10:16: Instrument scale factors ..: unity
219   - 2015-05-22T21:10:16: Observation identifiers ...: all
220   - 2015-05-22T21:10:16: Model type ................: PointSource
221   - 2015-05-22T21:10:16: Model components ..........: "SkyDirFunction" * "PowerLaw" * "Constant"
222   - 2015-05-22T21:10:16: Number of parameters ......: 6
223   - 2015-05-22T21:10:16: Number of spatial par's ...: 2
224   - 2015-05-22T21:10:16: RA .......................: 83.6331 [-360,360] deg (fixed,scale=1)
225   - 2015-05-22T21:10:16: DEC ......................: 22.0145 [-90,90] deg (fixed,scale=1)
226   - 2015-05-22T21:10:16: Number of spectral par's ..: 3
227   - 2015-05-22T21:10:16: Prefactor ................: 5.8499e-16 +/- 8.02289e-18 [1e-23,1e-13] ph/cm2/s/MeV (free,scale=1e-16,gradient)
228   - 2015-05-22T21:10:16: Index ....................: -2.49909 +/- 0.0118976 [-0,-5] (free,scale=-1,gradient)
229   - 2015-05-22T21:10:16: PivotEnergy ..............: 300000 [10000,1e+09] MeV (fixed,scale=1e+06,gradient)
230   - 2015-05-22T21:10:16: Number of temporal par's ..: 1
231   - 2015-05-22T21:10:16: Normalization ............: 1 (relative value) (fixed,scale=1,gradient)
232   - 2015-05-22T21:10:16: === GCTAModelCubeBackground ===
233   - 2015-05-22T21:10:16: Name ......................: BackgroundModel
234   - 2015-05-22T21:10:16: Instruments ...............: CTA, HESS, MAGIC, VERITAS
235   - 2015-05-22T21:10:16: Instrument scale factors ..: unity
236   - 2015-05-22T21:10:16: Observation identifiers ...: all
237   - 2015-05-22T21:10:16: Model type ................: "PowerLaw" * "Constant"
238   - 2015-05-22T21:10:16: Number of parameters ......: 4
239   - 2015-05-22T21:10:16: Number of spectral par's ..: 3
240   - 2015-05-22T21:10:16: Prefactor ................: 1.08781 +/- 0.0212678 [0,infty[ ph/cm2/s/MeV (free,scale=1,gradient)
241   - 2015-05-22T21:10:16: Index ....................: 0.0269681 +/- 0.0111532 [-10,10] (free,scale=1,gradient)
242   - 2015-05-22T21:10:16: PivotEnergy ..............: 1e+06 MeV (fixed,scale=1e+06,gradient)
243   - 2015-05-22T21:10:16: Number of temporal par's ..: 1
244   - 2015-05-22T21:10:16: Normalization ............: 1 (relative value) (fixed,scale=1,gradient)
  187 + 2015-12-07T21:37:45: +=================================+
  188 + 2015-12-07T21:37:45: | Maximum likelihood optimisation |
  189 + 2015-12-07T21:37:45: +=================================+
  190 + 2015-12-07T21:37:46: >Iteration 0: -logL=83748.453, Lambda=1.0e-03
  191 + 2015-12-07T21:37:47: >Iteration 1: -logL=83736.039, Lambda=1.0e-03, delta=12.413, max(|grad|)=15.134616 [Index:3]
  192 + 2015-12-07T21:37:48: >Iteration 2: -logL=83736.021, Lambda=1.0e-04, delta=0.018, max(|grad|)=0.108613 [Index:3]
  193 + 2015-12-07T21:37:49: >Iteration 3: -logL=83736.021, Lambda=1.0e-05, delta=0.000, max(|grad|)=0.000570 [Index:3]
  194 + ...
  195 + 2015-12-07T21:37:51: +=========================================+
  196 + 2015-12-07T21:37:51: | Maximum likelihood optimisation results |
  197 + 2015-12-07T21:37:51: +=========================================+
  198 + 2015-12-07T21:37:51: === GOptimizerLM ===
  199 + 2015-12-07T21:37:51: Optimized function value ..: 83736.021
  200 + 2015-12-07T21:37:51: Absolute precision ........: 0.005
  201 + 2015-12-07T21:37:51: Acceptable value decrease .: 2
  202 + 2015-12-07T21:37:51: Optimization status .......: converged
  203 + 2015-12-07T21:37:51: Number of parameters ......: 10
  204 + 2015-12-07T21:37:51: Number of free parameters .: 4
  205 + 2015-12-07T21:37:51: Number of iterations ......: 3
  206 + 2015-12-07T21:37:51: Lambda ....................: 1e-06
  207 + 2015-12-07T21:37:51: Maximum log likelihood ....: -83736.021
  208 + 2015-12-07T21:37:51: Observed events (Nobs) ...: 35198.000
  209 + 2015-12-07T21:37:51: Predicted events (Npred) ..: 35198.000 (Nobs - Npred = 7.6773e-07)
  210 + 2015-12-07T21:37:51: === GModels ===
  211 + 2015-12-07T21:37:51: Number of models ..........: 2
  212 + 2015-12-07T21:37:51: Number of parameters ......: 10
  213 + 2015-12-07T21:37:51: === GModelSky ===
  214 + 2015-12-07T21:37:51: Name ......................: Crab
  215 + 2015-12-07T21:37:51: Instruments ...............: all
  216 + 2015-12-07T21:37:51: Instrument scale factors ..: unity
  217 + 2015-12-07T21:37:51: Observation identifiers ...: all
  218 + 2015-12-07T21:37:51: Model type ................: PointSource
  219 + 2015-12-07T21:37:51: Model components ..........: "SkyDirFunction" * "PowerLaw" * "Constant"
  220 + 2015-12-07T21:37:51: Number of parameters ......: 6
  221 + 2015-12-07T21:37:51: Number of spatial par's ...: 2
  222 + 2015-12-07T21:37:51: RA .......................: 83.6331 [-360,360] deg (fixed,scale=1)
  223 + 2015-12-07T21:37:51: DEC ......................: 22.0145 [-90,90] deg (fixed,scale=1)
  224 + 2015-12-07T21:37:51: Number of spectral par's ..: 3
  225 + 2015-12-07T21:37:51: Prefactor ................: 5.75289e-16 +/- 7.24749e-18 [1e-23,1e-13] ph/cm2/s/MeV (free,scale=1e-16,gradient)
  226 + 2015-12-07T21:37:51: Index ....................: -2.53122 +/- 0.0113068 [-0,-5] (free,scale=-1,gradient)
  227 + 2015-12-07T21:37:51: PivotEnergy ..............: 300000 [10000,1e+09] MeV (fixed,scale=1e+06,gradient)
  228 + 2015-12-07T21:37:51: Number of temporal par's ..: 1
  229 + 2015-12-07T21:37:51: Normalization ............: 1 (relative value) (fixed,scale=1,gradient)
  230 + 2015-12-07T21:37:51: === GCTAModelCubeBackground ===
  231 + 2015-12-07T21:37:51: Name ......................: BackgroundModel
  232 + 2015-12-07T21:37:51: Instruments ...............: CTA, HESS, MAGIC, VERITAS
  233 + 2015-12-07T21:37:51: Instrument scale factors ..: unity
  234 + 2015-12-07T21:37:51: Observation identifiers ...: all
  235 + 2015-12-07T21:37:51: Model type ................: "PowerLaw" * "Constant"
  236 + 2015-12-07T21:37:51: Number of parameters ......: 4
  237 + 2015-12-07T21:37:51: Number of spectral par's ..: 3
  238 + 2015-12-07T21:37:51: Prefactor ................: 0.998055 +/- 0.0114979 [0.01,100] ph/cm2/s/MeV (free,scale=1,gradient)
  239 + 2015-12-07T21:37:51: Index ....................: 0.00648796 +/- 0.00697365 [-5,5] (free,scale=1,gradient)
  240 + 2015-12-07T21:37:51: PivotEnergy ..............: 1e+06 MeV (fixed,scale=1e+06,gradient)
  241 + 2015-12-07T21:37:51: Number of temporal par's ..: 1
  242 + 2015-12-07T21:37:51: Normalization ............: 1 (relative value) (fixed,scale=1,gradient)
... ...
doc/source/user_manual/getting_started/beyond_tsmap.rst
  View file @c1b6ac1
... ... @@ -3,13 +3,14 @@
3 3 Generating a Test Statistic map
4 4 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5 5  
6   -In the above examples we were always considering that we knew exactly
  6 +In the above examples you have always considering that you knew exactly
7 7 where the source is located, but in real life situations this may not
8 8 necessarily be the case.
9   -We thus need a means to search for significant excess emission in our data.
  9 +You thus need a means to search for significant excess emission in your data.
10 10 One possibility to accomplish this task is to compute the Test Statistic
11 11 for a specific source at a grid of trial positions.
12 12 The :ref:`cttsmap` tool will exactly do that job.
  13 +
13 14 The Test Statistic is defined as twice the log-likelihood difference
14 15 between fitting a source at a given position on top of a model or fitting
15 16 no source.
... ... @@ -18,7 +19,7 @@ the source detection significance in Gaussian sigmas, although the
18 19 exact relation depends somewhat on the formulation of the statistical
19 20 problem.
20 21  
21   -Here an example where we apply the :ref:`cttsmap` tool to our two
  22 +Here an example of how to apply the :ref:`cttsmap` tool to the two
22 23 simulated observations of the Crab in unbinned mode.
23 24 On input we provide a source model XML file and the name of the source
24 25 in the XML file that should be moved on a grid of test positions.
... ... @@ -31,11 +32,11 @@ nominal position of the Crab nebula with a grid spacing of 0.02 degrees.
31 32 .. code-block:: bash
32 33  
33 34 $ cttsmap
34   - Input event list, counts cube or observation definition file [events.fits] obs.xml
  35 + Input event list, counts cube or observation definition XML file [events.fits] obs.xml
35 36 Calibration database [prod2]
36   - Instrument response function [South_50h]
37   - Source model [$CTOOLS/share/models/crab.xml]
38   - Test source [Crab]
  37 + Instrument response function [South_0.5h]
  38 + Input model XML file [$CTOOLS/share/models/crab.xml]
  39 + Test source name [Crab]
39 40 First coordinate of image center in degrees (RA or galactic l) (0-360) [83.63]
40 41 Second coordinate of image center in degrees (DEC or galactic b) (-90-90) [22.01]
41 42 Projection method (AIT|AZP|CAR|MER|MOL|STG|TAN) [CAR]
... ... @@ -43,14 +44,14 @@ nominal position of the Crab nebula with a grid spacing of 0.02 degrees.
43 44 Image scale (in degrees/pixel) [0.02]
44 45 Size of the X axis in pixels [200] 10
45 46 Size of the Y axis in pixels [200] 10
46   - Output Test Statistic map [tsmap.fits]
  47 + Output Test Statistic map file [tsmap.fits]
47 48  
48 49 :ref:`cttsmap` writes the Test Statistic map in the ``tsmap.fits`` file
49 50 that contains one extension for the Test Statistic value and further
50 51 extensions for the spectral parameters that have been fitted for the
51 52 source at each position of the grid.
52 53 The figure below show the Test Statistic map which reaches a maximum
53   -value of 37484 near the centre of the map.
  54 +value of 40733 near the centre of the map.
54 55  
55 56 .. figure:: tsmap-crab.png
56 57 :height: 400px
... ...
doc/source/user_manual/getting_started/binning.rst 0 → 100644
  View file @c1b6ac1
  1 +.. _sec_binning_cta:
  2 +
  3 +Binning CTA data
  4 +~~~~~~~~~~~~~~~~
  5 +
  6 +As next analysis step you will bin the data in a counts cube using
  7 +:ref:`ctbin`.
  8 +A counts cube is a 3 dimensional data cube, spanned by
  9 +Right Ascension (or Galactic longitude), Declination (or Galactic latitude),
  10 +and energy (typically logarithmically spaced, but this is under user
  11 +control).
  12 +
  13 +:ref:`ctbin` is executed by typing:
  14 +
  15 +.. code-block:: bash
  16 +
  17 + $ ctbin
  18 + Input event list or observation definition XML file [events.fits]
  19 + First coordinate of image center in degrees (RA or galactic l) (0-360) [83.63]
  20 + Second coordinate of image center in degrees (DEC or galactic b) (-90-90) [22.01]
  21 + Projection method (AIT|AZP|CAR|MER|MOL|STG|TAN) [CAR]
  22 + Coordinate system (CEL - celestial, GAL - galactic) (CEL|GAL) [CEL]
  23 + Image scale (in degrees/pixel) [0.02]
  24 + Size of the X axis in pixels [200]
  25 + Size of the Y axis in pixels [200]
  26 + Algorithm for defining energy bins (FILE|LIN|LOG) [LOG]
  27 + Start value for first energy bin in TeV [0.1]
  28 + Stop value for last energy bin in TeV [100.0]
  29 + Number of energy bins [20]
  30 + Output counts cube file [cntcube.fits]
  31 +
  32 +The counts cube will be centred on the location of the Crab (Right Ascension
  33 +83.63 degrees, Declination 22.01 degrees) and will be aligned in celestial
  34 +coordinates. A cartesian projection has been selected. The counts cube has
  35 +200 x 200 spatial pixels of 0.02 x 0.02 degrees in size, hence it covers a
  36 +total area of 4 x 4 degrees.
  37 +
  38 +The counts cube will contain 20 maps, which are logarithmically spaced
  39 +in energy, and which cover the energy range from 0.1 TeV to 100 TeV. In this
  40 +example, the counts cube will be saved as ``cntcube.fits`` in the working
  41 +directory. In addition to the counts cube, that is stored as the primary
  42 +image extension, the FITS file also contains an extension named ``EBOUNDS``
  43 +that defines the energy boundaries that were used, and an extension ``GTI``
  44 +that defines the Good Time Intervals that have been used. The following
  45 +image shows the resulting FITS file. The ``EBOUNDS`` table has 20 rows, one
  46 +for each energy bin, while the ``GTI`` table has just a single row, indicating
  47 +the start and stop time of the simulated data.
  48 +
  49 +.. figure:: cntmap-fits.jpg
  50 + :width: 600px
  51 + :align: center
  52 +
  53 + *Counts cube FITS file*
  54 +
  55 +
  56 +An image of the first bin, covering the energy range 100 - 141 GeV, is
  57 +shown below:
  58 +
  59 +.. figure:: cntmap-map.jpg
  60 + :height: 400px
  61 + :align: center
  62 +
  63 + *Counts cube for first energy bin*
  64 +
  65 +For illustration, the last few lines of the log file ``ctbin.log`` are
  66 +reproduced below:
  67 +
  68 +.. code-block:: xml
  69 +
  70 + 2015-12-07T20:52:41: +=================+
  71 + 2015-12-07T20:52:41: | Bin observation |
  72 + 2015-12-07T20:52:41: +=================+
  73 + 2015-12-07T20:52:41: === CTA observation ===
  74 + 2015-12-07T20:52:41: Events in list ............: 22685
  75 + 2015-12-07T20:52:41: Events in cube ............: 18195
  76 + 2015-12-07T20:52:41: Event bins outside RoI ....: 0
  77 + 2015-12-07T20:52:41: Events outside cube area ..: 4490
  78 + 2015-12-07T20:52:41: Events outside energy bins : 0
  79 +
  80 +From the 22685 events that have been simulated and stored in the
  81 +``events.fits`` file, 18195 lie within the cube boundaries and are thus put
  82 +into the resulting counts cube. The counts cube is stored in a cartesian
  83 +projection in a World Coordinate System (WCS) compliant format.
... ...
doc/source/user_manual/getting_started/butterfly.rst 0 → 100644
  View file @c1b6ac1
  1 +.. _sec_butterfly_cta:
  2 +
  3 +Calculating and visualising a butterfly diagram
  4 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  5 +
  6 +To visualise the analysis results you can compute a butterfly diagram
  7 +which shows the confidence band of the spectral fit using the
  8 +:ref:`ctbutterfly` tool.
  9 +The butterfly diagram is the envelope of all power law models
  10 +that are within a given confidence limit compatible with the data.
  11 +By default a confidence level of 68% is used, but the level can be adjusted
  12 +using the hidden ``confidence`` parameter.
  13 +:ref:`ctbutterfly` computes this envelope by evaluating for each energy the
  14 +minimum and maximum intensity of all power law models that fall within the
  15 +error ellipse of the prefactor and index parameters.
  16 +The error ellipse is derived from the covariance matrix of a maximum
  17 +likelihood fit.
  18 +
  19 +The following example illustrates how you can use the :ref:`ctbutterfly`
  20 +tool:
  21 +
  22 +.. code-block:: bash
  23 +
  24 + $ ctbutterfly
  25 + Input event list, counts cube or observation definition XML file [events.fits]
  26 + Calibration database [prod2]
  27 + Instrument response function [South_0.5h]
  28 + Input model XML file [$CTOOLS/share/models/crab.xml] crab_results.xml
  29 + Source of interest [Crab]
  30 + Start value for first energy bin in TeV [0.1]
  31 + Stop value for last energy bin in TeV [100.0]
  32 + Output ASCII file [butterfly.txt]
  33 +
  34 +Now that you have computed the confidence band of the spectral fit and
  35 +that you will have an ASCII file named ``butterfly.txt`` on disk you can
  36 +visualise the butterfly using the script ``show_butterfly.py`` that is
  37 +in the ctools ``example`` folder. You will need matplotlib on your system
  38 +to make this work. To launch the script, type:
  39 +
  40 +.. code-block:: bash
  41 +
  42 + python $CTOOLS/share/examples/python/show_butterfly.py butterfly.txt
  43 +
  44 +This will result in a canvas which should look like the following:
  45 +
  46 +.. figure:: butterfly.jpg
  47 + :height: 400px
  48 + :align: center
  49 +
  50 + *Confidence band of the fit*
  51 +
0 52 \ No newline at end of file
... ...
doc/source/user_manual/getting_started/fitting.rst 0 → 100644
  View file @c1b6ac1
  1 +.. _sec_fitting_cta:
  2 +
  3 +Fitting CTA data
  4 +~~~~~~~~~~~~~~~~
  5 +
  6 +Now we are ready to fit the simulated data with a model. For simplicity
  7 +we use in this example the same model that we used to simulate the data
  8 +with :ref:`ctobssim`. Model fitting is done using the :ref:`ctlike` tool,
  9 +and we do the fit by typing:
  10 +
  11 +.. code-block:: bash
  12 +
  13 + $ ctlike
  14 + Input event list, counts cube or observation definition XML file [events.fits] cntcube.fits
  15 + Input exposure cube file (only needed for stacked analysis) [NONE]
  16 + Input PSF cube file (only needed for stacked analysis) [NONE]
  17 + Input background cube file (only needed for stacked analysis) [NONE]
  18 + Calibration database [prod2]
  19 + Instrument response function [South_0.5h]
  20 + Input model XML file [$CTOOLS/share/models/crab.xml]
  21 + Output model XML file [crab_results.xml]
  22 +
  23 +The data are fitted in *binned* mode, which means that the events
  24 +have been binned into a counts cube and the fit computes the log-likelihood
  25 +function by summing over all 200 x 200 x 20 bins of the counts cube. There is
  26 +an alternative method, the so called *unbinned* mode, where the events are
  27 +not binned into a counts cube and the log-likelihood is computed directly by
  28 +summing over all events. We will explore the *unbinned* mode later.
  29 +
  30 +One of the parameters of :ref:`ctlike` is a source model output file
  31 +(we specified ``crab_results.xml`` in the example), and this file will be
  32 +a copy of the source model input XML file where the parameter values have
  33 +been replaced by the fit results. In addition, the statistical uncertainties
  34 +are added for each fitted parameter using the attribute ``error``.
  35 +Below we show the XML result file that has been produced by the run:
  36 +
  37 +.. code-block:: xml
  38 +
  39 + <?xml version="1.0" encoding="UTF-8" standalone="no"?>
  40 + <source_library title="source library">
  41 + <source name="Crab" type="PointSource">
  42 + <spectrum type="PowerLaw">
  43 + <parameter name="Prefactor" value="5.78443" error="0.101348" scale="1e-16" min="1e-07" max="1000" free="1" />
  44 + <parameter name="Index" value="2.50664" error="0.0153631" scale="-1" min="0" max="5" free="1" />
  45 + <parameter name="Scale" value="0.3" scale="1e+06" min="0.01" max="1000" free="0" />
  46 + </spectrum>
  47 + <spatialModel type="SkyDirFunction">
  48 + <parameter name="RA" value="83.6331" scale="1" min="-360" max="360" free="0" />
  49 + <parameter name="DEC" value="22.0145" scale="1" min="-90" max="90" free="0" />
  50 + </spatialModel>
  51 + </source>
  52 + <source name="CTABackgroundModel" type="CTAIrfBackground" instrument="CTA">
  53 + <spectrum type="PowerLaw">
  54 + <parameter name="Prefactor" value="0.993018" error="0.0160113" scale="1" min="0.001" max="1000" free="1" />
  55 + <parameter name="Index" value="0.00269761" error="0.00973921" scale="1" min="-5" max="5" free="1" />
  56 + <parameter name="Scale" value="1" scale="1e+06" min="0.01" max="1000" free="0" />
  57 + </spectrum>
  58 + </source>
  59 + </source_library>
  60 +
  61 +In this example, the ``Prefactor`` and ``Index`` of the spectral model for the
  62 +Crab as well as the ``Prefactor`` and ``Index`` of the background spectral
  63 +model have been fitted (all parameters having the attribute ``free="1"`` are
  64 +fitted). Now we see also the effect of having multiplied the background
  65 +model with a power law. In that way, the amplitude of the background as
  66 +well as it's spectral slope is adjusted by the fit. Obviously, in this
  67 +example the adjustment compensates only for the statistical fluctuations
  68 +of the background, but with real data, the adjustment may account also for
  69 +some of the systematic uncertainties.
  70 +
  71 +.. warning::
  72 +
  73 + As good practice, the amplitude of the background model should always be
  74 + left as a free parameter of the fit. Otherwise, any uncertainty in the
  75 + background rate will immediately propagate into the flux estimate of the
  76 + source.
  77 +
  78 +To get more details about the model fitting you can inspect the log file.
  79 +Below the last lines of the ctlike.log log file that has been produced by
  80 +this run:
  81 +
  82 +.. code-block:: xml
  83 +
  84 + 2015-12-07T20:55:32: +=================================+
  85 + 2015-12-07T20:55:32: | Maximum likelihood optimisation |
  86 + 2015-12-07T20:55:32: +=================================+
  87 + 2015-12-07T20:55:33: >Iteration 0: -logL=54877.412, Lambda=1.0e-03
  88 + 2015-12-07T20:55:35: >Iteration 1: -logL=54875.025, Lambda=1.0e-03, delta=2.387, max(|grad|)=1.856683 [Index:7]
  89 + 2015-12-07T20:55:36: >Iteration 2: -logL=54875.024, Lambda=1.0e-04, delta=0.001, max(|grad|)=-0.024661 [Index:3]
  90 + 2015-12-07T20:55:36:
  91 + ...
  92 + 2015-12-07T20:55:38: +=========================================+
  93 + 2015-12-07T20:55:38: | Maximum likelihood optimisation results |
  94 + 2015-12-07T20:55:38: +=========================================+
  95 + 2015-12-07T20:55:38: === GOptimizerLM ===
  96 + 2015-12-07T20:55:38: Optimized function value ..: 54875.024
  97 + 2015-12-07T20:55:38: Absolute precision ........: 0.005
  98 + 2015-12-07T20:55:38: Acceptable value decrease .: 2
  99 + 2015-12-07T20:55:38: Optimization status .......: converged
  100 + 2015-12-07T20:55:38: Number of parameters ......: 10
  101 + 2015-12-07T20:55:38: Number of free parameters .: 4
  102 + 2015-12-07T20:55:38: Number of iterations ......: 2
  103 + 2015-12-07T20:55:38: Lambda ....................: 1e-05
  104 + 2015-12-07T20:55:38: Maximum log likelihood ....: -54875.024
  105 + 2015-12-07T20:55:38: Observed events (Nobs) ...: 18195.000
  106 + 2015-12-07T20:55:38: Predicted events (Npred) ..: 18194.999 (Nobs - Npred = 0.00146383)
  107 + 2015-12-07T20:55:38: === GModels ===
  108 + 2015-12-07T20:55:38: Number of models ..........: 2
  109 + 2015-12-07T20:55:38: Number of parameters ......: 10
  110 + 2015-12-07T20:55:38: === GModelSky ===
  111 + 2015-12-07T20:55:38: Name ......................: Crab
  112 + 2015-12-07T20:55:38: Instruments ...............: all
  113 + 2015-12-07T20:55:38: Instrument scale factors ..: unity
  114 + 2015-12-07T20:55:38: Observation identifiers ...: all
  115 + 2015-12-07T20:55:38: Model type ................: PointSource
  116 + 2015-12-07T20:55:38: Model components ..........: "SkyDirFunction" * "PowerLaw" * "Constant"
  117 + 2015-12-07T20:55:38: Number of parameters ......: 6
  118 + 2015-12-07T20:55:38: Number of spatial par's ...: 2
  119 + 2015-12-07T20:55:38: RA .......................: 83.6331 [-360,360] deg (fixed,scale=1)
  120 + 2015-12-07T20:55:38: DEC ......................: 22.0145 [-90,90] deg (fixed,scale=1)
  121 + 2015-12-07T20:55:38: Number of spectral par's ..: 3
  122 + 2015-12-07T20:55:38: Prefactor ................: 5.78443e-16 +/- 1.01348e-17 [1e-23,1e-13] ph/cm2/s/MeV (free,scale=1e-16,gradient)
  123 + 2015-12-07T20:55:38: Index ....................: -2.50664 +/- 0.0153631 [-0,-5] (free,scale=-1,gradient)
  124 + 2015-12-07T20:55:38: PivotEnergy ..............: 300000 [10000,1e+09] MeV (fixed,scale=1e+06,gradient)
  125 + 2015-12-07T20:55:38: Number of temporal par's ..: 1
  126 + 2015-12-07T20:55:38: Normalization ............: 1 (relative value) (fixed,scale=1,gradient)
  127 + 2015-12-07T20:55:38: === GCTAModelIrfBackground ===
  128 + 2015-12-07T20:55:38: Name ......................: CTABackgroundModel
  129 + 2015-12-07T20:55:38: Instruments ...............: CTA
  130 + 2015-12-07T20:55:38: Instrument scale factors ..: unity
  131 + 2015-12-07T20:55:38: Observation identifiers ...: all
  132 + 2015-12-07T20:55:38: Model type ................: "PowerLaw" * "Constant"
  133 + 2015-12-07T20:55:38: Number of parameters ......: 4
  134 + 2015-12-07T20:55:38: Number of spectral par's ..: 3
  135 + 2015-12-07T20:55:38: Prefactor ................: 0.993018 +/- 0.0160113 [0.001,1000] ph/cm2/s/MeV (free,scale=1,gradient)
  136 + 2015-12-07T20:55:38: Index ....................: 0.00269761 +/- 0.00973921 [-5,5] (free,scale=1,gradient)
  137 + 2015-12-07T20:55:38: PivotEnergy ..............: 1e+06 [10000,1e+09] MeV (fixed,scale=1e+06,gradient)
  138 + 2015-12-07T20:55:38: Number of temporal par's ..: 1
  139 + 2015-12-07T20:55:38: Normalization ............: 1 (relative value) (fixed,scale=1,gradient)
  140 +
  141 +The maximum likelihood optimizer required 2 iterations to converge. This
  142 +is pretty fast, but recall that we used the same model file for the simulation
  143 +and for fitting, hence the initial parameter values were already very close
  144 +to the best fitting values. To see the impact of the initial parameters on
  145 +the fit result, you may re-run :ref:`ctlike` using another copy of the model
  146 +XML file where you change the value attributes of the parameters that should be
  147 +fitted. You will see that the optimizer requires a couple of more iterations,
  148 +but it should converge to the same solution (provided that the initial values
  149 +are not too far from the best fitting values).
  150 +
  151 +.. note::
  152 +
  153 + As sanity check you should verify that the predicted number of events
  154 + (Npred) is equal to the observed number of events (Nobs). To facilitate
  155 + this comparison, :ref:`ctlike` provides the difference Nobs - Npred in
  156 + the log file. In real life situations, this difference may not always be
  157 + small, in particular if the source model is too constrained. You may
  158 + then free some of the model parameters so that the fit can correctly
  159 + describe the data.
  160 +
  161 +.. note::
  162 +
  163 + The :ref:`ctlike` tool has the ability to estimate the detection
  164 + significance for sources in the XML model. This is done by computing
  165 + the Test Statistic value which is defined as twice the log-likelihood
  166 + difference between fitting a source at a given position on top of a
  167 + (background) model or fitting no source. Roughly speaken, the square
  168 + root of the Test Statistic value gives the source detection significance
  169 + in Gaussian sigmas, although the exact relation depends somewhat on
  170 + the formulation of the statistical problem.
  171 +
  172 + To instruct :ref:`ctlike` to compute the Test Statistic value for a
  173 + given source you need to add the attribute ``tscalc="1"`` to the XML
  174 + file:
  175 +
  176 + .. code-block:: xml
  177 +
  178 + <source name="Crab" type="PointSource" tscalc="1">
  179 +
  180 + :ref:`ctlike` will then compute the Test Statistic value for that
  181 + source and dump the result in the log file:
  182 +
  183 + .. code-block:: xml
  184 +
  185 + 2015-12-07T20:58:45: === GModelSky ===
  186 + 2015-12-07T20:58:45: Name ......................: Crab
  187 + 2015-12-07T20:58:45: Instruments ...............: all
  188 + 2015-12-07T20:58:45: Test Statistic ............: 21164.4
  189 +
  190 + The Test Statistic value will also be added as new attribute
  191 + ``ts`` to the XML result file:
  192 +
  193 + .. code-block:: xml
  194 +
  195 + <source name="Crab" type="PointSource" ts="21164.384" tscalc="1">
... ...
doc/source/user_manual/getting_started/quickstart.rst
  View file @c1b6ac1
1 1 .. _quickstart:
2 2  
3   -A quick ctools tutorial
4   ------------------------
5   -
6 3 First steps with ctools
7   -~~~~~~~~~~~~~~~~~~~~~~~
8   -
9   -This section provides a step-by-step description of the CTA data analysis
10   -procedure implemented in ctools. In this example we will simulate data for
11   -the Crab nebula, observed on-axis, as a single source in the CTA field of
12   -view.
13   -
14   -The example consists of the following analysis steps:
15   -
16   -- :ref:`sec_simulating_cta`
17   -
18   -- :ref:`sec_binning_cta`
19   -
20   -- :ref:`sec_fitting_cta`
21   -
22   -- :ref:`sec_unbinned_cta`
23   -
24   -- :ref:`sec_butterfly_cta`
25   -
26   -
27   -.. _sec_simulating_cta:
28   -
29   -Simulating CTA data
30   -~~~~~~~~~~~~~~~~~~~
31   -
32   -CTA data are simulated using the :ref:`ctobssim` tool. To invoke the tool,
33   -type :ref:`ctobssim` at the console prompt (which is denoted by ``$``).
34   -:ref:`ctobssim` will query for a number of parameters:
35   -
36   -.. code-block:: bash
37   -
38   - $ ctobssim
39   - RA of pointing (degrees) (0-360) [83.63]
40   - Dec of pointing (degrees) (-90-90) [22.01]
41   - Radius of FOV (degrees) (0-180) [5.0]
42   - Start time (MET in s) [0.0]
43   - End time (MET in s) [1800.0]
44   - Lower energy limit (TeV) [0.1]
45   - Upper energy limit (TeV) [100.0]
46   - Calibration database [prod2]
47   - Instrument response function [South_50h]
48   - Model [$CTOOLS/share/models/crab.xml]
49   - Output event data file or observation definition file [events.fits]
50   -
51   -Each line represents a query for one parameter value.
52   -The line starts with a short description of the parameter, followed by
53   -the default value proposed by ctobssim in squared brackets ``[ ]``.
54   -**If no parameter is entered the default value will be used**
55   -(which is the case for all parameters shown here).
56   -Otherwise, the specified value will overwrite the default value.
57   -The round brackets ``( )`` indicate the range of possible parameter
58   -values (if applicable).
59   -
60   -
61   -You may have recognised that the environment variable ``$CTOOLS`` has
62   -been used in the path name of the model. ctools will automatically expand
63   -the environment variables in parameter inputs.
64   -
65   -The CTA instrument properties (effective area, PSF width) are taken from
66   -the prod2 database. The response for the southern array using the cuts
67   -optimised for 50 hours of observing time are used.
68   -
69   -.. note::
70   -
71   - ctools comes bundled with CTA response functions for the northern and
72   - the southern array. The response functions are based on a Prod2
73   - analysis with cuts optimised for 0.5 hours, 5 hours and 50 hours of
74   - observing time. The following Instrument Response Functions
75   - (IRFs) are available: ``North_0.5h``, ``North_5h``, ``North_50h``,
76   - ``South_0.5h``, ``South_5h``, and ``South_50h``.
77   -
78   -Events are simulated based on the instrument properties and based on a
79   -source and background model. Only events that fall within the specified
80   -region of interest (ROI), defined as a circle around a sky position in
81   -Right Ascension and Declination (in degrees), will be stored in the output
82   -event data file. The duration of the simulation is taken here to 30 minutes
83   -(or 1800 seconds). Events are simulated for energies between 0.1 and 100 TeV.
84   -
85   -The source and background model is defined by the XML file
86   -``$CTOOLS/share/models/crab.xml``:
87   -
88   -.. code-block:: xml
89   -
90   - <?xml version="1.0" standalone="no"?>
91   - <source_library title="source library">
92   - <source name="Crab" type="PointSource">
93   - <spectrum type="PowerLaw">
94   - <parameter name="Prefactor" scale="1e-16" value="5.7" min="1e-07" max="1000.0" free="1"/>
95   - <parameter name="Index" scale="-1" value="2.48" min="0.0" max="+5.0" free="1"/>
96   - <parameter name="Scale" scale="1e6" value="0.3" min="0.01" max="1000.0" free="0"/>
97   - </spectrum>
98   - <spatialModel type="SkyDirFunction">
99   - <parameter name="RA" scale="1.0" value="83.6331" min="-360" max="360" free="0"/>
100   - <parameter name="DEC" scale="1.0" value="22.0145" min="-90" max="90" free="0"/>
101   - </spatialModel>
102   - </source>
103   - <source name="CTABackgroundModel" type="CTAIrfBackground" instrument="CTA">
104   - <spectrum type="PowerLaw">
105   - <parameter name="Prefactor" scale="1.0" value="1.0" min="1e-3" max="1e+3" free="1"/>
106   - <parameter name="Index" scale="1.0" value="0.0" min="-5.0" max="+5.0" free="1"/>
107   - <parameter name="Scale" scale="1e6" value="1.0" min="0.01" max="1000.0" free="0"/>
108   - </spectrum>
109   - </source>
110   - </source_library>
111   -
112   -The model consists of a source library that contains two components:
113   -the Crab nebula and an instrumental background model.
114   -
115   -The Crab nebula is modelled by a factorized sky model that has a spectral
116   -and a spatial component (tags ``<spectrum>`` and ``<spatialModel>``,
117   -respectively). The spectrum is modelled by a power law, which is defined by
118   -three parameters: the ``Prefactor``, the ``Index`` and the ``Scale``.
119   -The spatial model has two parameters: Right Ascension in degrees (``RA``), and
120   -Declination in degrees (``DEC``). Each parameter has a value and a scale factor,
121   -the real value of the parameter being the product ``value * scale``. Typically,
122   -``scale`` is chosen so that ``value`` is of the order of 1 (this is relevant for
123   -model fitting). In addition, ``value`` is bound by a minimum (``min``) and
124   -maximum (``max``) value, and a parameter may be free (``free="1"``) or fixed
125   -(``free="0"``). The ``min``, ``max``, and ``free`` attributes are not
126   -relevant here for the simulations, but they will be important for the model
127   -fitting later.
128   -
129   -The spectral intensity I(E) (in units of photons/cm2/s/MeV) of the power
130   -law is given by
131   -
132   -.. math::
133   - \frac{dN}{dE} = N_0 \left( \frac{E}{E_0} \right)^{\gamma}
134   -
135   -where the parameters in the XML definition have the following mappings:
136   -
137   -* :math:`N_0` = ``Prefactor``
138   -* :math:`\gamma` = ``Index``
139   -* :math:`E_0` = ``Scale``
140   -
141   -.. warning::
142   -
143   - Energies are given in the XML file in MeV units. This is a GammaLib
144   - convention that can not be modified. **So make sure you always use
145   - MeV as energy unit in an XML file.**
146   -
147   -The instrumental background of CTA is modelled using the background
148   -information provided in the IRF (``CTAIrfBackground``) multipled
149   -by a power law. As it is defined here, the power law represents a
150   -constant of 1, hence the background IRF will be used without any
151   -modification. The power law will become active when fitting the data
152   -later and allows a spectral adjustment of the background model that
153   -may account for uncertainties in the background information provided
154   -in the IRF.
155   -
156   -:ref:`ctobssim` has a couple of hidden parameters, the most important one being
157   -certainly ``seed``. ``seed`` is an integer that specifies the seed value
158   -for the random number generator, and changing this parameter will allow to
159   -generate statistically independent Monte Carlo samples of CTA event data.
160   -To use for example a seed value of 41 you should type:
161   -
162   -.. code-block:: bash
163   -
164   - $ ctobssim seed=41
165   -
166   -:ref:`ctobssim` will write 2 files in the working directory: ``events.fits``
167   -and ``ctobssim.log``. The first file contains the simulated events in FITS
168   -format and can be inspected using ``fv`` or ``ds9``. The FITS file will
169   -contain three extensions: an empty primary image, a binary table named
170   -``EVENTS`` that holds the events (one row per event), and a binary table
171   -named ``GTI`` holding the Good Time Intervals (for the moment a single row
172   -with 2 columns providing the start and the stop time of the simulated time
173   -interval).
174   -
175   -The second file produced by :ref:`ctobssim` is a human readable log file that
176   -contains information about the job execution. As example, the last lines
177   -from this file are shown here:
178   -
179   -.. code-block:: xml
180   -
181   - 2015-05-22T19:24:53: +======================+
182   - 2015-05-22T19:24:53: | Simulate observation |
183   - 2015-05-22T19:24:53: +======================+
184   - 2015-05-22T19:24:53: === Observation ===
185   - 2015-05-22T19:24:53: Simulation area ...........: 1.9635e+11 cm2
186   - 2015-05-22T19:24:53: Simulation cone ...........: RA=83.63 deg, Dec=22.01 deg, r=5.5 deg
187   - 2015-05-22T19:24:53: Time interval .............: 0 - 1800 s
188   - 2015-05-22T19:24:53: Photon energy range .......: 100 GeV - 100 TeV
189   - 2015-05-22T19:24:53: Event energy range ........: 100 GeV - 100 TeV
190   - 2015-05-22T19:24:53: MC source photons .........: 207547 [Crab]
191   - 2015-05-22T19:24:53: MC source events ..........: 2961 [Crab]
192   - 2015-05-22T19:24:53: MC source events ..........: 2961 (all source models)
193   - 2015-05-22T19:24:55: MC background events ......: 13003
194   - 2015-05-22T19:24:55: MC events .................: 15964 (all models)
195   -
196   -Each line starts with the UTC time at which the line has been written. In
197   -this run, 207547 Crab photons have been thrown over an area of 19.6 square
198   -kilometres during a time interval of 1800 seconds. 2961 of these photons have
199   -been registered by CTA as events. In the same time interval, 13003 background
200   -events have been registred by CTA.
201   -
202   -You may change the name of the log file using the hidden parameter
203   -``logfile``:
204   -
205   -.. code-block:: bash
206   -
207   - $ ctobssim logfile=my-private-log-file
208   -
209   -Furthermore, you may decide on the amount of information provided in the
210   -log file (the chattiness of the executable) using the hidden parameter
211   -``chatter``:
212   -
213   -.. code-block:: bash
214   -
215   - $ ctobssim chatter=4
216   -
217   -``chatter`` can vary between 0 and 4, 0 providing no information while 4
218   -provides the most detailed information. **By default, all ctools have a
219   -chatter level of 2.**
220   -
221   -You may also duplicate the log file information into the console by setting
222   -the hidden ``debug`` parameter to yes:
223   -
224   -.. code-block:: bash
225   -
226   - $ ctobssim debug=yes
227   -
228   -
229   -.. _sec_binning_cta:
230   -
231   -Binning CTA data
232   -~~~~~~~~~~~~~~~~
233   -
234   -As next analysis step you will bin the data in a counts cube using
235   -:ref:`ctbin`.
236   -A counts cube is a 3 dimensional data cube, spanned by
237   -Right Ascension (or Galactic longitude), Declination (or Galactic latitude),
238   -and energy (typically logarithmically spaced, but this is under user
239   -control).
240   -
241   -:ref:`ctbin` is executed by typing:
242   -
243   -.. code-block:: bash
244   -
245   - $ ctbin
246   - Event list or observation definition file [events.fits]
247   - First coordinate of image center in degrees (RA or galactic l) (0-360) [83.63]
248   - Second coordinate of image center in degrees (DEC or galactic b) (-90-90) [22.01]
249   - Projection method (AIT|AZP|CAR|MER|MOL|STG|TAN) [CAR]
250   - Coordinate system (CEL - celestial, GAL - galactic) (CEL|GAL) [CEL]
251   - Image scale (in degrees/pixel) [0.02]
252   - Size of the X axis in pixels [200]
253   - Size of the Y axis in pixels [200]
254   - Algorithm for defining energy bins (FILE|LIN|LOG) [LOG]
255   - Start value for first energy bin in TeV [0.1]
256   - Stop value for last energy bin in TeV [100.0]
257   - Number of energy bins [20]
258   - Output counts cube [cntcube.fits]
259   -
260   -The counts cube will be centred on the location of the Crab (Right Ascension
261   -83.63 degrees, Declination 22.01 degrees) and will be aligned in celestial
262   -coordinates. A cartesian projection has been selected. The counts cube has
263   -200 x 200 spatial pixels of 0.02 x 0.02 degrees in size, hence it covers a
264   -total area of 4 x 4 degrees.
265   -
266   -The counts cube will contain 20 maps, which are logarithmically spaced
267   -in energy, and which cover the energy range from 0.1 TeV to 100 TeV. In this
268   -example, the counts cube will be saved as ``cntcube.fits`` in the working
269   -directory. In addition to the counts cube, that is stored as the primary
270   -image extension, the FITS file also contains an extension named ``EBOUNDS``
271   -that defines the energy boundaries that were used, and an extension ``GTI``
272   -that defines the Good Time Intervals that have been used. The following
273   -image shows the resulting FITS file. The ``EBOUNDS`` table has 20 rows, one
274   -for each energy bin, while the ``GTI`` table has just a single row, indicating
275   -the start and stop time of the simulated data.
276   -
277   -.. figure:: cntmap-fits.jpg
278   - :width: 600px
279   - :align: center
280   -
281   - *Counts cube FITS file*
282   -
283   -
284   -An image of the first bin, covering the energy range 100 - 141 GeV, is
285   -shown below:
286   -
287   -.. figure:: cntmap-map.jpg
288   - :height: 400px
289   - :align: center
290   -
291   - *Counts cube for first energy bin*
292   -
293   -
294   -For illustration, the last few lines of the log file ``ctbin.log`` are
295   -reproduced below:
296   -
297   -.. code-block:: xml
298   -
299   - 2015-05-22T19:40:30: +=================+
300   - 2015-05-22T19:40:30: | Bin observation |
301   - 2015-05-22T19:40:30: +=================+
302   - 2015-05-22T19:40:30: === Observation ===
303   - 2015-05-22T19:40:30: Events in list ............: 15964
304   - 2015-05-22T19:40:30: Events in cube ............: 13360
305   - 2015-05-22T19:40:30: Event bins outside RoI ....: 0
306   - 2015-05-22T19:40:30: Events outside cube area ..: 2604
307   - 2015-05-22T19:40:30: Events outside energy bins : 0
308   -
309   -From the 15964 events that have been simulated and stored in the
310   -``events.fits`` file, 13360 lie within the cube boundaries and are thus put
311   -into the resulting counts cube. The counts cube is stored in a cartesian
312   -projection in a World Coordinate System (WCS) compliant format.
313   -
314   -
315   -.. _sec_fitting_cta:
316   -
317   -Fitting CTA data
318   -~~~~~~~~~~~~~~~~
319   -
320   -Now we are ready to fit the simulated data with a model. For simplicity
321   -we use in this example the same model that we used to simulate the data
322   -with :ref:`ctobssim`. Model fitting is done using the :ref:`ctlike` tool,
323   -and we do the fit by typing:
324   -
325   -.. code-block:: bash
326   -
327   - $ ctlike
328   - Event list, counts cube or observation definition file [events.fits] cntcube.fits
329   - Exposure cube file (only needed for stacked analysis) [NONE]
330   - PSF cube file (only needed for stacked analysis) [NONE]
331   - Background cube file (only needed for stacked analysis) [NONE]
332   - Calibration database [prod2]
333   - Instrument response function [South_50h]
334   - Source model [$CTOOLS/share/models/crab.xml]
335   - Source model output file [crab_results.xml]
336   -
337   -The data are fitted in *binned* mode, which means that the events
338   -have been binned into a counts cube and the fit computes the log-likelihood
339   -function by summing over all 200 x 200 x 20 bins of the counts cube. There is
340   -an alternative method, the so called *unbinned* mode, where the events are
341   -not binned into a counts cube and the log-likelihood is computed directly by
342   -summing over all events. We will explore the *unbinned* mode later.
343   -
344   -One of the parameters of :ref:`ctlike` is a source model output file
345   -(we specified ``crab_results.xml`` in the example), and this file will be
346   -a copy of the source model input XML file where the parameter values have
347   -been replaced by the fit results. In addition, the statistical uncertainties
348   -are added for each fitted parameter using the attribute ``error``.
349   -Below we show the XML result file that has been produced by the run:
350   -
351   -.. code-block:: xml
352   -
353   - <?xml version="1.0" encoding="UTF-8" standalone="no"?>
354   - <source_library title="source library">
355   - <source name="Crab" type="PointSource">
356   - <spectrum type="PowerLaw">
357   - <parameter name="Prefactor" value="5.78197" error="0.110889" scale="1e-16" min="1e-07" max="1000" free="1" />
358   - <parameter name="Index" value="2.49174" error="0.0164369" scale="-1" min="0" max="5" free="1" />
359   - <parameter name="Scale" value="0.3" scale="1e+06" min="0.01" max="1000" free="0" />
360   - </spectrum>
361   - <spatialModel type="SkyDirFunction">
362   - <parameter name="RA" value="83.6331" scale="1" min="-360" max="360" free="0" />
363   - <parameter name="DEC" value="22.0145" scale="1" min="-90" max="90" free="0" />
364   - </spatialModel>
365   - </source>
366   - <source name="CTABackgroundModel" type="CTAIrfBackground" instrument="CTA">
367   - <spectrum type="PowerLaw">
368   - <parameter name="Prefactor" value="1.02048" error="0.0280684" scale="1" min="0.001" max="1000" free="1" />
369   - <parameter name="Index" value="0.0197856" error="0.0156686" scale="1" min="-5" max="5" free="1" />
370   - <parameter name="Scale" value="1" scale="1e+06" min="0.01" max="1000" free="0" />
371   - </spectrum>
372   - </source>
373   - </source_library>
374   -
375   -In this example, the ``Prefactor`` and ``Index`` of the spectral model for the
376   -Crab as well as the ``Prefactor`` and ``Index`` of the background spectral
377   -model have been fitted (all parameters having the attribute ``free="1"`` are
378   -fitted). Now we see also the effect of having multiplied the background
379   -model with a power law. In that way, the amplitude of the background as
380   -well as it's spectral slope is adjusted by the fit. Obviously, in this
381   -example the adjustment compensates only for the statistical fluctuations
382   -of the background, but with real data, the adjustment may account also for
383   -some of the systematic uncertainties.
384   -
385   -.. warning::
386   -
387   - As good practice, the amplitude of the background model should always be
388   - left as a free parameter of the fit. Otherwise, any uncertainty in the
389   - background rate will immediately propagate into the flux estimate of the
390   - source.
391   -
392   -To get more details about the model fitting you can inspect the log file.
393   -Below the last lines of the ctlike.log log file that has been produced by
394   -this run:
395   -
396   -.. code-block:: xml
397   -
398   - 2015-05-22T19:45:15: +=================================+
399   - 2015-05-22T19:45:15: | Maximum likelihood optimisation |
400   - 2015-05-22T19:45:15: +=================================+
401   - 2015-05-22T19:45:16: >Iteration 0: -logL=39910.748, Lambda=1.0e-03
402   - 2015-05-22T19:45:18: >Iteration 1: -logL=39908.788, Lambda=1.0e-03, delta=1.960, max(|grad|)=6.701856 [Index:7]
403   - 2015-05-22T19:45:19: >Iteration 2: -logL=39908.787, Lambda=1.0e-04, delta=0.001, max(|grad|)=-0.057041 [Index:3]
404   - 2015-05-22T19:45:21:
405   - 2015-05-22T19:45:21: +=========================================+
406   - 2015-05-22T19:45:21: | Maximum likelihood optimization results |
407   - 2015-05-22T19:45:21: +=========================================+
408   - 2015-05-22T19:45:21: === GOptimizerLM ===
409   - 2015-05-22T19:45:21: Optimized function value ..: 39908.787
410   - 2015-05-22T19:45:21: Absolute precision ........: 0.005
411   - 2015-05-22T19:45:21: Acceptable value decrease .: 2
412   - 2015-05-22T19:45:21: Optimization status .......: converged
413   - 2015-05-22T19:45:21: Number of parameters ......: 10
414   - 2015-05-22T19:45:21: Number of free parameters .: 4
415   - 2015-05-22T19:45:21: Number of iterations ......: 2
416   - 2015-05-22T19:45:21: Lambda ....................: 1e-05
417   - 2015-05-22T19:45:21: Maximum log likelihood ....: -39908.787
418   - 2015-05-22T19:45:21: Observed events (Nobs) ...: 13360.000
419   - 2015-05-22T19:45:21: Predicted events (Npred) ..: 13359.998 (Nobs - Npred = 0.00180799)
420   - 2015-05-22T19:45:21: === GModels ===
421   - 2015-05-22T19:45:21: Number of models ..........: 2
422   - 2015-05-22T19:45:21: Number of parameters ......: 10
423   - 2015-05-22T19:45:21: === GModelSky ===
424   - 2015-05-22T19:45:21: Name ......................: Crab
425   - 2015-05-22T19:45:21: Instruments ...............: all
426   - 2015-05-22T19:45:21: Instrument scale factors ..: unity
427   - 2015-05-22T19:45:21: Observation identifiers ...: all
428   - 2015-05-22T19:45:21: Model type ................: PointSource
429   - 2015-05-22T19:45:21: Model components ..........: "SkyDirFunction" * "PowerLaw" * "Constant"
430   - 2015-05-22T19:45:21: Number of parameters ......: 6
431   - 2015-05-22T19:45:21: Number of spatial par's ...: 2
432   - 2015-05-22T19:45:21: RA .......................: 83.6331 [-360,360] deg (fixed,scale=1)
433   - 2015-05-22T19:45:21: DEC ......................: 22.0145 [-90,90] deg (fixed,scale=1)
434   - 2015-05-22T19:45:21: Number of spectral par's ..: 3
435   - 2015-05-22T19:45:21: Prefactor ................: 5.78197e-16 +/- 1.10889e-17 [1e-23,1e-13] ph/cm2/s/MeV (free,scale=1e-16,gradient)
436   - 2015-05-22T19:45:21: Index ....................: -2.49174 +/- 0.0164369 [-0,-5] (free,scale=-1,gradient)
437   - 2015-05-22T19:45:21: PivotEnergy ..............: 300000 [10000,1e+09] MeV (fixed,scale=1e+06,gradient)
438   - 2015-05-22T19:45:21: Number of temporal par's ..: 1
439   - 2015-05-22T19:45:21: Normalization ............: 1 (relative value) (fixed,scale=1,gradient)
440   - 2015-05-22T19:45:21: === GCTAModelIrfBackground ===
441   - 2015-05-22T19:45:21: Name ......................: CTABackgroundModel
442   - 2015-05-22T19:45:21: Instruments ...............: CTA
443   - 2015-05-22T19:45:21: Instrument scale factors ..: unity
444   - 2015-05-22T19:45:21: Observation identifiers ...: all
445   - 2015-05-22T19:45:21: Model type ................: "PowerLaw" * "Constant"
446   - 2015-05-22T19:45:21: Number of parameters ......: 4
447   - 2015-05-22T19:45:21: Number of spectral par's ..: 3
448   - 2015-05-22T19:45:21: Prefactor ................: 1.02048 +/- 0.0280684 [0.001,1000] ph/cm2/s/MeV (free,scale=1,gradient)
449   - 2015-05-22T19:45:21: Index ....................: 0.0197856 +/- 0.0156686 [-5,5] (free,scale=1,gradient)
450   - 2015-05-22T19:45:21: PivotEnergy ..............: 1e+06 [10000,1e+09] MeV (fixed,scale=1e+06,gradient)
451   - 2015-05-22T19:45:21: Number of temporal par's ..: 1
452   - 2015-05-22T19:45:21: Normalization ............: 1 (relative value) (fixed,scale=1,gradient)
453   -
454   -The maximum likelihood optimizer required 2 iterations to converge. This
455   -is pretty fast, but recall that we used the same model file for the simulation
456   -and for fitting, hence the initial parameter values were already very close
457   -to the best fitting values. To see the impact of the initial parameters on
458   -the fit result, you may re-run :ref:`ctlike` using another copy of the model
459   -XML file where you change the value attributes of the parameters that should be
460   -fitted. You will see that the optimizer requires a couple of more iterations,
461   -but it should converge to the same solution (provided that the initial values
462   -are not too far from the best fitting values).
463   -
464   -.. note::
465   -
466   - As sanity check you should verify that the predicted number of events
467   - (Npred) is equal to the observed number of events (Nobs). To facilitate
468   - this comparison, :ref:`ctlike` provides the difference Nobs - Npred in
469   - the log file. In real life situations, this difference may not always be
470   - small, in particular if the source model is too constrained. You may
471   - then free some of the model parameters so that the fit can correctly
472   - describe the data.
473   -
474   -.. note::
475   -
476   - The :ref:`ctlike` tool has the ability to estimate the detection
477   - significance for sources in the XML model. This is done by computing
478   - the Test Statistic value which is defined as twice the log-likelihood
479   - difference between fitting a source at a given position on top of a
480   - (background) model or fitting no source. Roughly speaken, the square
481   - root of the Test Statistic value gives the source detection significance
482   - in Gaussian sigmas, although the exact relation depends somewhat on
483   - the formulation of the statistical problem.
484   -
485   - To instruct :ref:`ctlike` to compute the Test Statistic value for a
486   - given source you need to add the attribute ``tscalc="1"`` to the XML
487   - file:
488   -
489   - .. code-block:: xml
490   -
491   - <source name="Crab" type="PointSource" tscalc="1">
492   -
493   - :ref:`ctlike` will then compute the Test Statistic value for that
494   - source and dump the result in the log file:
495   -
496   - .. code-block:: xml
497   -
498   - 2015-05-22T19:58:43: === GModelSky ===
499   - 2015-05-22T19:58:43: Name ......................: Crab
500   - 2015-05-22T19:58:43: Instruments ...............: all
501   - 2015-05-22T19:58:43: Test Statistic ............: 18662.6
502   -
503   - The Test Statistic value will also be added as new attribute
504   - ``ts`` to the XML result file:
505   -
506   - .. code-block:: xml
507   -
508   - <source name="Crab" type="PointSource" ts="18662.576" tscalc="1">
509   -
510   -
511   -.. _sec_unbinned_cta:
512   -
513   -Doing an unbinned analysis
514   -~~~~~~~~~~~~~~~~~~~~~~~~~~
515   -
516   -As gamma-ray events are rare, the counts cubes generated by :ref:`ctbin`
517   -will in general be sparsly populated, having many empty pixels, in
518   -particular at high energies.
519   -An alternative analysis technique consists of working directly on the event
520   -list without binning the events in a counts cube. We will see the benefit of
521   -such an analysis later once you re-run :ref:`ctlike` in unbinned mode.
522   -
523   -For unbinned analysis you first have to define the data space region over
524   -which the analysis is done. This is similiar to the :ref:`ctbin` step for
525   -a binned analysis where you defined the size of the counts cube, the energy
526   -range, and the time interval. For unbinned analysis you have no such thing
527   -as a counts cube, but you have to define over which region of the data space
528   -the selected events are spread (because the ctools have to integrate over
529   -this region to compute the total number of predicted events in the data space
530   -that you analyse). Furthermore, you have to define what energy range is
531   -covered, and what time interval is spanned by the data. All this is done
532   -by the :ref:`ctselect` tool, which replaces the :ref:`ctbin` step in an
533   -unbinned analysis.
534   -
535   -:ref:`ctselect` performs an event selection by choosing only events within
536   -a given region-of-interest (ROI), within a given energy band, and within a
537   -given time interval from the input event list. The ROI is a circular region on
538   -the sky, for which you define the centre (in celestial coordinates) and the
539   -radius. Such a circular ROI is sometimes also called an acceptance cone. The
540   -following example shows how to run ctselect:
541   -
542   -.. code-block:: bash
543   -
544   - $ ctselect
545   - Input event list or observation definition file [events.fits]
546   - RA for ROI centre (degrees) (0-360) [83.63]
547   - Dec for ROI centre (degrees) (-90-90) [22.01]
548   - Radius of ROI (degrees) (0-180) [3.0]
549   - Start time (CTA MET in seconds) [0.0]
550   - End time (CTA MET in seconds) [0.0]
551   - Lower energy limit (TeV) [0.1]
552   - Upper energy limit (TeV) [100.0]
553   - Output event list or observation definition file [selected_events.fits]
554   -
555   -:ref:`ctselect` takes the input event list ``events.fits``, performs an
556   -event selection, and writes the selected event into the file
557   -``selected_events.fits``. The parameters it will query for are the centre
558   -of the ROI, the radius of the ROI, the start and stop time (in seconds),
559   -and the energy lower and upper limits (in TeV). The event selection information
560   -is also written as a set of data selection keywords to the output events
561   -file ``selected_events.fits``, by respecting the same syntax that has been
562   -implemented for Fermi/LAT. The following image is a screen dump of the data
563   -selection keywords that have been written to the ``EVENTS`` header in the
564   -file ``selected_events.fits``:
565   -
566   -.. figure:: dskeys.jpg
567   - :width: 400px
568   - :align: center
569   -
570   - *Data selection keywords*
571   -
572   -**It is mandatory for an unbinned analysis that these data selection keywords
573   -exist in the FITS file.**
574   -If they don't exist, :ref:`ctlike` will not execute in unbinned mode.
575   -
576   -Below some lines of the ``ctselect.log`` file that show the data selection
577   -part:
578   -
579   -.. code-block:: xml
580   -
581   - 2015-05-22T20:01:46: +=================+
582   - 2015-05-22T20:01:46: | Event selection |
583   - 2015-05-22T20:01:46: +=================+
584   - 2015-05-22T20:01:46: === Observation ===
585   - 2015-05-22T20:01:47: Selected energy range .....: 0.1 - 100 TeV
586   - 2015-05-22T20:01:47: Requested ROI .............: Centre(RA,DEC)=(83.63, 22.01) deg, Radius=3 deg
587   - 2015-05-22T20:01:47: ROI of data ...............: Centre(RA,DEC)=(83.63, 22.01) deg, Radius=5 deg
588   - 2015-05-22T20:01:47: Selected ROI ..............: Centre(RA,DEC)=(83.63, 22.01) deg, Radius=3 deg
589   - 2015-05-22T20:01:47: cfitsio selection .........: ENERGY >= 0.10000000 && ENERGY <= 100.00000000 && ANGSEP(83.630000,22.010000,RA,DEC) <= 3.000000
590   - 2015-05-22T20:01:47: FITS filename .............: /var/tmp/tmp.0.rRgLpO[EVENTS][ENERGY >= 0.10000000 && ENERGY <= 100.00000000 && ANGSEP(83.630000,22.010000,RA,DEC) <= 3.000000]
591   -
592   -.. note::
593   -
594   - :ref:`ctobssim` will also write data selection keywords in the event
595   - list FITS file, hence you can run :ref:`ctlike` directly on a FITS file
596   - produced by :ref:`ctobssim`. Any selection performed by :ref:`ctselect`
597   - needs to be fully enclosed within any previous selection, e.g. the ROI
598   - needs to be fully enclosed in the acceptance cone used for event
599   - simulation, the energy selection must be fully comprised in the
600   - range of simulated energies, the same applies for the temporal selection.
601   - :ref:`ctselect` will automatically adjust
602   - the selection parameters to guarantee full enclosure. To keep track of
603   - this adjustment, the :ref:`ctselect` log file quotes the requested
604   - selection, any existing selections, and the selection that was finally
605   - applied.
606   -
607   -.. warning::
608   -
609   - :ref:`ctselect` may of course also be used for event selection prior to
610   - binned analysis, for example to select events for a given period in
611   - time. **If you use** :ref:`ctselect` **however to make a spatial or energy
612   - selection, make sure that the counts cube is fully enclosed in the
613   - selection intervals.** Otherwise you will get empty zones in the counts
614   - cube of which the ctools are not aware of, and the subsequent analysis
615   - results will be wrong.
616   -
617   -Now that you have selected the events of interest, you can run ctlike in
618   -unbinned mode. To do this you have to specify the selected event list
619   -instead of the counts cube:
620   -
621   -.. code-block:: bash
622   -
623   - $ ctlike
624   - Event list, counts cube or observation definition file [cntcube.fits] selected_events.fits
625   - Calibration database [prod2]
626   - Instrument response function [South_50h]
627   - Source model [$CTOOLS/share/models/crab.xml]
628   - Source model output file [crab_results.xml]
629   -
630   -You will recognise that :ref:`ctlike` runs much faster in unbinned mode
631   -compared to binned mode.
632   -This is understandable as the selected event list contains
633   -only 15312 events, while the binned counts cube we used before had
634   -200 x 200 x 20 = 800000 pixels. As unbinned maximum likelihood fitting loops
635   -over the events (while binned maximum likelihood loops over the pixels),
636   -there are much less operations to perform in unbinned than in binned mode
637   -(there is some additional overhead in unbinned mode that comes from
638   -integrating the models over the region of interest, yet this is negligible
639   -compared to the operations needed when looping over all pixels). So as long
640   -as you work with small event lists, unbinned mode is faster (this
641   -typically holds up to 100 hours of observing time).
642   -Unbinned :ref:`ctlike` should also be more precise as no binning is performed,
643   -hence there is no loss of information due to histogramming.
644   -
645   -Below you see the corresponding output from the ctlike.log file. The fitted
646   -parameters are essentially identical to the ones found in binned mode.
647   -The slight difference with respect to the binned analysis may be explained
648   -by the different event sample that has been used for the analysis: while
649   -binned likelihood works on rectangular counts cubes, unbinned likelihood works
650   -on circular event selection regions. It is thus not possible to select exactly
651   -the same events for both analyses.
652   -
653   -.. code-block:: xml
654   -
655   - 2015-05-22T20:05:54: +=================================+
656   - 2015-05-22T20:05:54: | Maximum likelihood optimisation |
657   - 2015-05-22T20:05:54: +=================================+
658   - 2015-05-22T20:05:54: >Iteration 0: -logL=93854.543, Lambda=1.0e-03
659   - 2015-05-22T20:05:54: >Iteration 1: -logL=93848.595, Lambda=1.0e-03, delta=5.948, max(|grad|)=22.480581 [Index:7]
660   - 2015-05-22T20:05:54: >Iteration 2: -logL=93848.587, Lambda=1.0e-04, delta=0.008, max(|grad|)=-0.081846 [Index:3]
661   - 2015-05-22T20:05:54: >Iteration 3: -logL=93848.587, Lambda=1.0e-05, delta=0.000, max(|grad|)=-0.003485 [Index:3]
662   - 2015-05-22T20:05:54:
663   - 2015-05-22T20:05:54: +=========================================+
664   - 2015-05-22T20:05:54: | Maximum likelihood optimization results |
665   - 2015-05-22T20:05:54: +=========================================+
666   - 2015-05-22T20:05:54: === GOptimizerLM ===
667   - 2015-05-22T20:05:54: Optimized function value ..: 93848.587
668   - 2015-05-22T20:05:54: Absolute precision ........: 0.005
669   - 2015-05-22T20:05:54: Acceptable value decrease .: 2
670   - 2015-05-22T20:05:54: Optimization status .......: converged
671   - 2015-05-22T20:05:54: Number of parameters ......: 10
672   - 2015-05-22T20:05:54: Number of free parameters .: 4
673   - 2015-05-22T20:05:54: Number of iterations ......: 3
674   - 2015-05-22T20:05:54: Lambda ....................: 1e-06
675   - 2015-05-22T20:05:54: Maximum log likelihood ....: -93848.587
676   - 2015-05-22T20:05:54: Observed events (Nobs) ...: 15312.000
677   - 2015-05-22T20:05:54: Predicted events (Npred) ..: 15312.000 (Nobs - Npred = 3.03823e-06)
678   - 2015-05-22T20:05:54: === GModels ===
679   - 2015-05-22T20:05:54: Number of models ..........: 2
680   - 2015-05-22T20:05:54: Number of parameters ......: 10
681   - 2015-05-22T20:05:54: === GModelSky ===
682   - 2015-05-22T20:05:54: Name ......................: Crab
683   - 2015-05-22T20:05:54: Instruments ...............: all
684   - 2015-05-22T20:05:54: Instrument scale factors ..: unity
685   - 2015-05-22T20:05:54: Observation identifiers ...: all
686   - 2015-05-22T20:05:54: Model type ................: PointSource
687   - 2015-05-22T20:05:54: Model components ..........: "SkyDirFunction" * "PowerLaw" * "Constant"
688   - 2015-05-22T20:05:54: Number of parameters ......: 6
689   - 2015-05-22T20:05:54: Number of spatial par's ...: 2
690   - 2015-05-22T20:05:54: RA .......................: 83.6331 [-360,360] deg (fixed,scale=1)
691   - 2015-05-22T20:05:54: DEC ......................: 22.0145 [-90,90] deg (fixed,scale=1)
692   - 2015-05-22T20:05:54: Number of spectral par's ..: 3
693   - 2015-05-22T20:05:54: Prefactor ................: 5.80619e-16 +/- 1.11149e-17 [1e-23,1e-13] ph/cm2/s/MeV (free,scale=1e-16,gradient)
694   - 2015-05-22T20:05:54: Index ....................: -2.49282 +/- 0.0163467 [-0,-5] (free,scale=-1,gradient)
695   - 2015-05-22T20:05:54: PivotEnergy ..............: 300000 [10000,1e+09] MeV (fixed,scale=1e+06,gradient)
696   - 2015-05-22T20:05:54: Number of temporal par's ..: 1
697   - 2015-05-22T20:05:54: Normalization ............: 1 (relative value) (fixed,scale=1,gradient)
698   - 2015-05-22T20:05:54: === GCTAModelIrfBackground ===
699   - 2015-05-22T20:05:54: Name ......................: CTABackgroundModel
700   - 2015-05-22T20:05:54: Instruments ...............: CTA
701   - 2015-05-22T20:05:54: Instrument scale factors ..: unity
702   - 2015-05-22T20:05:54: Observation identifiers ...: all
703   - 2015-05-22T20:05:54: Model type ................: "PowerLaw" * "Constant"
704   - 2015-05-22T20:05:54: Number of parameters ......: 4
705   - 2015-05-22T20:05:54: Number of spectral par's ..: 3
706   - 2015-05-22T20:05:54: Prefactor ................: 1.03511 +/- 0.024311 [0.001,1000] ph/cm2/s/MeV (free,scale=1,gradient)
707   - 2015-05-22T20:05:54: Index ....................: 0.0333176 +/- 0.0134386 [-5,5] (free,scale=1,gradient)
708   - 2015-05-22T20:05:54: PivotEnergy ..............: 1e+06 [10000,1e+09] MeV (fixed,scale=1e+06,gradient)
709   - 2015-05-22T20:05:54: Number of temporal par's ..: 1
710   - 2015-05-22T20:05:54: Normalization ............: 1 (relative value) (fixed,scale=1,gradient)
711   -
712   -
713   -.. _sec_butterfly_cta:
714   -
715   -Calculating and visualising a butterfly
716   -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
717   -
718   -To visualise the analysis results retrieved above, one can calculate the
719   -confidence band of the spectral fit.
720   -The :ref:`ctbutterfly` tool takes the optimised source model as input.
721   -It takes the covariance matrix from the fit to conduct a
722   -Gaussian error propagation for each energy value. It will write the
723   -butterfly information into an ASCII file.
724   -The following example shows how to compute such a butterfly from the command
725   -line.
726   -
727   -.. code-block:: bash
728   -
729   - $ ctbutterfly
730   - Input event list, counts cube or observation definition file [events.fits]
731   - Calibration database [prod2]
732   - Instrument response function [South_50h]
733   - Source model [$CTOOLS/share/models/crab.xml]
734   - Source of interest [Crab]
735   - Start value for first energy bin in TeV [0.1]
736   - Stop value for last energy bin in TeV [100.0]
737   - Output ascii file [butterfly.txt]
738   -
739   -Now that you have computed the confidence band of the spectral fit and
740   -that you will have an ASCII file named ``butterfly.txt`` on disk you can
741   -visualise the butterfly using the script ``show_butterfly.py`` that is
742   -in the ctools ``example`` folder. You will need matplotlib on your system
743   -to make this work. To launch the script, type:
744   -
745   -.. code-block:: bash
746   -
747   - python $CTOOLS/share/examples/python/show_butterfly.py butterfly.txt
748   -
749   -This will result in a canvas which should look like the following:
750   -
751   -.. figure:: butterfly.jpg
752   - :height: 400px
753   - :align: center
  4 +-----------------------
754 5  
755   - *Confidence band of the fit*
756   -
757 6 \ No newline at end of file
  7 +This section provides a step-by-step description of a simple CTA data
  8 +analysis example using the ctools. In this example we will simulate a
  9 +half an hour long CTA observation of the Crab nebula as the single
  10 +point source within the CTA field of view. You will learn how to bin the
  11 +event data into a counts cube and how to fit a spatial and spectral model
  12 +to the data. You will also learn how to analyse directly event lists
  13 +without binning the events into a counts cube. Finally we will show how
  14 +you can create a butterfly diagram that shows the confidence band of the
  15 +fitted spectral model.
  16 +
  17 +.. toctree::
  18 + :maxdepth: 2
  19 +
  20 + simulating
  21 + binning
  22 + fitting
  23 + unbinned
  24 + butterfly
... ...
doc/source/user_manual/getting_started/resmap-crab.png
View file @c1b6ac1

251 KB | W: | H:

314 KB | W: | H:

  • 2-up
  • Swipe
  • Onion skin
doc/source/user_manual/getting_started/response.rst
  View file @c1b6ac1
... ... @@ -99,7 +99,7 @@ Specifying the response function as input parameters
99 99 ctools that require instrument response functions have two parameters
100 100 to specify the calibration database name and the response function name.
101 101 The following example shows a ``ctobssim`` run using the ``prod2``
102   -calibration database and the ``South_50h`` response function:
  102 +calibration database and the ``South_0.5h`` response function:
103 103  
104 104 .. code-block:: bash
105 105  
... ... @@ -112,8 +112,9 @@ calibration database and the ``South_50h`` response function:
112 112 Lower energy limit (TeV) [0.1]
113 113 Upper energy limit (TeV) [100.0]
114 114 Calibration database [prod2]
115   - Instrument response function [South_50h]
116   - Model [$CTOOLS/share/models/crab.xml]
  115 + Instrument response function [South_0.5h]
  116 + Input model XML file [$CTOOLS/share/models/crab.xml]
  117 + Output event data file or observation definition XML file [events.fits]
117 118  
118 119 Running the other tools is equivalent.
119 120  
... ... @@ -131,7 +132,7 @@ definition file:
131 132 <observation_list title="observation library">
132 133 <observation name="Crab" id="00001" instrument="CTA">
133 134 <parameter name="EventList" file="events.fits"/>
134   - <parameter name="Calibration" database="prod2" response="South_50h"/>
  135 + <parameter name="Calibration" database="prod2" response="South_0.5h"/>
135 136 </observation>
136 137 </observation_list>
137 138  
... ... @@ -141,9 +142,9 @@ response name. You can then pass this file directly to, e.g., ``ctlike``:
141 142 .. code-block:: bash
142 143  
143 144 $ ctlike
144   - Event list, counts cube or observation definition file [events.fits] obs_irf.xml
145   - Source model [$CTOOLS/share/models/crab.xml]
146   - Source model output file [crab_results.xml]
  145 + Input event list, counts cube or observation definition XML file [events.fits] obs_irf.xml
  146 + Input model XML file [$CTOOLS/share/models/crab.xml]
  147 + Output model XML file [crab_results.xml]
147 148  
148 149 Note that ``ctlike`` does not ask for the calibration database and
149 150 response name as it found the relevant information in the XML file.
... ... @@ -181,11 +182,11 @@ and response name from within Python:
181 182 import gammalib
182 183 obs = gammalib.GCTAObservation()
183 184 caldb = gammalib.GCaldb("cta", "prod2")
184   - irf = "South_50h"
  185 + irf = "South_0.5h"
185 186 obs.response(irf, caldb)
186 187  
187 188 The calibration database is set by creating a ``GCaldb`` object. The
188 189 constructor takes as argument the mission (always ``cta``) and the
189 190 database name, in our case ``prod2``. The response function is then set
190   -by passing the response name (here ``South_50h``) and the calibration
  191 +by passing the response name (here ``South_0.5h``) and the calibration
191 192 database object to the ``response`` method.
... ...
doc/source/user_manual/getting_started/simulating.rst 0 → 100644
  View file @c1b6ac1
  1 +.. _sec_simulating_cta:
  2 +
  3 +Simulating CTA data
  4 +~~~~~~~~~~~~~~~~~~~
  5 +
  6 +You can simulate a CTA observation with the :ref:`ctobssim` tool.
  7 +
  8 +To invoke the tool, type :ref:`ctobssim` at the console prompt
  9 +(which is denoted by ``$``).
  10 +:ref:`ctobssim` will query for a number of parameters:
  11 +
  12 +.. code-block:: bash
  13 +
  14 + $ ctobssim
  15 + RA of pointing (degrees) (0-360) [83.63]
  16 + Dec of pointing (degrees) (-90-90) [22.01]
  17 + Radius of FOV (degrees) (0-180) [5.0]
  18 + Start time (MET in s) [0.0]
  19 + End time (MET in s) [1800.0]
  20 + Lower energy limit (TeV) [0.1]
  21 + Upper energy limit (TeV) [100.0]
  22 + Calibration database [prod2]
  23 + Instrument response function [South_0.5h]
  24 + Input model XML file [$CTOOLS/share/models/crab.xml]
  25 + Output event data file or observation definition XML file [events.fits]
  26 +
  27 +Each line represents a query for one parameter value.
  28 +The line starts with a short description of the parameter, followed by
  29 +the default value proposed by ctobssim in squared brackets ``[ ]``.
  30 +
  31 +**If no parameter is entered the default value will be used**
  32 +(which is the case for all parameters shown here).
  33 +Otherwise, the specified value will overwrite the default value.
  34 +The round brackets ``( )`` indicate the range of possible parameter
  35 +values (if applicable).
  36 +
  37 +
  38 +You may have recognised that the environment variable ``$CTOOLS`` has
  39 +been used in the path name of the model. ctools will automatically expand
  40 +the environment variables in parameter inputs.
  41 +
  42 +The CTA instrument properties (effective area, PSF width) are taken from
  43 +the prod2 database. The response for the southern array using the cuts
  44 +optimised for 50 hours of observing time are used.
  45 +
  46 +.. note::
  47 +
  48 + ctools comes bundled with CTA response functions for the northern and
  49 + the southern array. The response functions are based on a Prod2
  50 + analysis with cuts optimised for 0.5 hours, 5 hours and 50 hours of
  51 + observing time. The following Instrument Response Functions
  52 + (IRFs) are available: ``North_0.5h``, ``North_5h``, ``North_50h``,
  53 + ``South_0.5h``, ``South_5h``, and ``South_50h``.
  54 +
  55 +Events are simulated based on the instrument properties and based on a
  56 +source and background model. Only events that fall within the specified
  57 +region of interest (ROI), defined as a circle around a sky position in
  58 +Right Ascension and Declination (in degrees), will be stored in the output
  59 +event data file. The duration of the simulation is taken here to 30 minutes
  60 +(or 1800 seconds). Events are simulated for energies between 0.1 and 100 TeV.
  61 +
  62 +The source and background model is defined by the XML file
  63 +``$CTOOLS/share/models/crab.xml``:
  64 +
  65 +.. code-block:: xml
  66 +
  67 + <?xml version="1.0" standalone="no"?>
  68 + <source_library title="source library">
  69 + <source name="Crab" type="PointSource">
  70 + <spectrum type="PowerLaw">
  71 + <parameter name="Prefactor" scale="1e-16" value="5.7" min="1e-07" max="1000.0" free="1"/>
  72 + <parameter name="Index" scale="-1" value="2.48" min="0.0" max="+5.0" free="1"/>
  73 + <parameter name="Scale" scale="1e6" value="0.3" min="0.01" max="1000.0" free="0"/>
  74 + </spectrum>
  75 + <spatialModel type="SkyDirFunction">
  76 + <parameter name="RA" scale="1.0" value="83.6331" min="-360" max="360" free="0"/>
  77 + <parameter name="DEC" scale="1.0" value="22.0145" min="-90" max="90" free="0"/>
  78 + </spatialModel>
  79 + </source>
  80 + <source name="CTABackgroundModel" type="CTAIrfBackground" instrument="CTA">
  81 + <spectrum type="PowerLaw">
  82 + <parameter name="Prefactor" scale="1.0" value="1.0" min="1e-3" max="1e+3" free="1"/>
  83 + <parameter name="Index" scale="1.0" value="0.0" min="-5.0" max="+5.0" free="1"/>
  84 + <parameter name="Scale" scale="1e6" value="1.0" min="0.01" max="1000.0" free="0"/>
  85 + </spectrum>
  86 + </source>
  87 + </source_library>
  88 +
  89 +The model consists of a source library that contains two components:
  90 +the Crab nebula and an instrumental background model.
  91 +
  92 +The Crab nebula is modelled by a factorized sky model that has a spectral
  93 +and a spatial component (tags ``<spectrum>`` and ``<spatialModel>``,
  94 +respectively). The spectrum is modelled by a power law, which is defined by
  95 +three parameters: the ``Prefactor``, the ``Index`` and the ``Scale``.
  96 +The spatial model has two parameters: Right Ascension in degrees (``RA``), and
  97 +Declination in degrees (``DEC``). Each parameter has a value and a scale factor,
  98 +the real value of the parameter being the product ``value * scale``. Typically,
  99 +``scale`` is chosen so that ``value`` is of the order of 1 (this is relevant for
  100 +model fitting). In addition, ``value`` is bound by a minimum (``min``) and
  101 +maximum (``max``) value, and a parameter may be free (``free="1"``) or fixed
  102 +(``free="0"``). The ``min``, ``max``, and ``free`` attributes are not
  103 +relevant here for the simulations, but they will be important for the model
  104 +fitting later.
  105 +
  106 +The spectral intensity I(E) (in units of photons/cm2/s/MeV) of the power
  107 +law is given by
  108 +
  109 +.. math::
  110 + \frac{dN}{dE} = N_0 \left( \frac{E}{E_0} \right)^{\gamma}
  111 +
  112 +where the parameters in the XML definition have the following mappings:
  113 +
  114 +* :math:`N_0` = ``Prefactor``
  115 +* :math:`\gamma` = ``Index``
  116 +* :math:`E_0` = ``Scale``
  117 +
  118 +.. warning::
  119 +
  120 + Energies are given in the XML file in MeV units. This is a GammaLib
  121 + convention that can not be modified. **So make sure you always use
  122 + MeV as energy unit in an XML file.**
  123 +
  124 +The instrumental background of CTA is modelled using the background
  125 +information provided in the IRF (``CTAIrfBackground``) multipled
  126 +by a power law. As it is defined here, the power law represents a
  127 +constant of 1, hence the background IRF will be used without any
  128 +modification. The power law will become active when fitting the data
  129 +later and allows a spectral adjustment of the background model that
  130 +may account for uncertainties in the background information provided
  131 +in the IRF.
  132 +
  133 +:ref:`ctobssim` has a couple of hidden parameters, the most important one being
  134 +certainly ``seed``. ``seed`` is an integer that specifies the seed value
  135 +for the random number generator, and changing this parameter will allow to
  136 +generate statistically independent Monte Carlo samples of CTA event data.
  137 +To use for example a seed value of 41 you should type:
  138 +
  139 +.. code-block:: bash
  140 +
  141 + $ ctobssim seed=41
  142 +
  143 +:ref:`ctobssim` will write 2 files in the working directory: ``events.fits``
  144 +and ``ctobssim.log``. The first file contains the simulated events in FITS
  145 +format and can be inspected using ``fv`` or ``ds9``. The FITS file will
  146 +contain three extensions: an empty primary image, a binary table named
  147 +``EVENTS`` that holds the events (one row per event), and a binary table
  148 +named ``GTI`` holding the Good Time Intervals (for the moment a single row
  149 +with 2 columns providing the start and the stop time of the simulated time
  150 +interval).
  151 +
  152 +The second file produced by :ref:`ctobssim` is a human readable log file that
  153 +contains information about the job execution. As example, the last lines
  154 +from this file are shown here:
  155 +
  156 +.. code-block:: xml
  157 +
  158 + 2015-12-07T20:48:30: +======================+
  159 + 2015-12-07T20:48:30: | Simulate observation |
  160 + 2015-12-07T20:48:30: +======================+
  161 + 2015-12-07T20:48:30: === CTA observation ===
  162 + 2015-12-07T20:48:30: Simulation area ...........: 1.9635e+11 cm2
  163 + 2015-12-07T20:48:30: Simulation cone ...........: RA=83.63 deg, Dec=22.01 deg, r=5.5 deg
  164 + 2015-12-07T20:48:30: Time interval .............: 0 - 1800 s
  165 + 2015-12-07T20:48:30: Photon energy range .......: 100 GeV - 100 TeV
  166 + 2015-12-07T20:48:30: Event energy range ........: 100 GeV - 100 TeV
  167 + 2015-12-07T20:48:30: Use model .................: Crab
  168 + 2015-12-07T20:48:30: Normalization .............: 1 [Crab]
  169 + 2015-12-07T20:48:30: Flux ......................: 5.87297e-10 [Crab] photons/cm2/s
  170 + 2015-12-07T20:48:30: Normalized flux ...........: 5.87297e-10 [Crab] photons/cm2/s
  171 + 2015-12-07T20:48:30: Photon rate ...............: 115.316 photons/s [Crab]
  172 + 2015-12-07T20:48:31: MC source photons .........: 207547 [Crab]
  173 + 2015-12-07T20:48:31: MC source events ..........: 3646 [Crab]
  174 + 2015-12-07T20:48:31: MC source events ..........: 3646 (all source models)
  175 + 2015-12-07T20:48:33: MC events outside ROI .....: 0
  176 + 2015-12-07T20:48:33: MC background events ......: 19039
  177 + 2015-12-07T20:48:33: MC events .................: 22685 (all models)
  178 +
  179 +Each line starts with the UTC time at which the line has been written. In
  180 +this run, 207547 Crab photons have been thrown over an area of 19.6 square
  181 +kilometres during a time interval of 1800 seconds. 3646 of these photons have
  182 +been registered by CTA as events. In the same time interval, 19039 background
  183 +events have been registred by CTA.
  184 +
  185 +You may change the name of the log file using the hidden parameter
  186 +``logfile``:
  187 +
  188 +.. code-block:: bash
  189 +
  190 + $ ctobssim logfile=my-private-log-file
  191 +
  192 +Furthermore, you may decide on the amount of information provided in the
  193 +log file (the chattiness of the executable) using the hidden parameter
  194 +``chatter``:
  195 +
  196 +.. code-block:: bash
  197 +
  198 + $ ctobssim chatter=4
  199 +
  200 +``chatter`` can vary between 0 and 4, 0 providing no information while 4
  201 +provides the most detailed information.
  202 +
  203 +**By default, all ctools have a chatter level of 2.**
  204 +
  205 +You may also duplicate the log file information into the console by setting
  206 +the hidden ``debug`` parameter to yes:
  207 +
  208 +.. code-block:: bash
  209 +
  210 + $ ctobssim debug=yes
... ...
doc/source/user_manual/getting_started/tsmap-crab.png
View file @c1b6ac1

70.7 KB | W: | H:

73.4 KB | W: | H:

  • 2-up
  • Swipe
  • Onion skin
doc/source/user_manual/getting_started/unbinned.rst 0 → 100644
  View file @c1b6ac1
  1 +.. _sec_unbinned_cta:
  2 +
  3 +Doing an unbinned analysis
  4 +~~~~~~~~~~~~~~~~~~~~~~~~~~
  5 +
  6 +As gamma-ray events are rare, the counts cubes generated by :ref:`ctbin`
  7 +will in general be sparsly populated, having many empty pixels, in
  8 +particular at high energies.
  9 +An alternative analysis technique consists of working directly on the event
  10 +list without binning the events in a counts cube. We will see the benefit of
  11 +such an analysis later once you re-run :ref:`ctlike` in unbinned mode.
  12 +
  13 +For unbinned analysis you first have to define the data space region over
  14 +which the analysis is done. This is similiar to the :ref:`ctbin` step for
  15 +a binned analysis where you defined the size of the counts cube, the energy
  16 +range, and the time interval. For unbinned analysis you have no such thing
  17 +as a counts cube, but you have to define over which region of the data space
  18 +the selected events are spread (because the ctools have to integrate over
  19 +this region to compute the total number of predicted events in the data space
  20 +that you analyse). Furthermore, you have to define what energy range is
  21 +covered, and what time interval is spanned by the data. All this is done
  22 +by the :ref:`ctselect` tool, which replaces the :ref:`ctbin` step in an
  23 +unbinned analysis.
  24 +
  25 +:ref:`ctselect` performs an event selection by choosing only events within
  26 +a given region-of-interest (ROI), within a given energy band, and within a
  27 +given time interval from the input event list. The ROI is a circular region on
  28 +the sky, for which you define the centre (in celestial coordinates) and the
  29 +radius. Such a circular ROI is sometimes also called an acceptance cone. The
  30 +following example shows how to run ctselect:
  31 +
  32 +.. code-block:: bash
  33 +
  34 + $ ctselect
  35 + Input event list or observation definition XML file [events.fits]
  36 + RA for ROI centre (degrees) (0-360) [83.63]
  37 + Dec for ROI centre (degrees) (-90-90) [22.01]
  38 + Radius of ROI (degrees) (0-180) [3.0]
  39 + Start time (CTA MET in seconds) [0.0]
  40 + End time (CTA MET in seconds) [0.0]
  41 + Lower energy limit (TeV) [0.1]
  42 + Upper energy limit (TeV) [100.0]
  43 + Output event list or observation definition XML file [selected_events.fits]
  44 +
  45 +:ref:`ctselect` takes the input event list ``events.fits``, performs an
  46 +event selection, and writes the selected event into the file
  47 +``selected_events.fits``. The parameters it will query for are the centre
  48 +of the ROI, the radius of the ROI, the start and stop time (in seconds),
  49 +and the energy lower and upper limits (in TeV). The event selection information
  50 +is also written as a set of data selection keywords to the output events
  51 +file ``selected_events.fits``, by respecting the same syntax that has been
  52 +implemented for Fermi/LAT. The following image is a screen dump of the data
  53 +selection keywords that have been written to the ``EVENTS`` header in the
  54 +file ``selected_events.fits``:
  55 +
  56 +.. figure:: dskeys.jpg
  57 + :width: 400px
  58 + :align: center
  59 +
  60 + *Data selection keywords*
  61 +
  62 +**It is mandatory for an unbinned analysis that these data selection keywords
  63 +exist in the FITS file.**
  64 +If they don't exist, :ref:`ctlike` will not execute in unbinned mode.
  65 +
  66 +Below some lines of the ``ctselect.log`` file that show the data selection
  67 +part:
  68 +
  69 +.. code-block:: xml
  70 +
  71 + 2015-12-06T23:44:52: +=================+
  72 + 2015-12-06T23:44:52: | Event selection |
  73 + 2015-12-06T23:44:52: +=================+
  74 + 2015-12-06T23:44:52: === CTA observation ===
  75 + 2015-12-06T23:44:52: Selected energy range .....: 0.1 - 100 TeV
  76 + 2015-12-06T23:44:52: Requested ROI .............: Centre(RA,DEC)=(83.63, 22.01) deg, Radius=3 deg
  77 + 2015-12-06T23:44:52: ROI of data ...............: Centre(RA,DEC)=(83.63, 22.01) deg, Radius=5 deg
  78 + 2015-12-06T23:44:52: Selected ROI ..............: Centre(RA,DEC)=(83.63, 22.01) deg, Radius=3 deg
  79 + 2015-12-06T23:44:52: cfitsio selection .........: ENERGY >= 0.10000000 && ENERGY <= 100.00000000 && ANGSEP(83.630000,22.010000,RA,DEC) <= 3.000000
  80 + 2015-12-06T23:44:52: FITS filename .............: /var/tmp/tmp.0.jHg5hJ[EVENTS][ENERGY >= 0.10000000 && ENERGY <= 100.00000000 && ANGSEP(83.630000,22.010000,RA,DEC) <= 3.000000]
  81 +
  82 +.. note::
  83 +
  84 + :ref:`ctobssim` will also write data selection keywords in the event
  85 + list FITS file, hence you can run :ref:`ctlike` directly on a FITS file
  86 + produced by :ref:`ctobssim`. Any selection performed by :ref:`ctselect`
  87 + needs to be fully enclosed within any previous selection, e.g. the ROI
  88 + needs to be fully enclosed in the acceptance cone used for event
  89 + simulation, the energy selection must be fully comprised in the
  90 + range of simulated energies, the same applies for the temporal selection.
  91 + :ref:`ctselect` will automatically adjust
  92 + the selection parameters to guarantee full enclosure. To keep track of
  93 + this adjustment, the :ref:`ctselect` log file quotes the requested
  94 + selection, any existing selections, and the selection that was finally
  95 + applied.
  96 +
  97 +.. warning::
  98 +
  99 + :ref:`ctselect` may of course also be used for event selection prior to
  100 + binned analysis, for example to select events for a given period in
  101 + time. **If you use** :ref:`ctselect` **however to make a spatial or energy
  102 + selection, make sure that the counts cube is fully enclosed in the
  103 + selection intervals.** Otherwise you will get empty zones in the counts
  104 + cube of which the ctools are not aware of, and the subsequent analysis
  105 + results will be wrong.
  106 +
  107 +Now that you have selected the events of interest, you can run ctlike in
  108 +unbinned mode. To do this you have to specify the selected event list
  109 +instead of the counts cube:
  110 +
  111 +.. code-block:: bash
  112 +
  113 + $ ctlike
  114 + Input event list, counts cube or observation definition XML file [cntcube.fits] selected_events.fits
  115 + Calibration database [prod2]
  116 + Instrument response function [South_0.5h]
  117 + Input model XML file [$CTOOLS/share/models/crab.xml]
  118 + Output model XML file [crab_results.xml]
  119 +
  120 +You will recognise that :ref:`ctlike` runs much faster in unbinned mode
  121 +compared to binned mode.
  122 +This is understandable as the selected event list contains
  123 +only 21203 events, while the binned counts cube we used before had
  124 +200 x 200 x 20 = 800000 pixels. As unbinned maximum likelihood fitting loops
  125 +over the events (while binned maximum likelihood loops over the pixels),
  126 +there are much less operations to perform in unbinned than in binned mode
  127 +(there is some additional overhead in unbinned mode that comes from
  128 +integrating the models over the region of interest, yet this is negligible
  129 +compared to the operations needed when looping over all pixels). So as long
  130 +as you work with small event lists, unbinned mode is faster (this
  131 +typically holds up to 100 hours of observing time).
  132 +Unbinned :ref:`ctlike` should also be more precise as no binning is performed,
  133 +hence there is no loss of information due to histogramming.
  134 +
  135 +Below you see the corresponding output from the ctlike.log file. The fitted
  136 +parameters are essentially identical to the ones found in binned mode.
  137 +The slight difference with respect to the binned analysis may be explained
  138 +by the different event sample that has been used for the analysis: while
  139 +binned likelihood works on rectangular counts cubes, unbinned likelihood works
  140 +on circular event selection regions. It is thus not possible to select exactly
  141 +the same events for both analyses.
  142 +
  143 +.. code-block:: xml
  144 +
  145 + 2015-12-07T21:02:17: +=================================+
  146 + 2015-12-07T21:02:17: | Maximum likelihood optimisation |
  147 + 2015-12-07T21:02:17: +=================================+
  148 + 2015-12-07T21:02:17: >Iteration 0: -logL=135278.644, Lambda=1.0e-03
  149 + 2015-12-07T21:02:17: >Iteration 1: -logL=135274.475, Lambda=1.0e-03, delta=4.168, max(|grad|)=5.806873 [Index:7]
  150 + 2015-12-07T21:02:17: >Iteration 2: -logL=135274.474, Lambda=1.0e-04, delta=0.001, max(|grad|)=-0.009463 [Index:7]
  151 + 2015-12-07T21:02:17:
  152 + ...
  153 + 2015-12-07T21:02:17: +=========================================+
  154 + 2015-12-07T21:02:17: | Maximum likelihood optimisation results |
  155 + 2015-12-07T21:02:17: +=========================================+
  156 + 2015-12-07T21:02:17: === GOptimizerLM ===
  157 + 2015-12-07T21:02:17: Optimized function value ..: 135274.474
  158 + 2015-12-07T21:02:17: Absolute precision ........: 0.005
  159 + 2015-12-07T21:02:17: Acceptable value decrease .: 2
  160 + 2015-12-07T21:02:17: Optimization status .......: converged
  161 + 2015-12-07T21:02:17: Number of parameters ......: 10
  162 + 2015-12-07T21:02:17: Number of free parameters .: 4
  163 + 2015-12-07T21:02:17: Number of iterations ......: 2
  164 + 2015-12-07T21:02:17: Lambda ....................: 1e-05
  165 + 2015-12-07T21:02:17: Maximum log likelihood ....: -135274.474
  166 + 2015-12-07T21:02:17: Observed events (Nobs) ...: 21203.000
  167 + 2015-12-07T21:02:17: Predicted events (Npred) ..: 21202.998 (Nobs - Npred = 0.00198937)
  168 + 2015-12-07T21:02:17: === GModels ===
  169 + 2015-12-07T21:02:17: Number of models ..........: 2
  170 + 2015-12-07T21:02:17: Number of parameters ......: 10
  171 + 2015-12-07T21:02:17: === GModelSky ===
  172 + 2015-12-07T21:02:17: Name ......................: Crab
  173 + 2015-12-07T21:02:17: Instruments ...............: all
  174 + 2015-12-07T21:02:17: Instrument scale factors ..: unity
  175 + 2015-12-07T21:02:17: Observation identifiers ...: all
  176 + 2015-12-07T21:02:17: Model type ................: PointSource
  177 + 2015-12-07T21:02:17: Model components ..........: "SkyDirFunction" * "PowerLaw" * "Constant"
  178 + 2015-12-07T21:02:17: Number of parameters ......: 6
  179 + 2015-12-07T21:02:17: Number of spatial par's ...: 2
  180 + 2015-12-07T21:02:17: RA .......................: 83.6331 [-360,360] deg (fixed,scale=1)
  181 + 2015-12-07T21:02:17: DEC ......................: 22.0145 [-90,90] deg (fixed,scale=1)
  182 + 2015-12-07T21:02:17: Number of spectral par's ..: 3
  183 + 2015-12-07T21:02:17: Prefactor ................: 5.81583e-16 +/- 1.01727e-17 [1e-23,1e-13] ph/cm2/s/MeV (free,scale=1e-16,gradient)
  184 + 2015-12-07T21:02:17: Index ....................: -2.50611 +/- 0.0153542 [-0,-5] (free,scale=-1,gradient)
  185 + 2015-12-07T21:02:17: PivotEnergy ..............: 300000 [10000,1e+09] MeV (fixed,scale=1e+06,gradient)
  186 + 2015-12-07T21:02:17: Number of temporal par's ..: 1
  187 + 2015-12-07T21:02:17: Normalization ............: 1 (relative value) (fixed,scale=1,gradient)
  188 + 2015-12-07T21:02:17: === GCTAModelIrfBackground ===
  189 + 2015-12-07T21:02:17: Name ......................: CTABackgroundModel
  190 + 2015-12-07T21:02:17: Instruments ...............: CTA
  191 + 2015-12-07T21:02:17: Instrument scale factors ..: unity
  192 + 2015-12-07T21:02:17: Observation identifiers ...: all
  193 + 2015-12-07T21:02:17: Model type ................: "PowerLaw" * "Constant"
  194 + 2015-12-07T21:02:17: Number of parameters ......: 4
  195 + 2015-12-07T21:02:17: Number of spectral par's ..: 3
  196 + 2015-12-07T21:02:17: Prefactor ................: 0.990866 +/- 0.0136406 [0.001,1000] ph/cm2/s/MeV (free,scale=1,gradient)
  197 + 2015-12-07T21:02:17: Index ....................: 0.00536014 +/- 0.00839916 [-5,5] (free,scale=1,gradient)
  198 + 2015-12-07T21:02:17: PivotEnergy ..............: 1e+06 [10000,1e+09] MeV (fixed,scale=1e+06,gradient)
  199 + 2015-12-07T21:02:17: Number of temporal par's ..: 1
  200 + 2015-12-07T21:02:17: Normalization ............: 1 (relative value) (fixed,scale=1,gradient)
... ...
doc/source/user_manual/glossary.rst
  View file @c1b6ac1
1 1 Glossary
2 2 ========
3 3  
4   -- **GammaLib** (`<http://gammalib.sourceforge.net/>`_)
  4 +- **GammaLib** (`<http://cta.irap.omp.eu/gammalib/>`_)
5 5  
6 6 A versatile toolbox for scientific analysis of astronomical
7 7 gamma-ray data.
... ...
doc/source/user_manual/index.rst
  View file @c1b6ac1
... ... @@ -8,8 +8,6 @@ User Manual
8 8 introduction
9 9 getting
10 10 getting_started/index
11   - enhancing
12   - expert
13 11 plotting
14 12 glossary
15 13  
... ...
doc/source/user_manual/introduction.rst
  View file @c1b6ac1
... ... @@ -22,6 +22,13 @@ also be specified as arguments separated by a whitespace to the ctool:
22 22  
23 23 $ ctobssim ra=83.63 dec=22.01 rad=5.0 tmin=0 tmax=1800 emin=0.1 emax=100.0 caldb=prod2 irf=South_50h inmodel=$CTOOLS/share/models/crab.xml outevents=events.fits
24 24  
  25 +If you need help about the usage of a ctool or a cscript, type the name of
  26 +the ctool or cscript followed by the ``--help`` option:
  27 +
  28 +.. code-block:: bash
  29 +
  30 + $ ctobssim --help
  31 +
25 32 ctools includes also a Python module that declares every ctool as a
26 33 Python class. The following example illustrates the usage:
27 34  
... ... @@ -47,7 +54,7 @@ command line or used as Python classes, as illustrated below:
47 54  
48 55 In this User Manual you will now learn how to install and use the ctools
49 56 package.
50   -If you encounter any problems, please read the :ref:`issues` section.
51   -If you're desperate, you may need :ref:`help`.
  57 +If you encounter any problems, please read the :ref:`faq` and :ref:`issues`
  58 +sections. If you're desperate, you may need :ref:`help`.
52 59 And you should read the :ref:`develop` section if you would like to
53 60 contribute to the ctools developments.
... ...
doc/source/user_manual/plotting.rst
  View file @c1b6ac1
1 1 Plotting
2 2 ========
3 3  
4   -Gammalib and ctools currently do not include classes and scripts to make plots.
  4 +Gammalib and ctools do not include classes and scripts to make plots.
5 5  
6   -This is intentional because creating and maintaining plotting tools that work on most user's machines
7   -and cover most user's needs is a big project in itself, and deciding to support a
8   -plotting package that is popular now as part of the CTA science tools could become very problematic in the future.
  6 +This is intentional because creating and maintaining plotting tools that
  7 +work on most user's machines and cover most user's needs is a big project
  8 +in itself, and deciding to support a plotting package that is popular now
  9 +as part of the CTA science tools could become very problematic in the
  10 +future.
  11 +
  12 +But we realise that most ctools users need to create plots for their
  13 +high-level science results, so on this page we provide a few pointers
  14 +to external packages and tools.
9 15  
10   -But we realise that most ctools users need to create plots for their high-level science results,
11   -so on this page we provide a few pointers to external packages and tools.
12 16  
13 17 General
14 18 -------
15 19  
16   -The most common way to create publication-quality astronomy plots at the moment is to use the `matplotlib`_
17   -Python plotting package. As illustrated by the `matplotlib gallery`_, virtually any plot can be constructed,
18   -but matplotlib doesn't have built-in easy-to-use classes or functions to create the common plots for gamma-ray
19   -astronomy, which are sky maps and spectra, so in the sections below we give some specific pointers for those.
  20 +The most common way to create publication-quality astronomy plots at the
  21 +moment is to use the `matplotlib`_ Python plotting package. As illustrated
  22 +by the `matplotlib gallery`_, virtually any plot can be constructed,
  23 +but matplotlib doesn't have built-in easy-to-use classes or functions to
  24 +create the common plots for gamma-ray astronomy, which are sky maps and
  25 +spectra, so in the sections below we give some specific pointers for those.
  26 +
20 27  
21 28 Sky maps
22 29 --------
23 30  
24   -For creating publication quality sky map plots via a Python script a good choice is to use `APLPy`_, `WCSAxes`_
25   -or `kapteyn`_, which are all based on matplotlib.
  31 +For creating publication quality sky map plots via a Python script a good
  32 +choice is to use `APLPy`_, `WCSAxes`_ or `kapteyn`_, which are all based on
  33 +matplotlib.
26 34  
27   -You can also use interactive astronomy image viewers like `DS9`_, `Aladin`_ or `Ginga`_
28   -which allow you to save the image to a PNG or PDF file after customising it interactively,
29   -but also contain command line options to create the plot, i.e. you can write a bash or Python script
30   -to make the plot reproducible (DS9 and Ginga also feature direct communication with Python,
31   -but that is a bit harder to use and usually used for interactive image analysis, not plotting scripts).
  35 +You can also use interactive astronomy image viewers like `DS9`_, `Aladin`_
  36 +or `Ginga`_ which allow you to save the image to a PNG or PDF file after
  37 +customising it interactively, but also contain command line options to create
  38 +the plot, i.e. you can write a bash or Python script to make the plot
  39 +reproducible (DS9 and Ginga also feature direct communication with Python,
  40 +but that is a bit harder to use and usually used for interactive image
  41 +analysis, not plotting scripts).
32 42  
33 43  
34 44 Spectra and light curves
35 45 ------------------------
36 46  
37   -To plot spectra or spectral energy distributions (including flux model curves, flux model error bands,
38   -flux points and residuals) and light curves, you can use matplotlib directly,
39   -or use the classes and scripts in `Gammapy`_.
40   -
41   -Another option is to use virtual observatory interactive spectrum tools like `IRIS`_, `CASSIS`_ or `VOSpec`_
42   -which allow you to save the plot to a PNG or PDF file after creating it interactively.
  47 +To plot spectra or spectral energy distributions (including flux model curves,
  48 +flux model error bands, flux points and residuals) and light curves, you can
  49 +use matplotlib directly, or use the classes and scripts in `Gammapy`_.
43 50  
  51 +Another option is to use virtual observatory interactive spectrum tools
  52 +like `IRIS`_, `CASSIS`_ or `VOSpec`_ which allow you to save the plot to a
  53 +PNG or PDF file after creating it interactively.
44 54  
45 55 .. _DS9: http://ds9.si.edu/
46 56 .. _Aladin: http://aladin.u-strasbg.fr/
... ...