Eirik Hatlen / ctools

Commit 6f602f417bd591b6a1b884c5e6173c8d09fad682

Authored by Jürgen Knödlseder
1 parent bc55d6e1

Remove ctools from Python rst file

Inline Side-by-side
Showing 1 changed file with 0 additions and 240 deletions
doc/source/users/tutorials/quickstart/python.rst deleted
View file @bc55d6e
1   -.. _start_python:
2   -
3   -Using ctools from Python
4   -------------------------
5   -
6   - .. admonition:: What you will learn
7   -
8   - You will learn how to **use the ctools and cscripts from Python** instead
9   - of typing the commands in the console.
10   -
11   -ctools provides two Python modules that allow using all tools and scripts as
12   -Python classes. To use ctools from Python you have to import the ``ctools``
13   -and ``cscripts`` modules into Python. You should also import the ``gammalib``
14   -module, as ctools without GammaLib is generally not very useful.
15   -
16   - .. warning::
17   -
18   - Always import ``gammalib`` before you import ``ctools`` and ``cscripts``.
19   -
20   -To simulate the event data from Python you have to type the following (recall
21   -:ref:`how to simulate event data from the command line <start_simulating>` for
22   -comparison) :
23   -
24   -.. code-block:: python
25   -
26   - >>> import gammalib
27   - >>> import ctools
28   - >>> import cscripts
29   - >>> sim = ctools.ctobssim()
30   - >>> sim['inmodel'] = '${CTOOLS}/share/models/crab.xml'
31   - >>> sim['outevents'] = 'events.fits'
32   - >>> sim['caldb'] = 'prod2'
33   - >>> sim['irf'] = 'South_0.5h'
34   - >>> sim['ra'] = 83.63
35   - >>> sim['dec'] = 22.01
36   - >>> sim['rad'] = 5.0
37   - >>> sim['tmin'] = '2020-01-01T00:00:00'
38   - >>> sim['tmax'] = '2020-01-01T01:00:00'
39   - >>> sim['emin'] = 0.03
40   - >>> sim['emax'] = 200.0
41   - >>> sim.execute()
42   -
43   -The first line after the ``import`` statements generates an instance of the
44   -:ref:`ctobssim` tool as a Python class. User parameters are then set using the
45   -``[ ]`` operator. After setting all parameters the ``execute()`` method is called to
46   -execute the :ref:`ctobssim` tool. On output the ``events.fits`` FITS file is
47   -created. Until now everything is identical to running the tool from the command
48   -line.
49   -
50   - .. note::
51   -
52   - See the :ref:`reference` for a list of parameters and their types for
53   - all tools and scripts. You can also inspect all parameters of a specific
54   - tool by calling the tool follwed by ``--help`` from the command line, e.g.
55   -
56   - .. code-block:: bash
57   -
58   - $ ctobssim --help
59   -
60   -Instead of executing the tool you may also *run* the tool using
61   -
62   -.. code-block:: python
63   -
64   - >>> sim.run()
65   -
66   -The main difference to the ``execute()`` method is that the ``run()`` method
67   -will not write the simulated event file to disk. Why is this useful? Well,
68   -after having typed ``sim.run()`` the :ref:`ctobssim` class still exists as an
69   -object in memory, including all the simulated events. The :ref:`ctobssim`
70   -class has an ``obs()`` method that returns an observation container that holds
71   -the simulated CTA observation with its associated events. To visualise this
72   -container, type:
73   -
74   -.. code-block:: python
75   -
76   - >>> print(sim.obs())
77   - === GObservations ===
78   - Number of observations ....: 1
79   - Number of models ..........: 2
80   - Number of observed events .: 202766
81   - Number of predicted events : 0
82   -
83   -There is one CTA observation in the container and to visualise that observation
84   -type:
85   -
86   -.. code-block:: python
87   -
88   - >>> print(sim.obs()[0])
89   - === GCTAObservation ===
90   - Name ......................:
91   - Identifier ................:
92   - Instrument ................: CTA
93   - Event file ................: events.fits
94   - Event type ................: EventList
95   - Statistics ................: Poisson
96   - Ontime ....................: 3599.99999976158 s
97   - Livetime ..................: 3527.99999976635 s
98   - Deadtime correction .......: 0.98
99   - User energy range .........: undefined
100   - === GCTAPointing ===
101   - Pointing direction ........: (RA,Dec)=(83.63,22.01)
102   - === GCTAResponseIrf ===
103   - Caldb mission .............: cta
104   - Caldb instrument ..........: prod2
105   - Response name .............: South_0.5h
106   - Energy dispersion .........: Not used
107   - Save energy range .........: undefined
108   - === GCTAEventList ===
109   - Number of events ..........: 202766 (disposed in "events.fits")
110   - Time interval .............: 58849.0008007407 - 58849.0424674074 days
111   - Energy interval ...........: 0.03 - 200 TeV
112   - Region of interest ........: RA=83.63, DEC=22.01 [0,0] Radius=5 deg
113   -
114   -The observation contains a CTA event list that is implement by the GammaLib
115   -class ``GCTAEventList``. You can access the event list using the ``events()``
116   -method. To visualise the individual events you can iterate over the events
117   -using a for loop. This will show the simulated celestial coordinates (RA, DEC),
118   -the coordinate in the camera system [DETX, DETY], the energies and the
119   -terrestrial times (TT) of all events. To do this, type:
120   -
121   -.. code-block:: python
122   -
123   - >>> events = sim.obs()[0].events()
124   - >>> for event in events:
125   - ... print(event)
126   - ...
127   - Dir=RA=83.6182556152344, DEC=22.2843074798584 [0.00478756989312195,-0.000189682185722814] Energy=63.157357275486 GeV Time=315532804.699509 s (TT)
128   - Dir=RA=83.8212127685547, DEC=21.9629154205322 [-0.000819836781619686,0.0030950360932479] Energy=53.25997620821 GeV Time=315532805.889628 s (TT)
129   - Dir=RA=83.6474838256836, DEC=22.0208301544189 [0.000189049359871014,0.000282857291220907] Energy=69.6808248758316 GeV Time=315532806.050809 s (TT)
130   - ...
131   -
132   -You can now benefit from the fact that you have some simulated events in
133   -memory to fit a model to these events using the :ref:`ctlike` class.
134   -You will do this in unbinned mode. Here is what you have to type:
135   -
136   -.. code-block:: python
137   -
138   - >>> like = ctools.ctlike(sim.obs())
139   - >>> like.run()
140   -
141   -This is pretty compact. Where are the user parameters?
142   -:ref:`ctlike` doesn't in fact need any parameters as all the relevant
143   -information is already contained in the observation container produced by the
144   -:ref:`ctobssim` class.
145   -And you may have recognised that you constructed the :ref:`ctlike`
146   -instance by using the :ref:`ctobssim` observation container as constructor
147   -argument.
148   -
149   - .. note::
150   -
151   - An observation container, implemented by the ``GObservations`` class
152   - of GammaLib, is the fundamental brick of any ctools analysis. Many tools
153   - and scripts handle observation containers, and accept them upon
154   - construction and return them after running the tool via the ``obs()``
155   - method.
156   -
157   - Passing observation containers between ctools classes is a very
158   - convenient and powerful way of building in-memory analysis pipelines.
159   - However, this implies that you need some computing ressources when
160   - dealing with large observation containers (for example if you want to
161   - analyse a few 100 hours of data at once). Also, if the script crashes
162   - the information is lost.
163   -
164   -To check how the fit went you can inspect the optimiser used by
165   -:ref:`ctlike` by typing:
166   -
167   -.. code-block:: python
168   -
169   - >>> print(like.opt())
170   - === GOptimizerLM ===
171   - Optimized function value ..: 757618.425
172   - Absolute precision ........: 0.005
173   - Acceptable value decrease .: 2
174   - Optimization status .......: converged
175   - Number of parameters ......: 10
176   - Number of free parameters .: 4
177   - Number of iterations ......: 2
178   - Lambda ....................: 1e-05
179   -
180   -You see that the fit converged after 2 iterations. Out of 10 parameters in the
181   -model 4 have been fitted (the others were kept fixed). To inspect the fit
182   -results you can print the model container that can be access using the
183   -``models()`` method of the observation container:
184   -
185   -.. code-block:: python
186   -
187   - >>> print(like.obs().models())
188   - === GModels ===
189   - Number of models ..........: 2
190   - Number of parameters ......: 10
191   - === GModelSky ===
192   - Name ......................: Crab
193   - Instruments ...............: all
194   - Instrument scale factors ..: unity
195   - Observation identifiers ...: all
196   - Model type ................: PointSource
197   - Model components ..........: "PointSource" * "PowerLaw" * "Constant"
198   - Number of parameters ......: 6
199   - Number of spatial par's ...: 2
200   - RA .......................: 83.6331 [-360,360] deg (fixed,scale=1)
201   - DEC ......................: 22.0145 [-90,90] deg (fixed,scale=1)
202   - Number of spectral par's ..: 3
203   - Prefactor ................: 5.73901839854211e-16 +/- 5.75150678022232e-18 [1e-23,1e-13] ph/cm2/s/MeV (free,scale=1e-16,gradient)
204   - Index ....................: -2.46442704108736 +/- 0.00738985717701118 [-0,-5] (free,scale=-1,gradient)
205   - PivotEnergy ..............: 300000 [10000,1000000000] MeV (fixed,scale=1000000,gradient)
206   - Number of temporal par's ..: 1
207   - Normalization ............: 1 (relative value) (fixed,scale=1,gradient)
208   - === GCTAModelIrfBackground ===
209   - Name ......................: CTABackgroundModel
210   - Instruments ...............: CTA
211   - Instrument scale factors ..: unity
212   - Observation identifiers ...: all
213   - Model type ................: "PowerLaw" * "Constant"
214   - Number of parameters ......: 4
215   - Number of spectral par's ..: 3
216   - Prefactor ................: 0.995734795709415 +/- 0.00725726198557001 [0.001,1000] ph/cm2/s/MeV (free,scale=1,gradient)
217   - Index ....................: -0.00198344390952578 +/- 0.00257263793207067 [-5,5] (free,scale=1,gradient)
218   - PivotEnergy ..............: 1000000 [10000,1000000000] MeV (fixed,scale=1000000,gradient)
219   - Number of temporal par's ..: 1
220   - Normalization ............: 1 (relative value) (fixed,scale=1,gradient)
221   -
222   -Suppose you want to repeat the fit by optimising also the position of the
223   -point source. This is easy from Python. Type the following:
224   -
225   -.. code-block:: python
226   -
227   - >>> like.obs().models()['Crab']['RA'].free()
228   - >>> like.obs().models()['Crab']['DEC'].free()
229   - >>> like.run()
230   - >>> print(like.obs().models())
231   - ...
232   - RA .......................: 83.6334964430607 +/- 0.000614768905318078 [-360,360] deg (free,scale=1)
233   - DEC ......................: 22.0149467750683 +/- 0.000559548446961086 [-90,90] deg (free,scale=1)
234   -
235   -
236   -The ``like.obs().models()`` method provides the model container, using the
237   -``['Crab']`` operator you access the Crab model in that container and using
238   -the ``['RA']`` and ``['DEC']`` operators you access the relevant model
239   -parameters. The ``free()`` method frees a parameter, the opposite would be a
240   -call to the ``fix()`` method.