Commit 6f602f417bd591b6a1b884c5e6173c8d09fad682
1 parent
bc55d6e1
Remove ctools from Python rst file
Showing
1 changed file
with
0 additions
and
240 deletions
doc/source/users/tutorials/quickstart/python.rst deleted
| 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. |