Commit c1b6ac1b03ef28ec29f57db5b6366b3b424cec76
1 parent
bf06528d
Update ctools documentation.
Showing
24 changed files
with
1259 additions
and
1258 deletions
doc/source/download.rst
| @@ -13,7 +13,7 @@ bugs. | @@ -13,7 +13,7 @@ bugs. | ||
| 13 | Releases | 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 | Below a table of ctools releases. Please note that at this stage of the | 18 | Below a table of ctools releases. Please note that at this stage of the |
| 19 | project there is a strict link between the ctools and gammalib versions. | 19 | project there is a strict link between the ctools and gammalib versions. |
| @@ -28,6 +28,9 @@ gammalib. | @@ -28,6 +28,9 @@ gammalib. | ||
| 28 | * - `ctools <http://cta.irap.omp.eu/ctools/releases/ctools/ChangeLog>`_ | 28 | * - `ctools <http://cta.irap.omp.eu/ctools/releases/ctools/ChangeLog>`_ |
| 29 | - `gammalib <http://cta.irap.omp.eu/ctools/releases/gammalib/ChangeLog>`_ | 29 | - `gammalib <http://cta.irap.omp.eu/ctools/releases/gammalib/ChangeLog>`_ |
| 30 | - Mac OS X package | 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 | * - `0.10.0 <http://cta.irap.omp.eu/ctools/releases/ctools/ctools-0.10.0.tar.gz>`_ | 34 | * - `0.10.0 <http://cta.irap.omp.eu/ctools/releases/ctools/ctools-0.10.0.tar.gz>`_ |
| 32 | - `0.11.0 <http://cta.irap.omp.eu/ctools/releases/gammalib/gammalib-0.11.0.tar.gz>`_ | 35 | - `0.11.0 <http://cta.irap.omp.eu/ctools/releases/gammalib/gammalib-0.11.0.tar.gz>`_ |
| 33 | - `ctools-0.10.0-macosx10.3.dmg <http://cta.irap.omp.eu/ctools/releases/ctools/ctools-0.10.0-macosx10.3.dmg>`_ | 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
| 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
| 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
| @@ -29,15 +29,15 @@ No system administrator privileges are needed to install ctools. | @@ -29,15 +29,15 @@ No system administrator privileges are needed to install ctools. | ||
| 29 | 29 | ||
| 30 | .. _sec_installing_gammalib: | 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 | installed and configured before ctools can be installed. In case that | 36 | installed and configured before ctools can be installed. In case that |
| 37 | ctools is already installed on your system you may skip reading this | 37 | ctools is already installed on your system you may skip reading this |
| 38 | section and continue with the :ref:`sec_building_ctools` section. | 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 | - About 200 MB of free disk space. | 42 | - About 200 MB of free disk space. |
| 43 | 43 | ||
| @@ -58,12 +58,12 @@ You will need the following to build the gammalib: | @@ -58,12 +58,12 @@ You will need the following to build the gammalib: | ||
| 58 | Furthermore it is recommended to have readline and ncurses installed | 58 | Furthermore it is recommended to have readline and ncurses installed |
| 59 | (including the developer packages). | 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 | in an appropriate location (for example ``$HOME/builds``), and type | 62 | in an appropriate location (for example ``$HOME/builds``), and type |
| 63 | 63 | ||
| 64 | .. code-block:: bash | 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 | (the ``$`` symbol indicates the console prompt and is not part of the | 68 | (the ``$`` symbol indicates the console prompt and is not part of the |
| 69 | command that you should type in). | 69 | command that you should type in). |
| @@ -73,7 +73,7 @@ typing | @@ -73,7 +73,7 @@ typing | ||
| 73 | 73 | ||
| 74 | .. code-block:: bash | 74 | .. code-block:: bash |
| 75 | 75 | ||
| 76 | - $ cd gammalib-0.11.0 | 76 | + $ cd gammalib-1.0.0 |
| 77 | $ ./configure | 77 | $ ./configure |
| 78 | $ make | 78 | $ make |
| 79 | $ make check | 79 | $ make check |
| @@ -82,6 +82,8 @@ typing | @@ -82,6 +82,8 @@ typing | ||
| 82 | The last step may require system administator privileges. In this case, | 82 | The last step may require system administator privileges. In this case, |
| 83 | use | 83 | use |
| 84 | 84 | ||
| 85 | +.. code-block:: bash | ||
| 86 | + | ||
| 85 | $ sudo make install | 87 | $ sudo make install |
| 86 | 88 | ||
| 87 | If you do not have system administrator privileges, change the install | 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,7 +135,7 @@ an appropriate location (for example ``$HOME/builds``), and type | ||
| 133 | 135 | ||
| 134 | .. code-block:: bash | 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 | (the ``$`` symbol indicates the console prompt and is not part of the | 140 | (the ``$`` symbol indicates the console prompt and is not part of the |
| 139 | command that you should type in). | 141 | command that you should type in). |
| @@ -142,7 +144,7 @@ Step in the directory and build the ctools by typing | @@ -142,7 +144,7 @@ Step in the directory and build the ctools by typing | ||
| 142 | 144 | ||
| 143 | .. code-block:: bash | 145 | .. code-block:: bash |
| 144 | 146 | ||
| 145 | - $ cd ctools-0.10.0 | 147 | + $ cd ctools-1.0.0 |
| 146 | $ ./configure | 148 | $ ./configure |
| 147 | $ make | 149 | $ make |
| 148 | 150 | ||
| @@ -181,7 +183,7 @@ following output at the end of the unit testing: | @@ -181,7 +183,7 @@ following output at the end of the unit testing: | ||
| 181 | PASS: test_python.py | 183 | PASS: test_python.py |
| 182 | make[4]: Nothing to be done for `all'. | 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 | # TOTAL: 3 | 188 | # TOTAL: 3 |
| 187 | # PASS: 3 | 189 | # PASS: 3 |
| @@ -345,19 +347,8 @@ As a quick check that your setup is okay you can run ``csinfo check``: | @@ -345,19 +347,8 @@ As a quick check that your setup is okay you can run ``csinfo check``: | ||
| 345 | ===> Your Gammalib / ctools setup is OK. | 347 | ===> Your Gammalib / ctools setup is OK. |
| 346 | 348 | ||
| 347 | If the setup is not okay, run the ``csinfo info`` command to print | 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 | .. _sec_known_problems: | 354 | .. _sec_known_problems: |
doc/source/user_manual/getting_started/beyond.rst
| @@ -3,12 +3,12 @@ | @@ -3,12 +3,12 @@ | ||
| 3 | Beyond the first steps | 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 | picture about the capabilities of ctools. | 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 | .. toctree:: | 13 | .. toctree:: |
| 14 | :maxdepth: 2 | 14 | :maxdepth: 2 |
| @@ -19,11 +19,3 @@ And you should be ready for doing your own cutting edge analyses. | @@ -19,11 +19,3 @@ And you should be ready for doing your own cutting edge analyses. | ||
| 19 | beyond_residual | 19 | beyond_residual |
| 20 | beyond_irf | 20 | beyond_irf |
| 21 | beyond_model | 21 | beyond_model |
| 22 | - | ||
| 23 | - | ||
| 24 | - | ||
| 25 | - | ||
| 26 | - | ||
| 27 | - | ||
| 28 | - | ||
| 29 | - |
doc/source/user_manual/getting_started/beyond_combine.rst
| @@ -25,9 +25,9 @@ nebula, each offset by 0.5 deg from the nebula in opposite directions: | @@ -25,9 +25,9 @@ nebula, each offset by 0.5 deg from the nebula in opposite directions: | ||
| 25 | Lower energy limit (TeV) [0.1] | 25 | Lower energy limit (TeV) [0.1] |
| 26 | Upper energy limit (TeV) [100.0] | 26 | Upper energy limit (TeV) [100.0] |
| 27 | Calibration database [prod2] | 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 | .. code-block:: bash | 32 | .. code-block:: bash |
| 33 | 33 | ||
| @@ -40,16 +40,16 @@ nebula, each offset by 0.5 deg from the nebula in opposite directions: | @@ -40,16 +40,16 @@ nebula, each offset by 0.5 deg from the nebula in opposite directions: | ||
| 40 | Lower energy limit (TeV) [0.1] | 40 | Lower energy limit (TeV) [0.1] |
| 41 | Upper energy limit (TeV) [100.0] | 41 | Upper energy limit (TeV) [100.0] |
| 42 | Calibration database [prod2] | 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 | This will produce the two event files ``events1.fits`` and ``events2.fits`` | 47 | This will produce the two event files ``events1.fits`` and ``events2.fits`` |
| 48 | on disk. | 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 | collects both observations in a list. | 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 | .. code-block:: xml | 54 | .. code-block:: xml |
| 55 | 55 | ||
| @@ -86,116 +86,140 @@ ctools knows which instrument specific functions need to be called.** | @@ -86,116 +86,140 @@ ctools knows which instrument specific functions need to be called.** | ||
| 86 | Imaging Air Cherenkov Telescope in a joint analysis. | 86 | Imaging Air Cherenkov Telescope in a joint analysis. |
| 87 | **Please recall that instrument strings are case sensitive.** | 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 | .. code-block:: bash | 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 | Calibration database [prod2] | 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 | filename of the observation definition XML file (here ``obs.xml``) as input | 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 | .. code-block:: xml | 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 | The log file indicates that the fit converged quickly, the spectral | 224 | The log file indicates that the fit converged quickly, the spectral |
| 201 | parameters of the Crab nebula have now been constrained using the events | 225 | parameters of the Crab nebula have now been constrained using the events |
doc/source/user_manual/getting_started/beyond_irf.rst
| @@ -6,9 +6,9 @@ Connecting observations to dedicated instrument response functions | @@ -6,9 +6,9 @@ Connecting observations to dedicated instrument response functions | ||
| 6 | So far the same instrument response function has been used for all | 6 | So far the same instrument response function has been used for all |
| 7 | observations in our analysis examples. | 7 | observations in our analysis examples. |
| 8 | You may have recognised that we always specified the calibration database | 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 | are shipped with ctools. | 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 | need to specify dedicated instrument response functions for the | 12 | need to specify dedicated instrument response functions for the |
| 13 | different observations. | 13 | different observations. |
| 14 | 14 | ||
| @@ -26,40 +26,40 @@ the northern array and the other with the southern array: | @@ -26,40 +26,40 @@ the northern array and the other with the southern array: | ||
| 26 | Lower energy limit (TeV) [0.1] | 26 | Lower energy limit (TeV) [0.1] |
| 27 | Upper energy limit (TeV) [100.0] | 27 | Upper energy limit (TeV) [100.0] |
| 28 | Calibration database [prod2] | 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 | .. code-block:: bash | 33 | .. code-block:: bash |
| 34 | 34 | ||
| 35 | $ ctobssim | 35 | $ ctobssim |
| 36 | RA of pointing (degrees) (0-360) [83.63] | 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 | Radius of FOV (degrees) (0-180) [5.0] | 38 | Radius of FOV (degrees) (0-180) [5.0] |
| 39 | Start time (MET in s) [0.0] | 39 | Start time (MET in s) [0.0] |
| 40 | End time (MET in s) [1800.0] | 40 | End time (MET in s) [1800.0] |
| 41 | Lower energy limit (TeV) [0.1] | 41 | Lower energy limit (TeV) [0.1] |
| 42 | Upper energy limit (TeV) [100.0] | 42 | Upper energy limit (TeV) [100.0] |
| 43 | Calibration database [prod2] | 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 | observation definition XML file: | 49 | observation definition XML file: |
| 50 | 50 | ||
| 51 | .. code-block:: xml | 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 | </observation_list> | 63 | </observation_list> |
| 64 | 64 | ||
| 65 | Each observation now has a ``Calibration`` parameter with the attributes | 65 | Each observation now has a ``Calibration`` parameter with the attributes |
| @@ -97,126 +97,136 @@ Within this database there are six response functions: | @@ -97,126 +97,136 @@ Within this database there are six response functions: | ||
| 97 | ``North_0.5h``, ``North_5h``, ``North_50h``, | 97 | ``North_0.5h``, ``North_5h``, ``North_50h``, |
| 98 | ``South_0.5h``, ``South_5h``, and ``South_50h``. | 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 | .. code-block:: bash | 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 | To see the usage of the individual response functions you may inspect the | 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 | function and that the filename of the response information differs for | 113 | function and that the filename of the response information differs for |
| 112 | both observations. | 114 | both observations. |
| 113 | 115 | ||
| 114 | .. code-block:: xml | 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 | A more fine grained control over the response function can be achieved by | 231 | A more fine grained control over the response function can be achieved by |
| 222 | specifying individual filenames for the various response components. | 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,18 +238,18 @@ This is definitely expert mode, to be used with utmost care. | ||
| 228 | <?xml version="1.0" standalone="no"?> | 238 | <?xml version="1.0" standalone="no"?> |
| 229 | <observation_list title="observation library"> | 239 | <observation_list title="observation library"> |
| 230 | <observation name="Crab" id="00001" instrument="CTA"> | 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 | </observation> | 246 | </observation> |
| 237 | <observation name="Crab" id="00002" instrument="CTA"> | 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 | </observation> | 253 | </observation> |
| 244 | </observation_list> | 254 | </observation_list> |
| 245 | 255 | ||
| @@ -264,5 +274,3 @@ file is given below: | @@ -264,5 +274,3 @@ file is given below: | ||
| 264 | <parameter name="BkgCube" file="bkgcube2.fits"/> | 274 | <parameter name="BkgCube" file="bkgcube2.fits"/> |
| 265 | </observation> | 275 | </observation> |
| 266 | </observation_list> | 276 | </observation_list> |
| 267 | - | ||
| 268 | - |
doc/source/user_manual/getting_started/beyond_model.rst
| @@ -26,20 +26,15 @@ specified by the following observation definition XML file: | @@ -26,20 +26,15 @@ specified by the following observation definition XML file: | ||
| 26 | </observation> | 26 | </observation> |
| 27 | </observation_list> | 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 | This is illustrated in the model XML file below that now has two background | 31 | This is illustrated in the model XML file below that now has two background |
| 32 | components. | 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 | .. code-block:: xml | 39 | .. code-block:: xml |
| 45 | 40 | ||
| @@ -72,13 +67,21 @@ event list. | @@ -72,13 +67,21 @@ event list. | ||
| 72 | </source> | 67 | </source> |
| 73 | </source_library> | 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 | Obviously, the upper observation has larger residuals owing to the ten | 85 | Obviously, the upper observation has larger residuals owing to the ten |
| 83 | times larger background rate that was used in the simulation of the | 86 | times larger background rate that was used in the simulation of the |
| 84 | associated data. | 87 | associated data. |
doc/source/user_manual/getting_started/beyond_residual.rst
| @@ -22,11 +22,11 @@ Suppose that you have done the following unbinned ``ctlike`` analysis: | @@ -22,11 +22,11 @@ Suppose that you have done the following unbinned ``ctlike`` analysis: | ||
| 22 | .. code-block:: bash | 22 | .. code-block:: bash |
| 23 | 23 | ||
| 24 | $ ctlike | 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 | Calibration database [prod2] | 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 | The :ref:`csresmap` script is then used as follows: | 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,18 +34,19 @@ The :ref:`csresmap` script is then used as follows: | ||
| 34 | 34 | ||
| 35 | $ csresmap | 35 | $ csresmap |
| 36 | Parfile csresmap.par not found. Create default parfile. | 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 | Calibration database [prod2] | 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 | Coordinate System (CEL|GAL) [CEL] | 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 | Size of the X axis in pixels [200] | 45 | Size of the X axis in pixels [200] |
| 47 | Size of the Y axis in pixels [200] | 46 | Size of the Y axis in pixels [200] |
| 48 | Pixel size (deg/pixel) [0.02] | 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 | In our example, the map will cover a field of 4 x 4 degrees centred on the | 51 | In our example, the map will cover a field of 4 x 4 degrees centred on the |
| 51 | Crab nebula at a pixel scale of 0.02 degrees per pixel. | 52 | Crab nebula at a pixel scale of 0.02 degrees per pixel. |
doc/source/user_manual/getting_started/beyond_stacked.rst
| @@ -6,16 +6,15 @@ Performing a stacked analysis | @@ -6,16 +6,15 @@ Performing a stacked analysis | ||
| 6 | A stacked analysis is a binned analysis where all data from multiple | 6 | A stacked analysis is a binned analysis where all data from multiple |
| 7 | observations are stacked into a single counts cube. | 7 | observations are stacked into a single counts cube. |
| 8 | The event stacking is done using the :ref:`ctbin` tool. | 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 | :ref:`ctbin` will then loop over all observations and collect all events | 11 | :ref:`ctbin` will then loop over all observations and collect all events |
| 13 | into a single counts cube: | 12 | into a single counts cube: |
| 14 | 13 | ||
| 15 | .. code-block:: bash | 14 | .. code-block:: bash |
| 16 | 15 | ||
| 17 | $ ctbin | 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 | First coordinate of image center in degrees (RA or galactic l) (0-360) [83.63] | 18 | 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] | 19 | 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] | 20 | Projection method (AIT|AZP|CAR|MER|MOL|STG|TAN) [CAR] |
| @@ -27,37 +26,37 @@ into a single counts cube: | @@ -27,37 +26,37 @@ into a single counts cube: | ||
| 27 | Start value for first energy bin in TeV [0.1] | 26 | Start value for first energy bin in TeV [0.1] |
| 28 | Stop value for last energy bin in TeV [100.0] | 27 | Stop value for last energy bin in TeV [100.0] |
| 29 | Number of energy bins [20] | 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 | background model that are needed to describe the stacked data. | 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 | cube (i.e. the sum of the effective areas for each observation multiplied | 37 | cube (i.e. the sum of the effective areas for each observation multiplied |
| 39 | by the corresponding livetimes) and an effective point spread function | 38 | by the corresponding livetimes) and an effective point spread function |
| 40 | (i.e. the point spread function of the different observations weighted by | 39 | (i.e. the point spread function of the different observations weighted by |
| 41 | the corresponding exposures). | 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 | :ref:`ctpsfcube` tools: | 42 | :ref:`ctpsfcube` tools: |
| 44 | 43 | ||
| 45 | .. code-block:: bash | 44 | .. code-block:: bash |
| 46 | 45 | ||
| 47 | $ ctexpcube | 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 | Calibration database [prod2] | 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 | Output exposure cube file [expcube.fits] | 51 | Output exposure cube file [expcube.fits] |
| 53 | 52 | ||
| 54 | .. code-block:: bash | 53 | .. code-block:: bash |
| 55 | 54 | ||
| 56 | $ ctpsfcube | 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 | Calibration database [prod2] | 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 | First coordinate of image center in degrees (RA or galactic l) (0-360) [83.63] | 60 | First coordinate of image center in degrees (RA or galactic l) (0-360) [83.63] |
| 62 | Second coordinate of image center in degrees (DEC or galactic b) (-90-90) [22.01] | 61 | Second coordinate of image center in degrees (DEC or galactic b) (-90-90) [22.01] |
| 63 | Projection method (AIT|AZP|CAR|MER|MOL|STG|TAN) [CAR] | 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,42 +67,41 @@ To get both informations we use the :ref:`ctexpcube` and | ||
| 68 | Lower energy limit (TeV) [0.1] | 67 | Lower energy limit (TeV) [0.1] |
| 69 | Upper energy limit (TeV) [100.0] | 68 | Upper energy limit (TeV) [100.0] |
| 70 | Number of energy bins [20] | 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 | pixelisation of the counts cube. | 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 | background cube using the :ref:`ctbkgcube` tool: | 89 | background cube using the :ref:`ctbkgcube` tool: |
| 92 | 90 | ||
| 93 | .. code-block:: bash | 91 | .. code-block:: bash |
| 94 | 92 | ||
| 95 | $ ctbkgcube | 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 | Calibration database [prod2] | 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 | Input model XML file [NONE] $CTOOLS/share/models/crab.xml | 98 | Input model XML file [NONE] $CTOOLS/share/models/crab.xml |
| 101 | Output background cube file [bkgcube.fits] | 99 | Output background cube file [bkgcube.fits] |
| 102 | Output model XML file [NONE] model.xml | 100 | Output model XML file [NONE] model.xml |
| 103 | 101 | ||
| 104 | The usage of :ref:`ctbkgcube` is very similar to that of :ref:`ctexpcube`, | 102 | The usage of :ref:`ctbkgcube` is very similar to that of :ref:`ctexpcube`, |
| 105 | yet it takes the model XML file as an additional input parameter. | 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 | file that is shipped with the ctools. | 105 | file that is shipped with the ctools. |
| 108 | :ref:`ctbkgcube` provides on output the background cube file | 106 | :ref:`ctbkgcube` provides on output the background cube file |
| 109 | ``bkgcube.fits`` and the model XML file ``model.xml`` that can | 107 | ``bkgcube.fits`` and the model XML file ``model.xml`` that can |
| @@ -115,7 +113,7 @@ modelling works: | @@ -115,7 +113,7 @@ modelling works: | ||
| 115 | 113 | ||
| 116 | <?xml version="1.0" encoding="UTF-8" standalone="no"?> | 114 | <?xml version="1.0" encoding="UTF-8" standalone="no"?> |
| 117 | <source_library title="source library"> | 115 | <source_library title="source library"> |
| 118 | - <source name="Crab" type="PointSource" tscalc="0"> | 116 | + <source name="Crab" type="PointSource"> |
| 119 | <spectrum type="PowerLaw"> | 117 | <spectrum type="PowerLaw"> |
| 120 | <parameter name="Prefactor" value="5.7" error="0" scale="1e-16" min="1e-07" max="1000" free="1" /> | 118 | <parameter name="Prefactor" value="5.7" error="0" scale="1e-16" min="1e-07" max="1000" free="1" /> |
| 121 | <parameter name="Index" value="2.48" error="0" scale="-1" min="0" max="5" free="1" /> | 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,88 +155,88 @@ as an appropriate multiplicator to the background cube. | ||
| 157 | Using the same binning for the exposure cube, the background cube and | 155 | Using the same binning for the exposure cube, the background cube and |
| 158 | the counts cube is only a convenience. | 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 | analysis using the :ref:`ctlike` tool: | 159 | analysis using the :ref:`ctlike` tool: |
| 162 | 160 | ||
| 163 | .. code-block:: bash | 161 | .. code-block:: bash |
| 164 | 162 | ||
| 165 | $ ctlike | 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 | :ref:`ctlike` recognises that a counts cube should be analysed and queries | 171 | :ref:`ctlike` recognises that a counts cube should be analysed and queries |
| 174 | for the exposure cube, the PSF cube, and the background cube file names. | 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 | the :ref:`ctpsfcube` and the :ref:`ctbkgcube` tools. | 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 | generated by the :ref:`ctbkgcube` tool. | 176 | generated by the :ref:`ctbkgcube` tool. |
| 179 | 177 | ||
| 180 | The log file of the :ref:`ctlike` run is shown below. | 178 | The log file of the :ref:`ctlike` run is shown below. |
| 181 | Note that the spectral model that is multiplied with the background | 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 | indicating a very small correction to the actual spectrum of the background | 181 | indicating a very small correction to the actual spectrum of the background |
| 184 | cube. | 182 | cube. |
| 185 | Real life situations may of course require larger correction factors. | 183 | Real life situations may of course require larger correction factors. |
| 186 | 184 | ||
| 187 | .. code-block:: xml | 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
| @@ -3,13 +3,14 @@ | @@ -3,13 +3,14 @@ | ||
| 3 | Generating a Test Statistic map | 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 | where the source is located, but in real life situations this may not | 7 | where the source is located, but in real life situations this may not |
| 8 | necessarily be the case. | 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 | One possibility to accomplish this task is to compute the Test Statistic | 10 | One possibility to accomplish this task is to compute the Test Statistic |
| 11 | for a specific source at a grid of trial positions. | 11 | for a specific source at a grid of trial positions. |
| 12 | The :ref:`cttsmap` tool will exactly do that job. | 12 | The :ref:`cttsmap` tool will exactly do that job. |
| 13 | + | ||
| 13 | The Test Statistic is defined as twice the log-likelihood difference | 14 | The Test Statistic is defined as twice the log-likelihood difference |
| 14 | between fitting a source at a given position on top of a model or fitting | 15 | between fitting a source at a given position on top of a model or fitting |
| 15 | no source. | 16 | no source. |
| @@ -18,7 +19,7 @@ the source detection significance in Gaussian sigmas, although the | @@ -18,7 +19,7 @@ the source detection significance in Gaussian sigmas, although the | ||
| 18 | exact relation depends somewhat on the formulation of the statistical | 19 | exact relation depends somewhat on the formulation of the statistical |
| 19 | problem. | 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 | simulated observations of the Crab in unbinned mode. | 23 | simulated observations of the Crab in unbinned mode. |
| 23 | On input we provide a source model XML file and the name of the source | 24 | On input we provide a source model XML file and the name of the source |
| 24 | in the XML file that should be moved on a grid of test positions. | 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,11 +32,11 @@ nominal position of the Crab nebula with a grid spacing of 0.02 degrees. | ||
| 31 | .. code-block:: bash | 32 | .. code-block:: bash |
| 32 | 33 | ||
| 33 | $ cttsmap | 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 | Calibration database [prod2] | 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 | First coordinate of image center in degrees (RA or galactic l) (0-360) [83.63] | 40 | First coordinate of image center in degrees (RA or galactic l) (0-360) [83.63] |
| 40 | Second coordinate of image center in degrees (DEC or galactic b) (-90-90) [22.01] | 41 | Second coordinate of image center in degrees (DEC or galactic b) (-90-90) [22.01] |
| 41 | Projection method (AIT|AZP|CAR|MER|MOL|STG|TAN) [CAR] | 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,14 +44,14 @@ nominal position of the Crab nebula with a grid spacing of 0.02 degrees. | ||
| 43 | Image scale (in degrees/pixel) [0.02] | 44 | Image scale (in degrees/pixel) [0.02] |
| 44 | Size of the X axis in pixels [200] 10 | 45 | Size of the X axis in pixels [200] 10 |
| 45 | Size of the Y axis in pixels [200] 10 | 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 | :ref:`cttsmap` writes the Test Statistic map in the ``tsmap.fits`` file | 49 | :ref:`cttsmap` writes the Test Statistic map in the ``tsmap.fits`` file |
| 49 | that contains one extension for the Test Statistic value and further | 50 | that contains one extension for the Test Statistic value and further |
| 50 | extensions for the spectral parameters that have been fitted for the | 51 | extensions for the spectral parameters that have been fitted for the |
| 51 | source at each position of the grid. | 52 | source at each position of the grid. |
| 52 | The figure below show the Test Statistic map which reaches a maximum | 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 | .. figure:: tsmap-crab.png | 56 | .. figure:: tsmap-crab.png |
| 56 | :height: 400px | 57 | :height: 400px |
doc/source/user_manual/getting_started/binning.rst
0 → 100644
| 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
| 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 | \ No newline at end of file | 52 | \ No newline at end of file |
doc/source/user_manual/getting_started/fitting.rst
0 → 100644
| 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
| 1 | .. _quickstart: | 1 | .. _quickstart: |
| 2 | 2 | ||
| 3 | -A quick ctools tutorial | ||
| 4 | ------------------------ | ||
| 5 | - | ||
| 6 | First steps with ctools | 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 | \ No newline at end of file | 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
doc/source/user_manual/getting_started/response.rst
| @@ -99,7 +99,7 @@ Specifying the response function as input parameters | @@ -99,7 +99,7 @@ Specifying the response function as input parameters | ||
| 99 | ctools that require instrument response functions have two parameters | 99 | ctools that require instrument response functions have two parameters |
| 100 | to specify the calibration database name and the response function name. | 100 | to specify the calibration database name and the response function name. |
| 101 | The following example shows a ``ctobssim`` run using the ``prod2`` | 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 | .. code-block:: bash | 104 | .. code-block:: bash |
| 105 | 105 | ||
| @@ -112,8 +112,9 @@ calibration database and the ``South_50h`` response function: | @@ -112,8 +112,9 @@ calibration database and the ``South_50h`` response function: | ||
| 112 | Lower energy limit (TeV) [0.1] | 112 | Lower energy limit (TeV) [0.1] |
| 113 | Upper energy limit (TeV) [100.0] | 113 | Upper energy limit (TeV) [100.0] |
| 114 | Calibration database [prod2] | 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 | Running the other tools is equivalent. | 119 | Running the other tools is equivalent. |
| 119 | 120 | ||
| @@ -131,7 +132,7 @@ definition file: | @@ -131,7 +132,7 @@ definition file: | ||
| 131 | <observation_list title="observation library"> | 132 | <observation_list title="observation library"> |
| 132 | <observation name="Crab" id="00001" instrument="CTA"> | 133 | <observation name="Crab" id="00001" instrument="CTA"> |
| 133 | <parameter name="EventList" file="events.fits"/> | 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 | </observation> | 136 | </observation> |
| 136 | </observation_list> | 137 | </observation_list> |
| 137 | 138 | ||
| @@ -141,9 +142,9 @@ response name. You can then pass this file directly to, e.g., ``ctlike``: | @@ -141,9 +142,9 @@ response name. You can then pass this file directly to, e.g., ``ctlike``: | ||
| 141 | .. code-block:: bash | 142 | .. code-block:: bash |
| 142 | 143 | ||
| 143 | $ ctlike | 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 | Note that ``ctlike`` does not ask for the calibration database and | 149 | Note that ``ctlike`` does not ask for the calibration database and |
| 149 | response name as it found the relevant information in the XML file. | 150 | response name as it found the relevant information in the XML file. |
| @@ -181,11 +182,11 @@ and response name from within Python: | @@ -181,11 +182,11 @@ and response name from within Python: | ||
| 181 | import gammalib | 182 | import gammalib |
| 182 | obs = gammalib.GCTAObservation() | 183 | obs = gammalib.GCTAObservation() |
| 183 | caldb = gammalib.GCaldb("cta", "prod2") | 184 | caldb = gammalib.GCaldb("cta", "prod2") |
| 184 | - irf = "South_50h" | 185 | + irf = "South_0.5h" |
| 185 | obs.response(irf, caldb) | 186 | obs.response(irf, caldb) |
| 186 | 187 | ||
| 187 | The calibration database is set by creating a ``GCaldb`` object. The | 188 | The calibration database is set by creating a ``GCaldb`` object. The |
| 188 | constructor takes as argument the mission (always ``cta``) and the | 189 | constructor takes as argument the mission (always ``cta``) and the |
| 189 | database name, in our case ``prod2``. The response function is then set | 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 | database object to the ``response`` method. | 192 | database object to the ``response`` method. |
doc/source/user_manual/getting_started/simulating.rst
0 → 100644
| 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
doc/source/user_manual/getting_started/unbinned.rst
0 → 100644
| 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
| 1 | Glossary | 1 | Glossary |
| 2 | ======== | 2 | ======== |
| 3 | 3 | ||
| 4 | -- **GammaLib** (`<http://gammalib.sourceforge.net/>`_) | 4 | +- **GammaLib** (`<http://cta.irap.omp.eu/gammalib/>`_) |
| 5 | 5 | ||
| 6 | A versatile toolbox for scientific analysis of astronomical | 6 | A versatile toolbox for scientific analysis of astronomical |
| 7 | gamma-ray data. | 7 | gamma-ray data. |
doc/source/user_manual/index.rst
doc/source/user_manual/introduction.rst
| @@ -22,6 +22,13 @@ also be specified as arguments separated by a whitespace to the ctool: | @@ -22,6 +22,13 @@ also be specified as arguments separated by a whitespace to the ctool: | ||
| 22 | 22 | ||
| 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 | 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 | ctools includes also a Python module that declares every ctool as a | 32 | ctools includes also a Python module that declares every ctool as a |
| 26 | Python class. The following example illustrates the usage: | 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,7 +54,7 @@ command line or used as Python classes, as illustrated below: | ||
| 47 | 54 | ||
| 48 | In this User Manual you will now learn how to install and use the ctools | 55 | In this User Manual you will now learn how to install and use the ctools |
| 49 | package. | 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 | And you should read the :ref:`develop` section if you would like to | 59 | And you should read the :ref:`develop` section if you would like to |
| 53 | contribute to the ctools developments. | 60 | contribute to the ctools developments. |
doc/source/user_manual/plotting.rst
| 1 | Plotting | 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 | General | 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 | Sky maps | 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 | Spectra and light curves | 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 | .. _DS9: http://ds9.si.edu/ | 55 | .. _DS9: http://ds9.si.edu/ |
| 46 | .. _Aladin: http://aladin.u-strasbg.fr/ | 56 | .. _Aladin: http://aladin.u-strasbg.fr/ |