Commit 28dd804ed486481d3f94f3b398963ebfefae1ba2
1 parent
4c188dcc
Update ctools documentation for release 1.7
Showing
36 changed files
with
762 additions
and
198 deletions
doc/source/_templates/index.html
| ... | ... | @@ -15,20 +15,22 @@ is supported as well. {%endtrans%}</p> |
| 15 | 15 | |
| 16 | 16 | <p>{%trans%} ctools are based on <a href="http://cta.irap.omp.eu/gammalib">GammaLib</a>, |
| 17 | 17 | a versatile toolbox for the scientific analysis of astronomical gamma-ray data. |
| 18 | -Besides CTA, GammaLib supports also the analysis of Fermi/LAT and COMPTEL data, | |
| 19 | -and extensions to support further gamma-ray instruments are planned. An | |
| 20 | -interface to virtual observatory ressources does also exist. By making use of | |
| 21 | -the GammaLib multi-instrument capabilities, ctools supports the joint analysis | |
| 22 | -of CTA, H.E.S.S., MAGIC, VERITAS, Fermi/LAT, INTEGRAL/SPI and COMPTEL data. | |
| 18 | +Besides CTA, GammaLib supports the analysis of H.E.S.S., MAGIC, VERITAS, | |
| 19 | +Fermi/LAT, COMPTEL and INTEGRAL/SPI data. GammaLib supports in particular the | |
| 20 | +combination of data from different instruments in a true joint multi-wavelength | |
| 21 | +analysis that consistently handles the response of each instrument. An interface | |
| 22 | +to virtual observatory ressources does also exist. | |
| 23 | 23 | {%endtrans%}</p> |
| 24 | 24 | |
| 25 | 25 | <p>{%trans%} ctools are developed by a team of enthousiastic gamma-ray |
| 26 | 26 | astronomers with support from engineers. We regularily organise |
| 27 | 27 | <a href=https://cta-redmine.irap.omp.eu/projects/ctools/wiki/Coding_sprints>coding sprints</a> |
| 28 | 28 | where key developers but also newcomers meet to discuss the developments |
| 29 | -and next steps, and advance with the coding of the software. {%endtrans%}</p> | |
| 29 | +and next steps, and advance with the coding of the software. | |
| 30 | +{%endtrans%}</p> | |
| 30 | 31 | |
| 31 | 32 | <p>{%trans%} ctools is free software distributed under the |
| 32 | -<a href="http://www.gnu.org/licenses/gpl.html">GNU GPL license version 3</a> {%endtrans%}</p> | |
| 33 | +<a href="http://www.gnu.org/licenses/gpl.html">GNU GPL license version 3</a> | |
| 34 | +{%endtrans%}</p> | |
| 33 | 35 | |
| 34 | 36 | {% endblock %} | ... | ... |
doc/source/about.rst
| ... | ... | @@ -15,13 +15,12 @@ Creation of shell or Python scripts and pipelines is supported as well. |
| 15 | 15 | |
| 16 | 16 | ctools are based on GammaLib, a versatile toolbox for the scientific |
| 17 | 17 | analysis of astronomical gamma-ray data. |
| 18 | -Besides CTA, GammaLib supports also the analysis of Fermi/LAT, INTEGRAL/SPI | |
| 19 | -and COMPTEL data, and extensions to support further gamma-ray instruments are | |
| 20 | -planned. | |
| 18 | +Besides CTA, GammaLib supports the analysis of H.E.S.S., MAGIC, VERITAS, | |
| 19 | +Fermi/LAT, COMPTEL and INTEGRAL/SPI data. | |
| 20 | +GammaLib supports in particular the combination of data from different instruments | |
| 21 | +in a true joint multi-wavelength analysis that consistently handles the response | |
| 22 | +of each instrument. | |
| 21 | 23 | An interface to virtual observatory ressources does also exist. |
| 22 | -By making use of the GammaLib multi-instrument capabilities, ctools | |
| 23 | -supports the joint analysis of CTA, H.E.S.S., MAGIC, VERITAS, Fermi/LAT, | |
| 24 | -INTEGRAL/SPI and COMPTEL data. | |
| 25 | 24 | |
| 26 | 25 | ctools are developed by a team of enthousiastic gamma-ray astronomers with |
| 27 | 26 | support from engineers. We regularily organise | ... | ... |
doc/source/admin/download.rst
| ... | ... | @@ -3,7 +3,7 @@ |
| 3 | 3 | Download |
| 4 | 4 | ======== |
| 5 | 5 | |
| 6 | -The latest ctools release is ``ctools-1.6.3`` (7 November 2019). | |
| 6 | +The latest ctools release is ``ctools-1.7.0`` (16 July 2020). | |
| 7 | 7 | |
| 8 | 8 | Below a table of ctools releases. Please read the :ref:`sec_release` to |
| 9 | 9 | learn more about new features and corrected bugs in a given release. |
| ... | ... | @@ -23,6 +23,9 @@ learn more about new features and corrected bugs in a given release. |
| 23 | 23 | * - ctools |
| 24 | 24 | - gammalib |
| 25 | 25 | - Mac OS X (10.7+) binary disk image |
| 26 | + * - `1.7.0 <http://cta.irap.omp.eu/ctools/releases/ctools/ctools-1.7.0.tar.gz>`_ | |
| 27 | + - `1.7.0 <http://cta.irap.omp.eu/ctools/releases/gammalib/gammalib-1.7.0.tar.gz>`_ | |
| 28 | + - `ctools-1.7.0-macosx10.7.dmg <http://cta.irap.omp.eu/ctools/releases/ctools/ctools-1.7.0-macosx10.7.dmg>`_ | |
| 26 | 29 | * - `1.6.3 <http://cta.irap.omp.eu/ctools/releases/ctools/ctools-1.6.3.tar.gz>`_ |
| 27 | 30 | - `1.6.3 <http://cta.irap.omp.eu/ctools/releases/gammalib/gammalib-1.6.3.tar.gz>`_ |
| 28 | 31 | - `ctools-1.6.3-macosx10.7.dmg <http://cta.irap.omp.eu/ctools/releases/ctools/ctools-1.6.3-macosx10.7.dmg>`_ | ... | ... |
doc/source/admin/install_devel.rst
| ... | ... | @@ -7,7 +7,7 @@ The current development version of the code can be downloaded as source |
| 7 | 7 | tarballs, Mac OS X binaries, or directly from the `Git <https://git-scm.com/>`_ |
| 8 | 8 | repository. |
| 9 | 9 | |
| 10 | -The current ctools development release is ``ctools-1.7.0.dev``. | |
| 10 | +The current ctools development release is ``ctools-1.8.0.dev``. | |
| 11 | 11 | |
| 12 | 12 | |
| 13 | 13 | Source tarballs |
| ... | ... | @@ -15,8 +15,8 @@ Source tarballs |
| 15 | 15 | |
| 16 | 16 | Download the source tarballs from the following links |
| 17 | 17 | |
| 18 | -- `ctools <http://cta.irap.omp.eu/ctools/releases/ctools/ctools-1.7.0.dev.tar.gz>`_ | |
| 19 | -- `GammaLib <http://cta.irap.omp.eu/ctools/releases/gammalib/gammalib-1.7.0.dev.tar.gz>`_ | |
| 18 | +- `ctools <http://cta.irap.omp.eu/ctools/releases/ctools/ctools-1.8.0.dev.tar.gz>`_ | |
| 19 | +- `GammaLib <http://cta.irap.omp.eu/ctools/releases/gammalib/gammalib-1.8.0.dev.tar.gz>`_ | |
| 20 | 20 | |
| 21 | 21 | and follow the instructions on :ref:`sec_install_source`. |
| 22 | 22 | |
| ... | ... | @@ -26,7 +26,7 @@ Binary packages |
| 26 | 26 | |
| 27 | 27 | Download the installer image from the following link |
| 28 | 28 | |
| 29 | -- `Mac OS X (10.7+) <http://cta.irap.omp.eu/ctools/releases/ctools/ctools-1.7.0.dev-macosx10.7.dmg>`_ | |
| 29 | +- `Mac OS X (10.7+) <http://cta.irap.omp.eu/ctools/releases/ctools/ctools-1.8.0.dev-macosx10.7.dmg>`_ | |
| 30 | 30 | |
| 31 | 31 | and follow the instructions on :ref:`sec_install_binary`. |
| 32 | 32 | |
| ... | ... | @@ -131,7 +131,7 @@ version as follows: |
| 131 | 131 | |
| 132 | 132 | $ conda create -n ctools-devel python=3.6 |
| 133 | 133 | $ source activate ctools-devel |
| 134 | - $ conda install --use-local ctools=1.7.0.dev | |
| 134 | + $ conda install --use-local ctools=1.8.0.dev | |
| 135 | 135 | |
| 136 | 136 | Note that you can choose between Python 2.7, 3.5, 3.6 and 3.7 for your |
| 137 | 137 | conda environment. | ... | ... |
doc/source/admin/release_history/1.7.rst
| 1 | 1 | .. _1.7: |
| 2 | 2 | |
| 3 | -ctools 1.7 release | |
| 4 | -================== | |
| 3 | +ctools 1.7 release (16 July 2020) | |
| 4 | +================================= | |
| 5 | 5 | |
| 6 | 6 | Overview |
| 7 | 7 | -------- |
| ... | ... | @@ -58,8 +58,3 @@ New features |
| 58 | 58 | * [`2961 <https://cta-redmine.irap.omp.eu/issues/2961>`_] - |
| 59 | 59 | Add csscs script for spectral component separation |
| 60 | 60 | |
| 61 | - | |
| 62 | - | |
| 63 | -Clean up | |
| 64 | --------- | |
| 65 | - | ... | ... |
doc/source/admin/release_history/1.8.rst
0 → 100644
| 1 | +.. _1.8: | |
| 2 | + | |
| 3 | +ctools 1.8 release | |
| 4 | +================== | |
| 5 | + | |
| 6 | +Overview | |
| 7 | +-------- | |
| 8 | + | |
| 9 | +ctools 1.8 is a major release that adds significant functionality. | |
| 10 | + | |
| 11 | +In particular, this release provides: | |
| 12 | + | |
| 13 | +* ... | |
| 14 | +* ... | |
| 15 | + | |
| 16 | + | |
| 17 | +Bug fixes | |
| 18 | +--------- | |
| 19 | + | |
| 20 | +* [`2883 <https://cta-redmine.irap.omp.eu/issues/2883>`_] - | |
| 21 | + ... | |
| 22 | + | |
| 23 | + | |
| 24 | +Improvements | |
| 25 | +------------ | |
| 26 | + | |
| 27 | +* [`2883 <https://cta-redmine.irap.omp.eu/issues/2883>`_] - | |
| 28 | + ... | |
| 29 | + | |
| 30 | + | |
| 31 | +New features | |
| 32 | +------------ | |
| 33 | + | |
| 34 | +* [`2883 <https://cta-redmine.irap.omp.eu/issues/2883>`_] - | |
| 35 | + ... | |
| 36 | + | |
| 37 | + | |
| 38 | +Clean up | |
| 39 | +-------- | |
| 40 | + | |
| 41 | +* [`2883 <https://cta-redmine.irap.omp.eu/issues/2883>`_] - | |
| 42 | + ... | ... | ... |
doc/source/users/tutorials/1dc/first_fitting.rst
| ... | ... | @@ -162,7 +162,7 @@ You create the spectrum for ``Src001`` using |
| 162 | 162 | Input model definition XML file [$CTOOLS/share/models/crab.xml] results_stacked.xml |
| 163 | 163 | Source name [Crab] Src001 |
| 164 | 164 | Spectrum generation method (SLICE|NODES|AUTO) [AUTO] |
| 165 | - Binning algorithm (LIN|LOG|FILE) [LOG] | |
| 165 | + Binning algorithm (FILE|LIN|LOG|POW) [LOG] | |
| 166 | 166 | Lower energy limit (TeV) [0.1] |
| 167 | 167 | Upper energy limit (TeV) [100.0] |
| 168 | 168 | Number of energy bins [20] 10 |
| ... | ... | @@ -180,7 +180,7 @@ and for ``Src003`` using |
| 180 | 180 | Input model definition XML file [results_stacked.xml] |
| 181 | 181 | Source name [Src001] Src003 |
| 182 | 182 | Spectrum generation method (SLICE|NODES|AUTO) [AUTO] |
| 183 | - Binning algorithm (LIN|LOG|FILE) [LOG] | |
| 183 | + Binning algorithm (FILE|LIN|LOG|POW) [LOG] | |
| 184 | 184 | Lower energy limit (TeV) [0.1] |
| 185 | 185 | Upper energy limit (TeV) [100.0] |
| 186 | 186 | Number of energy bins [10] | ... | ... |
doc/source/users/tutorials/1dc/first_onoff.rst
| ... | ... | @@ -200,7 +200,7 @@ follows: |
| 200 | 200 | $ csphagen |
| 201 | 201 | Input event list or observation definition XML file [obs.xml] |
| 202 | 202 | Input model definition XML file (if NONE, use point source) [NONE] |
| 203 | - Algorithm for defining energy bins (FILE|LIN|LOG) [LOG] | |
| 203 | + Algorithm for defining energy bins (FILE|LIN|LOG|POW) [LOG] | |
| 204 | 204 | Start value for first energy bin in TeV [0.1] |
| 205 | 205 | Stop value for last energy bin in TeV [100.0] 50.0 |
| 206 | 206 | Number of energy bins [120] 30 |
| ... | ... | @@ -387,7 +387,7 @@ The fit result can be inspected by peeking the log file: |
| 387 | 387 | Input event list or observation definition XML file [obs.xml] |
| 388 | 388 | Input model definition XML file (if NONE, use point source) [NONE] CasA_model.xml |
| 389 | 389 | Source name [Crab] Cassiopeia A |
| 390 | - Algorithm for defining energy bins (FILE|LIN|LOG) [LOG] | |
| 390 | + Algorithm for defining energy bins (FILE|LIN|LOG|POW) [LOG] | |
| 391 | 391 | Start value for first energy bin in TeV [0.1] |
| 392 | 392 | Stop value for last energy bin in TeV [50.0] |
| 393 | 393 | Number of energy bins [30] |
| ... | ... | @@ -467,7 +467,7 @@ and the SED by typing |
| 467 | 467 | Input model definition XML file [$CTOOLS/share/models/crab.xml] CasA_results.xml |
| 468 | 468 | Source name [Crab] Cassiopeia A |
| 469 | 469 | Spectrum generation method (SLICE|NODES|AUTO) [AUTO] |
| 470 | - Binning algorithm (LIN|LOG|FILE) [LOG] | |
| 470 | + Binning algorithm (FILE|LIN|LOG|POW) [LOG] | |
| 471 | 471 | Lower energy limit (TeV) [0.1] |
| 472 | 472 | Upper energy limit (TeV) [100.0] 50.0 |
| 473 | 473 | Number of energy bins [20] 30 | ... | ... |
doc/source/users/tutorials/1dc/first_stacked.rst
| ... | ... | @@ -30,7 +30,7 @@ a counts cube. You do this using the :ref:`ctbin` tool: |
| 30 | 30 | Image scale (in degrees/pixel) [0.02] |
| 31 | 31 | Size of the X axis in pixels [200] 300 |
| 32 | 32 | Size of the Y axis in pixels [200] 300 |
| 33 | - Algorithm for defining energy bins (FILE|LIN|LOG) [LOG] | |
| 33 | + Algorithm for defining energy bins (FILE|LIN|LOG|POW) [LOG] | |
| 34 | 34 | Lower energy limit (TeV) [0.1] |
| 35 | 35 | Upper energy limit (TeV) [100.0] |
| 36 | 36 | Number of energy bins (1-200) [20] 30 |
| ... | ... | @@ -93,7 +93,7 @@ You run :ref:`ctpsfcube` as follows: |
| 93 | 93 | Image scale (in degrees/pixel) [1.0] |
| 94 | 94 | Size of the X axis in pixels [10] |
| 95 | 95 | Size of the Y axis in pixels [10] |
| 96 | - Algorithm for defining energy bins (FILE|LIN|LOG) [LOG] | |
| 96 | + Algorithm for defining energy bins (FILE|LIN|LOG|POW) [LOG] | |
| 97 | 97 | Lower energy limit (TeV) [0.1] |
| 98 | 98 | Upper energy limit (TeV) [100.0] |
| 99 | 99 | Number of energy bins (1-1000) [20] 30 | ... | ... |
doc/source/users/tutorials/hess_dr1/jointfermi.rst
| ... | ... | @@ -77,37 +77,37 @@ The model that will be used in this analysis is shown below: |
| 77 | 77 | |
| 78 | 78 | .. code-block:: xml |
| 79 | 79 | |
| 80 | - <?xml version="1.0" standalone="no"?> | |
| 81 | - <source_library title="source library"> | |
| 82 | - <source type="PointSource" name="Crab"> | |
| 83 | - <spectrum type="LogParabola"> | |
| 84 | - <parameter name="Prefactor" scale="1e-17" value="3.23" min="1e-07" max="10000.0" free="1"/> | |
| 85 | - <parameter name="Index" scale="-1" value="2.47" min="0.5" max="+5.0" free="1"/> | |
| 86 | - <parameter name="Curvature" scale="-1" value="0.24" min="-5.0" max="+5.0" free="1"/> | |
| 87 | - <parameter name="PivotEnergy" scale="1e6" value="1.0" min="0.01" max="1000.0" free="0"/> | |
| 88 | - </spectrum> | |
| 89 | - <spatialModel type="PointSource"> | |
| 90 | - <parameter name="RA" scale="1.0" value="83.633" min="-360" max="360" free="0"/> | |
| 91 | - <parameter name="DEC" scale="1.0" value="22.015" min="-90" max="90" free="0"/> | |
| 92 | - </spatialModel> | |
| 93 | - </source> | |
| 94 | - <source type="DiffuseSource" name="Galactic_diffuse" instrument="LAT"> | |
| 95 | - <spectrum type="Constant"> | |
| 96 | - <parameter name="Normalization" scale="1.0" value="1.0" min="0.1" max="10.0" free="1"/> | |
| 97 | - </spectrum> | |
| 98 | - <spatialModel type="DiffuseMapCube" file="gll_iem_v07.fits"> | |
| 99 | - <parameter name="Normalization" scale="1.0" value="1.0" min="0.1" max="10.0" free="0"/> | |
| 100 | - </spatialModel> | |
| 101 | - </source> | |
| 102 | - <source type="DiffuseSource" name="Isotropic_diffuse" instrument="LAT"> | |
| 103 | - <spectrum type="FileFunction" file="iso_P8R2_SOURCE_V2_v1.txt"> | |
| 104 | - <parameter name="Normalization" scale="1.0" value="1.0" min="0.0" max="1000.0" free="0"/> | |
| 105 | - </spectrum> | |
| 106 | - <spatialModel type="DiffuseIsotropic"> | |
| 107 | - <parameter name="Value" scale="1.0" value="1.0" min="0.0" max="10.0" free="0"/> | |
| 108 | - </spatialModel> | |
| 109 | - </source> | |
| 110 | - </source_library> | |
| 80 | + <?xml version="1.0" standalone="no"?> | |
| 81 | + <source_library title="source library"> | |
| 82 | + <source type="PointSource" name="Crab"> | |
| 83 | + <spectrum type="LogParabola"> | |
| 84 | + <parameter name="Prefactor" scale="1e-17" value="3.23" min="1e-07" max="10000.0" free="1"/> | |
| 85 | + <parameter name="Index" scale="-1" value="2.47" min="0.5" max="+5.0" free="1"/> | |
| 86 | + <parameter name="Curvature" scale="-1" value="0.24" min="-5.0" max="+5.0" free="1"/> | |
| 87 | + <parameter name="PivotEnergy" scale="1e6" value="1.0" min="0.01" max="1000.0" free="0"/> | |
| 88 | + </spectrum> | |
| 89 | + <spatialModel type="PointSource"> | |
| 90 | + <parameter name="RA" scale="1.0" value="83.633" min="-360" max="360" free="0"/> | |
| 91 | + <parameter name="DEC" scale="1.0" value="22.015" min="-90" max="90" free="0"/> | |
| 92 | + </spatialModel> | |
| 93 | + </source> | |
| 94 | + <source type="DiffuseSource" name="Galactic_diffuse" instrument="LAT"> | |
| 95 | + <spectrum type="Constant"> | |
| 96 | + <parameter name="Normalization" scale="1.0" value="1.0" min="0.1" max="10.0" free="1"/> | |
| 97 | + </spectrum> | |
| 98 | + <spatialModel type="DiffuseMapCube" file="gll_iem_v07.fits"> | |
| 99 | + <parameter name="Normalization" scale="1.0" value="1.0" min="0.1" max="10.0" free="0"/> | |
| 100 | + </spatialModel> | |
| 101 | + </source> | |
| 102 | + <source type="DiffuseSource" name="Isotropic_diffuse" instrument="LAT"> | |
| 103 | + <spectrum type="FileFunction" file="iso_P8R2_SOURCE_V2_v1.txt"> | |
| 104 | + <parameter name="Normalization" scale="1.0" value="1.0" min="0.0" max="1000.0" free="0"/> | |
| 105 | + </spectrum> | |
| 106 | + <spatialModel type="DiffuseIsotropic"> | |
| 107 | + <parameter name="Value" scale="1.0" value="1.0" min="0.0" max="10.0" free="0"/> | |
| 108 | + </spatialModel> | |
| 109 | + </source> | |
| 110 | + </source_library> | |
| 111 | 111 | |
| 112 | 112 | The model contains a point source located at the position of the Crab |
| 113 | 113 | with a log-parabola spectrum. It does not have any ``instrument`` attribute, which means that it applies to all instruments. In addition, the model contains two ``DiffuseSource`` |
| ... | ... | @@ -119,10 +119,10 @@ Now you can fit the model to the data using :ref:`ctlike`: |
| 119 | 119 | |
| 120 | 120 | .. code-block:: bash |
| 121 | 121 | |
| 122 | - $ ctlike | |
| 123 | - Input event list, counts cube or observation definition XML file [] joint_observations.xml | |
| 124 | - Input model definition XML file [] joint_models.xml | |
| 125 | - Output model definition XML file [] joint_results.xml | |
| 122 | + $ ctlike | |
| 123 | + Input event list, counts cube or observation definition XML file [] joint_observations.xml | |
| 124 | + Input model definition XML file [] joint_models.xml | |
| 125 | + Output model definition XML file [] joint_results.xml | |
| 126 | 126 | |
| 127 | 127 | The results are: prefactor (for 1 TeV pivot energy) (4.5±0.2)×10−11 |
| 128 | 128 | photons cm−2 s−1 TeV−1, spectral index 2.42±0.04, and curvature |
| ... | ... | @@ -140,28 +140,28 @@ We can now generate the butterfly |
| 140 | 140 | |
| 141 | 141 | .. code-block:: bash |
| 142 | 142 | |
| 143 | - $ ctbutterfly | |
| 144 | - Input event list, counts cube or observation definition XML file [events.fits] joint_observations.xml | |
| 145 | - Source of interest [Crab] | |
| 146 | - Input model definition XML file [$CTOOLS/share/models/crab.xml] joint_results.xml | |
| 147 | - Lower energy limit (TeV) [0.1] 0.05 | |
| 148 | - Upper energy limit (TeV) [100.0] | |
| 149 | - Output ASCII file [butterfly.txt] | |
| 143 | + $ ctbutterfly | |
| 144 | + Input event list, counts cube or observation definition XML file [events.fits] joint_observations.xml | |
| 145 | + Source of interest [Crab] | |
| 146 | + Input model definition XML file [$CTOOLS/share/models/crab.xml] joint_results.xml | |
| 147 | + Lower energy limit (TeV) [0.1] 0.05 | |
| 148 | + Upper energy limit (TeV) [100.0] | |
| 149 | + Output ASCII file [butterfly.txt] | |
| 150 | 150 | |
| 151 | 151 | and spectral energy distribution (SED) |
| 152 | 152 | |
| 153 | 153 | .. code-block:: bash |
| 154 | 154 | |
| 155 | - $ csspec | |
| 156 | - Input event list, counts cube, or observation definition XML file [joint_observations.xml] | |
| 157 | - Input model definition XML file [joint_results.xml] | |
| 158 | - Source name [Crab] | |
| 159 | - Spectrum generation method (SLICE|NODES|AUTO) [AUTO] | |
| 160 | - Algorithm for defining energy bins (FILE|LIN|LOG) [LOG] | |
| 161 | - Start value for first energy bin in TeV [0.1] 0.05 | |
| 162 | - Stop value for last energy bin in TeV [100.0] | |
| 163 | - Number of energy bins (1-200) [10] 15 | |
| 164 | - Output spectrum file [spectrum.fits] | |
| 155 | + $ csspec | |
| 156 | + Input event list, counts cube, or observation definition XML file [joint_observations.xml] | |
| 157 | + Input model definition XML file [joint_results.xml] | |
| 158 | + Source name [Crab] | |
| 159 | + Spectrum generation method (SLICE|NODES|AUTO) [AUTO] | |
| 160 | + Algorithm for defining energy bins (FILE|LIN|LOG|POW) [LOG] | |
| 161 | + Start value for first energy bin in TeV [0.1] 0.05 | |
| 162 | + Stop value for last energy bin in TeV [100.0] | |
| 163 | + Number of energy bins (1-200) [10] 15 | |
| 164 | + Output spectrum file [spectrum.fits] | |
| 165 | 165 | |
| 166 | 166 | Below you can see the resulting butterfly and SED. |
| 167 | 167 | |
| ... | ... | @@ -180,9 +180,8 @@ Below you can see the resulting butterfly and SED. |
| 180 | 180 | |
| 181 | 181 | .. code-block:: bash |
| 182 | 182 | |
| 183 | - $ $CTOOLS/share/examples/python/show_butterfly.py butterfly.txt | |
| 184 | - | |
| 185 | - $ $CTOOLS/share/examples/python/show_spectrum.py spectrum.fits | |
| 183 | + $ $CTOOLS/share/examples/python/show_butterfly.py butterfly.txt | |
| 184 | + $ $CTOOLS/share/examples/python/show_spectrum.py spectrum.fits | |
| 186 | 185 | |
| 187 | 186 | The SED is not shown above 40 TeV because the low counting statistics |
| 188 | 187 | make the results uninteresting. | ... | ... |
doc/source/users/tutorials/howto/comptel/howto_comptel_spectrum.rst
| ... | ... | @@ -18,7 +18,7 @@ script. To do this, type |
| 18 | 18 | Input model definition XML file [$CTOOLS/share/models/crab.xml] models.xml |
| 19 | 19 | Source name [Crab] |
| 20 | 20 | Spectrum generation method (SLICE|NODES|AUTO) [AUTO] |
| 21 | - Algorithm for defining energy bins (FILE|LIN|LOG) [LOG] | |
| 21 | + Algorithm for defining energy bins (FILE|LIN|LOG|POW) [LOG] | |
| 22 | 22 | Start value for first energy bin in TeV [0.1] 0.00000075 |
| 23 | 23 | Stop value for last energy bin in TeV [100.0] 0.00003 |
| 24 | 24 | Number of energy bins (1-200) [20] 4 | ... | ... |
doc/source/users/tutorials/howto/fermi/howto_fermi_spectrum.rst
| ... | ... | @@ -18,7 +18,7 @@ script. To do this, type |
| 18 | 18 | Input model definition XML file [$CTOOLS/share/models/crab.xml] vela_results.xml |
| 19 | 19 | Source name [Crab] Vela |
| 20 | 20 | Spectrum generation method (SLICE|NODES|AUTO) [AUTO] |
| 21 | - Algorithm for defining energy bins (FILE|LIN|LOG) [LOG] | |
| 21 | + Algorithm for defining energy bins (FILE|LIN|LOG|POW) [LOG] | |
| 22 | 22 | Start value for first energy bin in TeV [0.1] 0.0001 |
| 23 | 23 | Stop value for last energy bin in TeV [100.0] 0.1 |
| 24 | 24 | Number of energy bins (1-200) [20] 10 | ... | ... |
doc/source/users/tutorials/howto/howto_combine_instruments.rst
| ... | ... | @@ -51,7 +51,7 @@ Then bin the selected observations into a counts cube |
| 51 | 51 | Image scale (in degrees/pixel) [0.02] |
| 52 | 52 | Size of the X axis in pixels [200] |
| 53 | 53 | Size of the Y axis in pixels [200] |
| 54 | - Algorithm for defining energy bins (FILE|LIN|LOG) [LOG] | |
| 54 | + Algorithm for defining energy bins (FILE|LIN|LOG|POW) [LOG] | |
| 55 | 55 | Lower energy limit (TeV) [0.1] 0.03 |
| 56 | 56 | Upper energy limit (TeV) [100.0] 150.0 |
| 57 | 57 | Number of energy bins (1-200) [20] 40 |
| ... | ... | @@ -78,7 +78,7 @@ Then compute the response cubes as follows |
| 78 | 78 | Image scale (in degrees/pixel) [1.0] |
| 79 | 79 | Size of the X axis in pixels [10] |
| 80 | 80 | Size of the Y axis in pixels [10] |
| 81 | - Algorithm for defining energy bins (FILE|LIN|LOG) [LOG] | |
| 81 | + Algorithm for defining energy bins (FILE|LIN|LOG|POW) [LOG] | |
| 82 | 82 | Lower energy limit (TeV) [0.1] 0.03 |
| 83 | 83 | Upper energy limit (TeV) [100.0] 150.0 |
| 84 | 84 | Number of energy bins (1-200) [20] 40 |
| ... | ... | @@ -194,7 +194,7 @@ combined data set. You do this using the :ref:`csspec` script as follows |
| 194 | 194 | Input model definition XML file [$CTOOLS/share/models/crab.xml] models.xml |
| 195 | 195 | Source name [Crab] Vela |
| 196 | 196 | Spectrum generation method (SLICE|NODES|AUTO) [AUTO] |
| 197 | - Algorithm for defining energy bins (FILE|LIN|LOG) [LOG] | |
| 197 | + Algorithm for defining energy bins (FILE|LIN|LOG|POW) [LOG] | |
| 198 | 198 | Start value for first energy bin in TeV [0.1] 0.0001 |
| 199 | 199 | Stop value for last energy bin in TeV [100.0] 150.0 |
| 200 | 200 | Number of energy bins (1-200) [20] | ... | ... |
doc/source/users/tutorials/howto/howto_xspec.rst
| ... | ... | @@ -49,7 +49,7 @@ Off counts spectrum: |
| 49 | 49 | Calibration database [prod2] |
| 50 | 50 | Instrument response function [South_0.5h] |
| 51 | 51 | Input model definition XML file (if NONE, use point source) [NONE] |
| 52 | - Algorithm for defining energy bins (FILE|LIN|LOG) [LOG] | |
| 52 | + Algorithm for defining energy bins (FILE|LIN|LOG|POW) [LOG] | |
| 53 | 53 | Start value for first energy bin in TeV [0.1] |
| 54 | 54 | Stop value for last energy bin in TeV [100.0] |
| 55 | 55 | Number of energy bins [120] 20 | ... | ... |
doc/source/users/tutorials/quickstart/binning.rst
| ... | ... | @@ -27,7 +27,7 @@ using the :ref:`ctbin` tool as follows: |
| 27 | 27 | Image scale (in degrees/pixel) [0.02] |
| 28 | 28 | Size of the X axis in pixels [200] |
| 29 | 29 | Size of the Y axis in pixels [200] |
| 30 | - Algorithm for defining energy bins (FILE|LIN|LOG) [LOG] | |
| 30 | + Algorithm for defining energy bins (FILE|LIN|LOG|POW) [LOG] | |
| 31 | 31 | Lower energy limit (TeV) [0.1] |
| 32 | 32 | Upper energy limit (TeV) [100.0] |
| 33 | 33 | Number of energy bins (1-200) [20] | ... | ... |
doc/source/users/tutorials/quickstart/energy_dispersion.rst
| ... | ... | @@ -69,7 +69,7 @@ Then you bin as before the selected events into a counts cube using the |
| 69 | 69 | Image scale (in degrees/pixel) [0.02] |
| 70 | 70 | Size of the X axis in pixels [200] |
| 71 | 71 | Size of the Y axis in pixels [200] |
| 72 | - Algorithm for defining energy bins (FILE|LIN|LOG) [LOG] | |
| 72 | + Algorithm for defining energy bins (FILE|LIN|LOG|POW) [LOG] | |
| 73 | 73 | Lower energy limit (TeV) [0.1] |
| 74 | 74 | Upper energy limit (TeV) [100.0] |
| 75 | 75 | Number of energy bins (1-200) [20] |
| ... | ... | @@ -82,22 +82,22 @@ using the :ref:`ctexpcube` tool. You run the tool as follows: |
| 82 | 82 | .. code-block:: bash |
| 83 | 83 | |
| 84 | 84 | $ ctedispcube |
| 85 | - Input event list or observation definition XML file [NONE] selected_events_edisp.fits | |
| 86 | - Calibration database [prod2] | |
| 87 | - Instrument response function [South_0.5h] | |
| 88 | - Input counts cube file to extract energy dispersion cube definition [NONE] | |
| 89 | - Coordinate system (CEL - celestial, GAL - galactic) (CEL|GAL) [CEL] | |
| 90 | - Projection method (AIT|AZP|CAR|GLS|MER|MOL|SFL|SIN|STG|TAN) [CAR] | |
| 91 | - First coordinate of image center in degrees (RA or galactic l) (0-360) [83.63] | |
| 92 | - Second coordinate of image center in degrees (DEC or galactic b) (-90-90) [22.51] | |
| 93 | - Image scale (in degrees/pixel) [1.0] | |
| 94 | - Size of the X axis in pixels [10] | |
| 95 | - Size of the Y axis in pixels [10] | |
| 96 | - Algorithm for defining energy bins (FILE|LIN|LOG) [LOG] | |
| 97 | - Lower energy limit (TeV) [0.1] | |
| 98 | - Upper energy limit (TeV) [100.0] | |
| 99 | - Number of energy bins (1-1000) [20] | |
| 100 | - Output energy dispersion cube file [edispcube.fits] | |
| 85 | + Input event list or observation definition XML file [NONE] selected_events_edisp.fits | |
| 86 | + Calibration database [prod2] | |
| 87 | + Instrument response function [South_0.5h] | |
| 88 | + Input counts cube file to extract energy dispersion cube definition [NONE] | |
| 89 | + Coordinate system (CEL - celestial, GAL - galactic) (CEL|GAL) [CEL] | |
| 90 | + Projection method (AIT|AZP|CAR|GLS|MER|MOL|SFL|SIN|STG|TAN) [CAR] | |
| 91 | + First coordinate of image center in degrees (RA or galactic l) (0-360) [83.63] | |
| 92 | + Second coordinate of image center in degrees (DEC or galactic b) (-90-90) [22.51] | |
| 93 | + Image scale (in degrees/pixel) [1.0] | |
| 94 | + Size of the X axis in pixels [10] | |
| 95 | + Size of the Y axis in pixels [10] | |
| 96 | + Algorithm for defining energy bins (FILE|LIN|LOG|POW) [LOG] | |
| 97 | + Lower energy limit (TeV) [0.1] | |
| 98 | + Upper energy limit (TeV) [100.0] | |
| 99 | + Number of energy bins (1-1000) [20] | |
| 100 | + Output energy dispersion cube file [edispcube.fits] | |
| 101 | 101 | |
| 102 | 102 | Now you are ready to perform a binned maximum likelihood analysis taking the |
| 103 | 103 | energy dispersion into account. You do this by running the :ref:`ctlike` tool | ... | ... |
doc/source/users/tutorials/quickstart/onoff.rst
| ... | ... | @@ -47,7 +47,7 @@ To derive On/Off observations from the ``events_edisp.fits`` event list, type: |
| 47 | 47 | Instrument response function [South_0.5h] |
| 48 | 48 | Input model definition XML file (if NONE, use point source) [NONE] $CTOOLS/share/models/crab.xml |
| 49 | 49 | Source name [Crab] |
| 50 | - Algorithm for defining energy bins (FILE|LIN|LOG) [LOG] | |
| 50 | + Algorithm for defining energy bins (FILE|LIN|LOG|POW) [LOG] | |
| 51 | 51 | Start value for first energy bin in TeV [0.1] |
| 52 | 52 | Stop value for last energy bin in TeV [100.0] |
| 53 | 53 | Number of energy bins [120] 30 | ... | ... |
doc/source/users/tutorials/quickstart/response.rst
| ... | ... | @@ -59,7 +59,7 @@ You run :ref:`ctpsfcube` as follows: |
| 59 | 59 | Image scale (in degrees/pixel) [1.0] |
| 60 | 60 | Size of the X axis in pixels [10] |
| 61 | 61 | Size of the Y axis in pixels [10] |
| 62 | - Algorithm for defining energy bins (FILE|LIN|LOG) [LOG] | |
| 62 | + Algorithm for defining energy bins (FILE|LIN|LOG|POW) [LOG] | |
| 63 | 63 | Lower energy limit (TeV) [0.1] |
| 64 | 64 | Upper energy limit (TeV) [100.0] |
| 65 | 65 | Number of energy bins (1-1000) [20] | ... | ... |
doc/source/users/tutorials/quickstart/spectrum.rst
| ... | ... | @@ -34,7 +34,7 @@ bins between 100 GeV and 100 TeV: |
| 34 | 34 | Input model definition XML file [$CTOOLS/share/models/crab.xml] crab_results.xml |
| 35 | 35 | Source name [Crab] |
| 36 | 36 | Spectrum generation method (SLICE|NODES|AUTO) [AUTO] |
| 37 | - Binning algorithm (LIN|LOG|FILE) [LOG] | |
| 37 | + Binning algorithm (FILE|LIN|LOG|POW) [LOG] | |
| 38 | 38 | Lower energy limit (TeV) [0.1] |
| 39 | 39 | Upper energy limit (TeV) [100.0] |
| 40 | 40 | Number of energy bins [20] 10 | ... | ... |
doc/source/users/user_manual/data.rst
| 1 | 1 | .. _um_data: |
| 2 | 2 | |
| 3 | -The data | |
| 4 | --------- | |
| 3 | +IACT data | |
| 4 | +--------- | |
| 5 | 5 | |
| 6 | -ctools operates on event lists. An event list is a table where each row | |
| 6 | +For Imaging Air Cherenkov Telescopes (IACTs), such as CTA, H.E.S.S., MAGIC or | |
| 7 | +VERITAS, ctools operates on event lists. An event list is a table where each row | |
| 7 | 8 | corresponds to a registered event and each column corresponds to a property |
| 8 | 9 | of the event. Required properties are the event identifier, the reconstructed |
| 9 | 10 | event direction, the reconstructed event energy and the trigger time. Event |
| ... | ... | @@ -36,7 +37,7 @@ of the H.E.S.S. event lists comprising a single GTI is shown below. |
| 36 | 37 | |
| 37 | 38 | Note that times are given in so-called Mission-Elapsed Time (MET) in seconds, |
| 38 | 39 | and that the zero-point of the MET is specified by the ``MJDREFI`` and |
| 39 | -``MJDREFF`` keywords as the integer and fraction part of a Modified Julian Date | |
| 40 | +``MJDREFF`` keywords as the integer and fractional part of a Modified Julian Date | |
| 40 | 41 | (MJD) in the header of the GTI. The same holds also for the trigger times in |
| 41 | 42 | the event list. |
| 42 | 43 | ... | ... |
doc/source/users/user_manual/likelihood.rst
| ... | ... | @@ -266,7 +266,7 @@ where :math:`\ln L(M_s+M_b)` is the log-likelihood value obtained when |
| 266 | 266 | fitting the source and the background together to the data, and |
| 267 | 267 | :math:`\ln L(M_b)` is the log-likelihood value obtained when fitting only |
| 268 | 268 | the background model to the data. |
| 269 | -Under the hypothesis that the model :math:`M_s+M_b` provides a satisfactory fit | |
| 269 | +Under the hypothesis that the model :math:`M_b` provides a satisfactory fit | |
| 270 | 270 | of the data, :math:`\mathrm{TS}` follows a :math:`\chi^2_n` distribution with |
| 271 | 271 | :math:`n` degrees of freedom, where :math:`n` is the number of free parameters |
| 272 | 272 | in the source model component. Therefore | ... | ... |
doc/source/users/user_manual/model_table.png
0 → 100644
20.6 KB
doc/source/users/user_manual/model_table_energies.png
0 → 100644
16.6 KB
doc/source/users/user_manual/model_table_parameters.png
0 → 100644
23.4 KB
doc/source/users/user_manual/model_table_spectra.png
0 → 100644
15.4 KB
doc/source/users/user_manual/models.rst
| ... | ... | @@ -7,8 +7,10 @@ Modelling the data |
| 7 | 7 | :maxdepth: 1 |
| 8 | 8 | |
| 9 | 9 | models_concept |
| 10 | - models_implementation | |
| 11 | - models_spatial_src | |
| 12 | - models_spatial_bgd | |
| 10 | + models_source | |
| 11 | + models_spatial | |
| 13 | 12 | models_spectral |
| 14 | 13 | models_temporal |
| 14 | + models_bgd_iact | |
| 15 | + models_bgd_comptel | |
| 16 | + models_bgd_spi | ... | ... |
doc/source/users/user_manual/models_bgd_comptel.rst
0 → 100644
| 1 | +.. _um_models_bgd_comptel: | |
| 2 | + | |
| 3 | +COMPTEL background models | |
| 4 | +------------------------- | |
| 5 | + | |
| 6 | +The following section presents the model that is available in ctools for the | |
| 7 | +modelling of instrumental background in COMPTEL data. | |
| 8 | + | |
| 9 | +In general, the instrumental background in COMPTEL data for a given energy | |
| 10 | +band :math:`E'` is specified by a so-called DRB cube: | |
| 11 | + | |
| 12 | +.. math:: | |
| 13 | + M(p',E') = {\rm DRB}(\chi, \psi, \bar{\varphi} | E') | |
| 14 | + | |
| 15 | +where :math:`M(p',E')` is given in units of | |
| 16 | +:math:`{\rm events} \,\, {\rm s}^{-1} {\rm MeV}^{-1} {\rm sr}^{-1}`. | |
| 17 | +:math:`(\chi, \psi)` is the photon scatter direction while | |
| 18 | +:math:`\bar{\varphi}` is the Compton scattering angle. | |
| 19 | + | |
| 20 | + | |
| 21 | +DRB cubes | |
| 22 | +^^^^^^^^^ | |
| 23 | + | |
| 24 | +DRB cubes are specified as FITS files in the | |
| 25 | +:ref:`observation definition file <glossary_obsdef>` | |
| 26 | +using the ``DRB`` parameter, e.g. | |
| 27 | + | |
| 28 | +.. code-block:: xml | |
| 29 | + | |
| 30 | + <?xml version="1.0" standalone="no"?> | |
| 31 | + <observation_list title="observation library"> | |
| 32 | + <observation name="Crab" id="100001" instrument="COM"> | |
| 33 | + <parameter name="DRE" file="m50438_dre.fits"/> | |
| 34 | + <parameter name="DRB" file="m34997_drg.fits"/> | |
| 35 | + <parameter name="DRG" file="m34997_drg.fits"/> | |
| 36 | + <parameter name="DRX" file="m32171_drx.fits"/> | |
| 37 | + <parameter name="IAQ" value="ENERG(0.75-1.0)MeV"/> | |
| 38 | + </observation> | |
| 39 | + ... | |
| 40 | + </observation_list> | |
| 41 | + | |
| 42 | +Since DRB files are not provided by HEASARC, the user may specify the DRG | |
| 43 | +file as a first order approximation of the instrumental background distribution | |
| 44 | +in COMPTEL data. | |
| 45 | + | |
| 46 | + | |
| 47 | +DRB fitting | |
| 48 | +^^^^^^^^^^^ | |
| 49 | + | |
| 50 | +The usual way of handling the COMPTEL background model during a maximum likelihood | |
| 51 | +fit is to adjust the normalisation of each :math:`\bar{\varphi}`-layer of the | |
| 52 | +DRB cube to the data. This is accomplished by using the ``DRBFitting`` model, | |
| 53 | +e.g. | |
| 54 | + | |
| 55 | +.. code-block:: xml | |
| 56 | + | |
| 57 | + <source name="Background(0.75-1.0)MeV" type="DRBFitting" instrument="COM" id="100001"> | |
| 58 | + <node> | |
| 59 | + <parameter name="Phibar" scale="1.0" value="1.0" min="0.0" max="50.0" free="0"/> | |
| 60 | + <parameter name="Normalization" scale="1.0" value="0.0" min="0.0" max="1000.0" free="0"/> | |
| 61 | + </node> | |
| 62 | + <node> | |
| 63 | + <parameter name="Phibar" scale="1.0" value="3.0" min="0.0" max="50.0" free="0"/> | |
| 64 | + <parameter name="Normalization" scale="1.0" value="0.0" min="0.0" max="1000.0" free="0"/> | |
| 65 | + </node> | |
| 66 | + <node> | |
| 67 | + <parameter name="Phibar" scale="1.0" value="5.0" min="0.0" max="50.0" free="0"/> | |
| 68 | + <parameter name="Normalization" scale="1.0" value="0.0" min="0.0" max="1000.0" free="0"/> | |
| 69 | + </node> | |
| 70 | + <node> | |
| 71 | + <parameter name="Phibar" scale="1.0" value="7.0" min="0.0" max="50.0" free="0"/> | |
| 72 | + <parameter name="Normalization" scale="1.0" value="0.0" min="0.0" max="1000.0" free="0"/> | |
| 73 | + </node> | |
| 74 | + <node> | |
| 75 | + <parameter name="Phibar" scale="1.0" value="9.0" min="0.0" max="50.0" free="0"/> | |
| 76 | + <parameter name="Normalization" scale="1.0" value="0.0" min="0.0" max="1000.0" free="0"/> | |
| 77 | + </node> | |
| 78 | + <node> | |
| 79 | + <parameter name="Phibar" scale="1.0" value="11.0" min="0.0" max="50.0" free="0"/> | |
| 80 | + <parameter name="Normalization" scale="1.0" value="0.0" min="0.0" max="1000.0" free="0"/> | |
| 81 | + </node> | |
| 82 | + <node> | |
| 83 | + <parameter name="Phibar" scale="1.0" value="13.0" min="0.0" max="50.0" free="0"/> | |
| 84 | + <parameter name="Normalization" scale="1.0" value="0.0" min="0.0" max="1000.0" free="0"/> | |
| 85 | + </node> | |
| 86 | + <node> | |
| 87 | + <parameter name="Phibar" scale="1.0" value="15.0" min="0.0" max="50.0" free="0"/> | |
| 88 | + <parameter name="Normalization" scale="1.0" value="0.0" min="0.0" max="1000.0" free="0"/> | |
| 89 | + </node> | |
| 90 | + <node> | |
| 91 | + <parameter name="Phibar" scale="1.0" value="17.0" min="0.0" max="50.0" free="0"/> | |
| 92 | + <parameter name="Normalization" scale="1.0" value="1.0" min="0.0" max="1000.0" free="1"/> | |
| 93 | + </node> | |
| 94 | + ... | |
| 95 | + </source> | |
| 96 | + | |
| 97 | +.. warning:: | |
| 98 | + Depending on the energy band :math:`E'`, a DRB cube may be empty for a number | |
| 99 | + of :math:`\bar{\varphi}`-layers, which means that the corresponding | |
| 100 | + normalisation cannot be adjusted. To avoid warnings during the :ref:`ctlike` | |
| 101 | + model fit it is recommended to fix the ``Normalization`` parameters of the | |
| 102 | + corresponding layers. In the example above, all layers with :math:`\bar{\varphi}` | |
| 103 | + values below 16 degrees were fixed, the first fitted normalisation | |
| 104 | + is for :math:`\bar{\varphi}=17` degrees. | ... | ... |
doc/source/users/user_manual/models_spatial_bgd.rst renamed to doc/source/users/user_manual/models_bgd_iact.rst
| 1 | -.. _um_models_spatial_bgd: | |
| 1 | +.. _um_models_bgd_iact: | |
| 2 | 2 | |
| 3 | -Spatial background model components | |
| 4 | ------------------------------------ | |
| 3 | +IACT background models | |
| 4 | +---------------------- | |
| 5 | 5 | |
| 6 | -The following sections present the spatial model components that are available | |
| 7 | -in ctools for instrumental background modelling for Imaging Air Cherenkov | |
| 8 | -Telescopes (IACTs) such as H.E.S.S., VERITAS, MAGIC and CTA. | |
| 6 | +The following sections present the model components that are available in | |
| 7 | +ctools for the modelling of instrumental background in data from Imaging Air | |
| 8 | +Cherenkov Telescopes (IACTs) such as CTA, H.E.S.S., VERITAS, and MAGIC. | |
| 9 | + | |
| 10 | +IACT background models are factorised into an optional spatial tag | |
| 11 | +(tags ``<spatialModel>`` or ``<radialModel>``) and a spectral tag | |
| 12 | +(tag ``<spectrum>``) using | |
| 13 | + | |
| 14 | +.. math:: | |
| 15 | + M(p',E') = M_{\rm spatial}(p'|E') \times M_{\rm spectral}(E') | |
| 16 | + | |
| 17 | +where :math:`M(p',E')` is given in units of | |
| 18 | +:math:`{\rm events} \,\, {\rm s}^{-1} {\rm MeV}^{-1} {\rm sr}^{-1}`. | |
| 19 | + | |
| 20 | +For the spectral components, all spectra described in | |
| 21 | +:ref:`um_models_spectral` | |
| 22 | +may be used. | |
| 23 | + | |
| 24 | +.. note:: | |
| 25 | + Spatial directions :math:`p'` and energies :math:`E'` are now the | |
| 26 | + reconstructed quantities, hence no convolution of the model with the | |
| 27 | + :ref:`Instrument Response Functions <um_irf>` is performed. | |
| 9 | 28 | |
| 10 | 29 | |
| 11 | 30 | General IACT background |
| ... | ... | @@ -26,11 +45,38 @@ General IACT background |
| 26 | 45 | </spectrum> |
| 27 | 46 | </source> |
| 28 | 47 | |
| 29 | - .. note:: | |
| 30 | - Please speficy the ``instrument`` label in the XML file that corresponds | |
| 31 | - to the ``instrument`` label of the data. Otherwise the model will not be used | |
| 32 | - for your data. Valid ``instrument`` labels are ``HESS``, ``VERITAS``, | |
| 33 | - ``MAGIC`` and ``CTA``. | |
| 48 | + .. warning:: | |
| 49 | + You need to specify the ``instrument`` label in the ``source`` tag | |
| 50 | + that corresponds to the ``instrument`` label of the observation to which | |
| 51 | + the model should apply. Supported ``instrument`` labels are ``CTA``, | |
| 52 | + ``HESS``, ``VERITAS`` and ``MAGIC``. | |
| 53 | + | |
| 54 | + For example, if you analyse a H.E.S.S. observation you need to specify | |
| 55 | + ``instrument="HESS"`` in the ``source`` tag, while the model type is | |
| 56 | + still ``CTABackground``. So don't get confused! | |
| 57 | + | |
| 58 | + .. code-block:: xml | |
| 59 | + | |
| 60 | + <source name="Background" type="CTABackground" instrument="HESS"> | |
| 61 | + | |
| 62 | + The same logic applies to the radial acceptance, IRF, effective area and | |
| 63 | + cube background models. | |
| 64 | + | |
| 65 | + .. warning:: | |
| 66 | + In case that a background model should be used for the analysis of | |
| 67 | + On/Off data, the corresponding ``OnOff`` ``instrument`` label needs to | |
| 68 | + be selected. Supported ``OnOff`` ``instrument`` labels are ``CTAOnOff``, | |
| 69 | + ``HESSOnOff``, ``VERITASOnOff`` and ``MAGICOnOff``. | |
| 70 | + | |
| 71 | + For example, if you analyse a H.E.S.S. On/Off observation you need to | |
| 72 | + specify | |
| 73 | + | |
| 74 | + .. code-block:: xml | |
| 75 | + | |
| 76 | + <source name="Background" type="CTABackground" instrument="HESSOnOff"> | |
| 77 | + | |
| 78 | + The same logic applies to the radial acceptance, IRF, effective area and | |
| 79 | + cube background models. | |
| 34 | 80 | |
| 35 | 81 | The following sections describe the spatial model components that are |
| 36 | 82 | available. |
| ... | ... | @@ -238,13 +284,15 @@ Radial acceptance background |
| 238 | 284 | |
| 239 | 285 | These models require a ``<radialModel>`` tag as the spatial component and |
| 240 | 286 | accept all spatial model types that take the offset angle :math:`\theta` |
| 241 | - as variable, such as ``Gaussian``, ``Profile`` and ``Polynom``. The use | |
| 242 | - of the radial acceptance model is deprecated, and the ``CTABackground`` | |
| 243 | - model should be used instead. | |
| 287 | + as variable, such as ``Gaussian``, ``Profile`` and ``Polynom``. | |
| 288 | + | |
| 289 | + .. warning:: | |
| 290 | + The use of the radial acceptance model is deprecated, and the | |
| 291 | + ``CTABackground`` model should be used instead. | |
| 244 | 292 | |
| 245 | 293 | |
| 246 | -CTA IRF background | |
| 247 | -^^^^^^^^^^^^^^^^^^ | |
| 294 | +IRF background | |
| 295 | +^^^^^^^^^^^^^^ | |
| 248 | 296 | |
| 249 | 297 | The :ref:`Instrument Response Functions (IRFs) <um_irf>` contain a template |
| 250 | 298 | that predicts the background rate as function of position in the field of view |
| ... | ... | @@ -252,7 +300,10 @@ CTA IRF background |
| 252 | 300 | :math:`{\rm events} \, {\rm s}^{-1} {\rm MeV}^{-1} {\rm sr}^{-1}`. This template |
| 253 | 301 | can be used by specifying a model of type ``CTAIrfBackground``. No spatial component |
| 254 | 302 | will be specified explicitly since the spatial (and spectral) information is |
| 255 | - already contained in the template. The model will be multiplied by a spectral law. | |
| 303 | + already contained in the template. | |
| 304 | + | |
| 305 | + The model will be multiplied by a spectral component to allow for the adjustment | |
| 306 | + of the energy distribution of the background rate. | |
| 256 | 307 | |
| 257 | 308 | .. code-block:: xml |
| 258 | 309 | |
| ... | ... | @@ -274,12 +325,13 @@ CTA IRF background |
| 274 | 325 | </source> |
| 275 | 326 | |
| 276 | 327 | |
| 277 | -CTA effective area background | |
| 278 | -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 328 | +Effective area background | |
| 329 | +^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 279 | 330 | |
| 280 | 331 | Instead of using the background template the effective area for gamma rays can |
| 281 | 332 | also be used to model the instrumental background. Note that in this case the |
| 282 | - effective area has to be scaled to a reasonable background rate. | |
| 333 | + effective area has to be scaled to a reasonable background rate by selecting | |
| 334 | + appropriate values for the spectral model component. | |
| 283 | 335 | |
| 284 | 336 | .. code-block:: xml |
| 285 | 337 | |
| ... | ... | @@ -290,13 +342,18 @@ CTA effective area background |
| 290 | 342 | </source> |
| 291 | 343 | |
| 292 | 344 | |
| 293 | -CTA cube background | |
| 294 | -^^^^^^^^^^^^^^^^^^^ | |
| 345 | +Cube background | |
| 346 | +^^^^^^^^^^^^^^^ | |
| 347 | + | |
| 348 | + For a stacked analysis, the background rates are predicted by a so called | |
| 349 | + background cube. The FITS file name of the background cube is specified | |
| 350 | + either as ctools task parameter, or using the ``BkgCube`` parameter in the | |
| 351 | + the observation definition XML file. | |
| 295 | 352 | |
| 296 | - For a stacked analysis, the background rate is predicted by a so called | |
| 297 | - background cube. The background cube is used by specifying a model of type | |
| 353 | + The background cube model is used by specifying a model of type | |
| 298 | 354 | ``CTACubeBackground``. Similar to the ``CTAIrfBackground`` model, the |
| 299 | - background cube is multplied by a spectral model. | |
| 355 | + background cube is multplied with a spectral model to allow for the adjustment | |
| 356 | + of the energy distribution of the background rate. | |
| 300 | 357 | |
| 301 | 358 | .. code-block:: xml |
| 302 | 359 | ... | ... |
doc/source/users/user_manual/models_bgd_spi.rst
0 → 100644
| 1 | +.. _um_models_bgd_spi: | |
| 2 | + | |
| 3 | +SPI background models | |
| 4 | +--------------------- | |
| 5 | + | |
| 6 | +The instrumental background in INTEGRAL/SPI data is modelled by so-called | |
| 7 | +templates that describe the variation of the background rates with time: | |
| 8 | + | |
| 9 | +.. math:: | |
| 10 | + M(p',E',t') = \sum_{i=0}^{N-1} n_i(d',E',t') \times {\rm TPL}_i(d',E',t') | |
| 11 | + | |
| 12 | +where :math:`M(p',E',t')` is given in units of | |
| 13 | +:math:`{\rm events} \,\, {\rm s}^{-1} {\rm MeV}^{-1} {\rm sr}^{-1}`. | |
| 14 | +:math:`d'` is the SPI detector identifier, | |
| 15 | +:math:`E'` is the measured energy, and | |
| 16 | +:math:`t'` is the time that is linked via the pointing of the SPI | |
| 17 | +telescope to an area of the sky. | |
| 18 | + | |
| 19 | +:math:`{\rm TPL}_i(d',E',t')` is the :math:`i` th out of :math:`N` | |
| 20 | +templates, and :math:`n_i(d',E',t')` is a normalisation factor for this | |
| 21 | +template that may depend on the SPI detector identifier, measured energy and | |
| 22 | +time. | |
| 23 | + | |
| 24 | + | |
| 25 | +Creating a background model | |
| 26 | +^^^^^^^^^^^^^^^^^^^^^^^^^^^ | |
| 27 | + | |
| 28 | +Since the number of background normalisation factors for INTEGRAL/SPI data | |
| 29 | +analysis may be large, it is not recommenced to create a | |
| 30 | +:ref:`model definition XML file <glossary_moddef>` | |
| 31 | +directly, but to use the ``gammalib.GSPIModelDataSpace()`` constructor in | |
| 32 | +a Python script to set up the background model. | |
| 33 | +The ``gammalib.GSPIModelDataSpace()`` constructor takes four arguments: | |
| 34 | + | |
| 35 | +* a SPI observation group | |
| 36 | +* the name you want to give to the model component | |
| 37 | +* a fit method that should be used for the model component | |
| 38 | +* an index that refers to the template that should be used for the model | |
| 39 | + component | |
| 40 | + | |
| 41 | +In the example below it is assumed that three background templates | |
| 42 | +were generated using the | |
| 43 | +`Off-line Scientific Analysis (OSA) <https://www.isdc.unige.ch/integral/analysis#Software>`_ | |
| 44 | +task ``spi_obs_back``, which appends the templates to the SPI observation | |
| 45 | +group ``og_spi.fits``. | |
| 46 | +The first template corresponds to the saturated event rates in the Germanium | |
| 47 | +detectors, the second is a constant rate template, and the third corresponds | |
| 48 | +to a linearly increasing rate with time. | |
| 49 | + | |
| 50 | + .. code-block:: python | |
| 51 | + | |
| 52 | + # Load SPI observation | |
| 53 | + og = gammalib.GSPIObservation('og_spi.fits') | |
| 54 | + | |
| 55 | + # Set background model components | |
| 56 | + bgm_model_1 = gammalib.GSPIModelDataSpace(og, 'GEDSAT', 'orbit,dete', 0) | |
| 57 | + bgm_model_2 = gammalib.GSPIModelDataSpace(og, 'CONST', 'dete', 1) | |
| 58 | + bgm_model_3 = gammalib.GSPIModelDataSpace(og, 'TIME1', 'dete', 2) | |
| 59 | + | |
| 60 | + # Append models | |
| 61 | + models = gammalib.GModels() | |
| 62 | + models.append(bgm_model_1) | |
| 63 | + models.append(bgm_model_2) | |
| 64 | + models.append(bgm_model_3) | |
| 65 | + | |
| 66 | + # Save models | |
| 67 | + models.save('model_spi.xml') | |
| 68 | + | |
| 69 | +For illustration, the typical content of the resulting XML file is as follows: | |
| 70 | + | |
| 71 | + .. code-block:: xml | |
| 72 | + | |
| 73 | + <source name="GEDSAT" type="DataSpace" instrument="SPI" method="orbit,dete" index="0"> | |
| 74 | + <parameter name="GEDSAT D000 O0019" value="1" scale="1" free="1"/> | |
| 75 | + <parameter name="GEDSAT D001 O0019" value="1" scale="1" free="1"/> | |
| 76 | + <parameter name="GEDSAT D002 O0019" value="1" scale="1" free="1"/> | |
| 77 | + <parameter name="GEDSAT D003 O0019" value="1" scale="1" free="1"/> | |
| 78 | + ... | |
| 79 | + <parameter name="GEDSAT D016 O0139" value="1" scale="1" free="1"/> | |
| 80 | + <parameter name="GEDSAT D017 O0139" value="1" scale="1" free="1"/> | |
| 81 | + <parameter name="GEDSAT D018 O0139" value="1" scale="1" free="1"/> | |
| 82 | + </source> | |
| 83 | + <source name="CONST" type="DataSpace" instrument="SPI" method="dete" index="1"> | |
| 84 | + <parameter name="CONST D000" value="1" scale="1" free="1"/> | |
| 85 | + <parameter name="CONST D001" value="1" scale="1" free="1"/> | |
| 86 | + <parameter name="CONST D002" value="1" scale="1" free="1"/> | |
| 87 | + <parameter name="CONST D003" value="1" scale="1" free="1"/> | |
| 88 | + <parameter name="CONST D004" value="1" scale="1" free="1"/> | |
| 89 | + <parameter name="CONST D005" value="1" scale="1" free="1"/> | |
| 90 | + <parameter name="CONST D006" value="1" scale="1" free="1"/> | |
| 91 | + <parameter name="CONST D007" value="1" scale="1" free="1"/> | |
| 92 | + <parameter name="CONST D008" value="1" scale="1" free="1"/> | |
| 93 | + <parameter name="CONST D009" value="1" scale="1" free="1"/> | |
| 94 | + <parameter name="CONST D010" value="1" scale="1" free="1"/> | |
| 95 | + <parameter name="CONST D011" value="1" scale="1" free="1"/> | |
| 96 | + <parameter name="CONST D012" value="1" scale="1" free="1"/> | |
| 97 | + <parameter name="CONST D013" value="1" scale="1" free="1"/> | |
| 98 | + <parameter name="CONST D014" value="1" scale="1" free="1"/> | |
| 99 | + <parameter name="CONST D015" value="1" scale="1" free="1"/> | |
| 100 | + <parameter name="CONST D016" value="1" scale="1" free="1"/> | |
| 101 | + <parameter name="CONST D017" value="1" scale="1" free="1"/> | |
| 102 | + <parameter name="CONST D018" value="1" scale="1" free="1"/> | |
| 103 | + </source> | |
| 104 | + <source name="TIME1" type="DataSpace" instrument="SPI" method="dete" index="2"> | |
| 105 | + <parameter name="TIME1 D000" value="1" scale="1" free="1"/> | |
| 106 | + <parameter name="TIME1 D001" value="1" scale="1" free="1"/> | |
| 107 | + <parameter name="TIME1 D002" value="1" scale="1" free="1"/> | |
| 108 | + <parameter name="TIME1 D003" value="1" scale="1" free="1"/> | |
| 109 | + <parameter name="TIME1 D004" value="1" scale="1" free="1"/> | |
| 110 | + <parameter name="TIME1 D005" value="1" scale="1" free="1"/> | |
| 111 | + <parameter name="TIME1 D006" value="1" scale="1" free="1"/> | |
| 112 | + <parameter name="TIME1 D007" value="1" scale="1" free="1"/> | |
| 113 | + <parameter name="TIME1 D008" value="1" scale="1" free="1"/> | |
| 114 | + <parameter name="TIME1 D009" value="1" scale="1" free="1"/> | |
| 115 | + <parameter name="TIME1 D010" value="1" scale="1" free="1"/> | |
| 116 | + <parameter name="TIME1 D011" value="1" scale="1" free="1"/> | |
| 117 | + <parameter name="TIME1 D012" value="1" scale="1" free="1"/> | |
| 118 | + <parameter name="TIME1 D013" value="1" scale="1" free="1"/> | |
| 119 | + <parameter name="TIME1 D014" value="1" scale="1" free="1"/> | |
| 120 | + <parameter name="TIME1 D015" value="1" scale="1" free="1"/> | |
| 121 | + <parameter name="TIME1 D016" value="1" scale="1" free="1"/> | |
| 122 | + <parameter name="TIME1 D017" value="1" scale="1" free="1"/> | |
| 123 | + <parameter name="TIME1 D018" value="1" scale="1" free="1"/> | |
| 124 | + </source> | |
| 125 | + | |
| 126 | + | |
| 127 | +Fit methods | |
| 128 | +^^^^^^^^^^^ | |
| 129 | + | |
| 130 | +The fit method defines how the indices of the SPI data space are | |
| 131 | +grouped into template normalisation factors. Grouping is allowed in all three | |
| 132 | +data space dimensions: for pointings, detectors and energies. | |
| 133 | + | |
| 134 | +In the example above, individual background normalisation factors for the | |
| 135 | +``GEDSAT`` template were assigned to each orbit and detector, while for the | |
| 136 | +``CONST`` and ``TIME1`` template there is one normalisation factor per | |
| 137 | +detector. Here some further examples: | |
| 138 | + | |
| 139 | +* ``orbit,dete,gedfail``: one normalisation factor per orbit and detector and | |
| 140 | + Germanium detector failure period | |
| 141 | +* ``orbit,evtclass``: one normalisation factor per orbit and event class | |
| 142 | +* ``dete,ebin``: one normalisation factor per detector and energy bin | |
| 143 | +* ``gedanneal``: one normalisation factor per Germanium detector annealing | |
| 144 | + period | |
| 145 | + | |
| 146 | + | |
| 147 | +Pointing grouping | |
| 148 | +~~~~~~~~~~~~~~~~~ | |
| 149 | + | |
| 150 | +point | |
| 151 | +..... | |
| 152 | + | |
| 153 | +Assigns a template normalisation factor for each pointing. | |
| 154 | + | |
| 155 | + | |
| 156 | +orbit | |
| 157 | +..... | |
| 158 | + | |
| 159 | +Assigns a template normalisation factor for each orbit. | |
| 160 | + | |
| 161 | +date | |
| 162 | +.... | |
| 163 | + | |
| 164 | +Assigns a template normalisation factor for each date interval. For example, | |
| 165 | +``date 4 hours`` assigns a normalisation factor for intervals of 4 hours, | |
| 166 | +or ``date 1 month`` assigns a normalisation factor for intervals of one month. | |
| 167 | +The following time units are supported: ``min``, ``hour``, ``day``, ``week``, | |
| 168 | +``month`` or ``year``. | |
| 169 | + | |
| 170 | +gedfail | |
| 171 | +....... | |
| 172 | + | |
| 173 | +Makes sure that there are different template normalisation factors before and | |
| 174 | +after the failure of a Germanium detector. This method can either be used | |
| 175 | +as a fit method, or can be used in combination with ``point``, ``orbit``, | |
| 176 | +``date`` and ``gedanneal``. | |
| 177 | + | |
| 178 | +gedanneal | |
| 179 | +......... | |
| 180 | + | |
| 181 | +Makes sure that there are different template normalisation factors before and | |
| 182 | +after the Germanium detector annealing. This method can either be used | |
| 183 | +as a fit method, or can be used in combination with ``point``, ``orbit``, | |
| 184 | +``date`` and ``gedfail``. | |
| 185 | + | |
| 186 | + | |
| 187 | +Detector grouping | |
| 188 | +~~~~~~~~~~~~~~~~~ | |
| 189 | + | |
| 190 | +dete | |
| 191 | +.... | |
| 192 | + | |
| 193 | +Assigns a template normalisation factor for each detector. | |
| 194 | + | |
| 195 | +evtclass | |
| 196 | +........ | |
| 197 | + | |
| 198 | +Assigns a template normalisation factor for event class. Event classes are | |
| 199 | +either single detector events (SE), double detector events (ME2) or tripple | |
| 200 | +detector events (ME3). | |
| 201 | + | |
| 202 | + | |
| 203 | +Energy grouping | |
| 204 | +~~~~~~~~~~~~~~~ | |
| 205 | + | |
| 206 | +ebin | |
| 207 | +.... | |
| 208 | + | |
| 209 | +Assigns a template normalisation factor for each energy bin. | ... | ... |
doc/source/users/user_manual/models_concept.rst
| ... | ... | @@ -7,7 +7,7 @@ A central element of any data analysis is the modeling of the observed |
| 7 | 7 | event distribution. |
| 8 | 8 | Generally, the measured events can be separated into two distinct classes: |
| 9 | 9 | events being attributed to gamma rays of celestial origin (the "source" |
| 10 | -events) or events being attributed to any other kind of trigger (the | |
| 10 | +events) and events being attributed to any other kind of trigger (the | |
| 11 | 11 | "background" events). |
| 12 | 12 | In the first case, the :ref:`Instrument Response Functions (IRFs) <um_irf>` |
| 13 | 13 | describe how an incident gamma-ray converts into a measured event. | ... | ... |
doc/source/users/user_manual/models_implementation.rst renamed to doc/source/users/user_manual/models_source.rst
| 1 | -.. _um_models_implementation: | |
| 1 | +.. _um_models_source: | |
| 2 | 2 | |
| 3 | -Implementation | |
| 4 | --------------- | |
| 3 | +Source models | |
| 4 | +------------- | |
| 5 | 5 | |
| 6 | 6 | The general model is describe in ctools using a |
| 7 | 7 | :ref:`model definition XML file <glossary_moddef>`. |
| 8 | 8 | Below is a simple example of such a file comprising one source and one |
| 9 | -background model. | |
| 10 | -Each model is factorised into | |
| 11 | -a spectral (tag ``<spectrum>``), | |
| 12 | -a spatial (tags ``<spatialModel>`` or ``<radialModel>``), and | |
| 13 | -a temporal component (tag ``<temporal>``). | |
| 9 | +background model (see :ref:`um_models_bgd` for the implementation of the | |
| 10 | +background models). | |
| 11 | + | |
| 12 | +Each source model is factorised into a spatial (tags ``<spatialModel>``, a | |
| 13 | +spectral (tag ``<spectrum>``), and a temporal component (tag ``<temporal>``) | |
| 14 | +using | |
| 14 | 15 | |
| 15 | 16 | .. math:: |
| 16 | 17 | M(p,E,t) = M_{\rm spatial}(p|E) \times M_{\rm spectral}(E) \times M_{\rm temporal}(t) |
| 17 | 18 | |
| 18 | 19 | where :math:`M(p,E,t)` is given in units of |
| 19 | -:math:`photons \,\, cm^{-2} s^{-1} MeV^{-1} sr^{-1}`. | |
| 20 | +:math:`photons \,\, {\rm cm}^{-1} {\rm s}^{-1} {\rm MeV}^{-1} {\rm sr}^{-1}`. | |
| 20 | 21 | |
| 21 | 22 | The spatial model component describes the energy dependent morphology of the |
| 22 | 23 | source. | ... | ... |
doc/source/users/user_manual/models_spatial_src.rst renamed to doc/source/users/user_manual/models_spatial.rst
| 1 | -.. _um_models_spatial_src: | |
| 1 | +.. _um_models_spatial: | |
| 2 | 2 | |
| 3 | 3 | Spatial source model components |
| 4 | 4 | ------------------------------- |
| ... | ... | @@ -7,9 +7,8 @@ The following sections present the spatial model components that are available |
| 7 | 7 | in ctools for gamma-ray sources. |
| 8 | 8 | |
| 9 | 9 | .. note:: |
| 10 | - Except of the ``DiffuseMapCube`` model, all spatial models are normalized | |
| 11 | - so that when integrated over the sphere the result is unity. For clarify, | |
| 12 | - the spatial normalisation is omitted in the formulae below. | |
| 10 | + Except of the ``DiffuseMapCube`` model, all spatial models are normalised | |
| 11 | + so that when integrated over the sphere the result is unity. | |
| 13 | 12 | |
| 14 | 13 | Point source |
| 15 | 14 | ^^^^^^^^^^^^ |
| ... | ... | @@ -33,8 +32,8 @@ Point source |
| 33 | 32 | * ``RA`` is the Right Ascension (degrees) |
| 34 | 33 | * ``DEC`` is the Declination (degrees) |
| 35 | 34 | |
| 36 | - The ``RA`` and ``DEC`` parameters can be remplaced by ``GLON`` and ``GLAT`` | |
| 37 | - for Galactic coordinates | |
| 35 | + Instead of ``RA`` and ``DEC`` one may use ``GLON`` and ``GLAT`` to give the | |
| 36 | + position in Galactic coordinates | |
| 38 | 37 | |
| 39 | 38 | .. code-block:: xml |
| 40 | 39 | |
| ... | ... | @@ -54,6 +53,14 @@ Point source |
| 54 | 53 | * ``GLAT`` is the Galactic latitude (degrees) |
| 55 | 54 | |
| 56 | 55 | .. note:: |
| 56 | + Galactic coordinates using the ``GLON`` and ``GLAT`` parameters can be | |
| 57 | + specified for all spatial models that require a sky coordinate. Galactic | |
| 58 | + coordinates are transformed internally into celestial coordinates, and | |
| 59 | + in case that a model is written into an XML file, the corresponding | |
| 60 | + parameters will be replaced by the celestial coordinates ``RA`` and | |
| 61 | + ``DEC``. | |
| 62 | + | |
| 63 | + .. note:: | |
| 57 | 64 | For compatibility with the Fermi/LAT ScienceTools the model type |
| 58 | 65 | ``PointSource`` can be replaced by ``SkyDirFunction``. |
| 59 | 66 | |
| ... | ... | @@ -82,10 +89,43 @@ RadialDisk |
| 82 | 89 | |
| 83 | 90 | where |
| 84 | 91 | |
| 85 | - * ``RA`` is the Right Ascension (degrees) | |
| 86 | - * ``DEC`` is the Declination (degrees) | |
| 92 | + * ``RA`` is the Right Ascension of the disk centre (degrees) | |
| 93 | + * ``DEC`` is the Declination of the disk centre (degrees) | |
| 87 | 94 | * ``Radius`` is the disk radius (degrees) |
| 88 | 95 | |
| 96 | +RadialRing | |
| 97 | +~~~~~~~~~~ | |
| 98 | + | |
| 99 | + The ``RadialRing`` model specifies a uniform intensity distribution within | |
| 100 | + a circular ring | |
| 101 | + | |
| 102 | + .. code-block:: xml | |
| 103 | + | |
| 104 | + <source name="Crab" type="ExtendedSource"> | |
| 105 | + <spatialModel type="RadialRing"> | |
| 106 | + <parameter name="RA" scale="1.0" value="83.6331" min="-360" max="360" free="1"/> | |
| 107 | + <parameter name="DEC" scale="1.0" value="22.0145" min="-90" max="90" free="1"/> | |
| 108 | + <parameter name="Radius" scale="1.0" value="0.20" min="0.01" max="10" free="1"/> | |
| 109 | + <parameter name="Width" scale="1.0" value="0.15" min="0.01" max="10" free="1"/> | |
| 110 | + </spatialModel> | |
| 111 | + <spectrum type="..."> | |
| 112 | + ... | |
| 113 | + </spectrum> | |
| 114 | + </source> | |
| 115 | + | |
| 116 | + where | |
| 117 | + | |
| 118 | + * ``RA`` is the Right Ascension of the ring centre (degrees) | |
| 119 | + * ``DEC`` is the Declination of the ring centre (degrees) | |
| 120 | + * ``Radius`` is the inner ring radius (degrees) | |
| 121 | + * ``Width`` is the ring width radius (degrees) | |
| 122 | + | |
| 123 | + .. note:: | |
| 124 | + Specifying the inner ring radius and ring width guarantees that both | |
| 125 | + parameters are well defined. The ring outer radius is given by | |
| 126 | + ``Radius+Width``. | |
| 127 | + | |
| 128 | + | |
| 89 | 129 | RadialGaussian |
| 90 | 130 | ~~~~~~~~~~~~~~ |
| 91 | 131 | |
| ... | ... | @@ -112,8 +152,8 @@ RadialGaussian |
| 112 | 152 | |
| 113 | 153 | where |
| 114 | 154 | |
| 115 | - * ``RA`` is the Right Ascension (degrees) | |
| 116 | - * ``DEC`` is the Declination (degrees) | |
| 155 | + * ``RA`` is the Right Ascension of the Gaussian centre (degrees) | |
| 156 | + * ``DEC`` is the Declination of the Gaussian centre (degrees) | |
| 117 | 157 | * :math:`\sigma` = ``Sigma`` (degrees) |
| 118 | 158 | |
| 119 | 159 | RadialShell |
| ... | ... | @@ -155,15 +195,11 @@ RadialShell |
| 155 | 195 | |
| 156 | 196 | where |
| 157 | 197 | |
| 158 | - * ``RA`` is the Right Ascension (degrees) | |
| 159 | - * ``DEC`` is the Declination (degrees) | |
| 198 | + * ``RA`` is the Right Ascension of the shell centre (degrees) | |
| 199 | + * ``DEC`` is the Declination of the shell centre (degrees) | |
| 160 | 200 | * :math:`\theta_{\rm out}` = ``Radius`` + ``Width`` (degrees) |
| 161 | 201 | * :math:`\theta_{\rm in}` = ``Radius`` (degrees) |
| 162 | 202 | |
| 163 | - .. note:: | |
| 164 | - For all radial source models the ``RA`` and ``DEC`` parameters can be | |
| 165 | - remplaced by ``GLON`` and ``GLAT`` for Galactic coordinates. | |
| 166 | - | |
| 167 | 203 | |
| 168 | 204 | Elliptical source |
| 169 | 205 | ^^^^^^^^^^^^^^^^^ |
| ... | ... | @@ -239,10 +275,6 @@ EllipticalGaussian |
| 239 | 275 | from North |
| 240 | 276 | * :math:`\phi` is the azimuth angle with respect to North. |
| 241 | 277 | |
| 242 | - .. note:: | |
| 243 | - For all elliptical source models the ``RA`` and ``DEC`` parameters can be | |
| 244 | - remplaced by ``GLON`` and ``GLAT`` for Galactic coordinates. | |
| 245 | - | |
| 246 | 278 | |
| 247 | 279 | Diffuse source |
| 248 | 280 | ^^^^^^^^^^^^^^ | ... | ... |
doc/source/users/user_manual/models_spectral.rst
| ... | ... | @@ -86,10 +86,10 @@ Power law |
| 86 | 86 | .. code-block:: xml |
| 87 | 87 | |
| 88 | 88 | <spectrum type="PowerLaw"> |
| 89 | - <parameter scale="1e-07" name="PhotonFlux" min="1e-07" max="1000.0" value="1.0" free="1"/> | |
| 90 | - <parameter scale="1.0" name="Index" min="-5.0" max="+5.0" value="-2.0" free="1"/> | |
| 91 | - <parameter scale="1.0" name="LowerLimit" min="10.0" max="1000000.0" value="100.0" free="0"/> | |
| 92 | - <parameter scale="1.0" name="UpperLimit" min="10.0" max="1000000.0" value="500000.0" free="0"/> | |
| 89 | + <parameter name="PhotonFlux" scale="1e-07" value="1.0" min="1e-07" max="1000.0" free="1"/> | |
| 90 | + <parameter name="Index" scale="1.0" value="-2.0" min="-5.0" max="+5.0" free="1"/> | |
| 91 | + <parameter name="LowerLimit" scale="1.0" value="100.0" min="10.0" max="1000000.0" free="0"/> | |
| 92 | + <parameter name="UpperLimit" scale="1.0" value="500000.0" min="10.0" max="1000000.0" free="0"/> | |
| 93 | 93 | </spectrum> |
| 94 | 94 | |
| 95 | 95 | This spectral model component implements the power law function |
| ... | ... | @@ -202,11 +202,11 @@ Super exponentially cut-off power law |
| 202 | 202 | .. code-block:: xml |
| 203 | 203 | |
| 204 | 204 | <spectrum type="PLSuperExpCutoff"> |
| 205 | - <parameter name="Prefactor" scale="1e-16" value="1.0" min="1e-07" max="1000.0" free="1"/> | |
| 206 | - <parameter name="Index1" scale="-1" value="2.0" min="0.0" max="+5.0" free="1"/> | |
| 207 | - <parameter name="Cutoff" scale="1e6" value="1.0" min="0.01" max="1000.0" free="1"/> | |
| 208 | - <parameter name="Index2" scale="1.0" value="1.5" min="0.1" max="5.0" free="1"/> | |
| 209 | - <parameter name="Scale" scale="1e6" value="1.0" min="0.01" max="1000.0" free="0"/> | |
| 205 | + <parameter name="Prefactor" scale="1e-16" value="1.0" min="1e-07" max="1000.0" free="1"/> | |
| 206 | + <parameter name="Index1" scale="-1" value="2.0" min="0.0" max="+5.0" free="1"/> | |
| 207 | + <parameter name="Cutoff" scale="1e6" value="1.0" min="0.01" max="1000.0" free="1"/> | |
| 208 | + <parameter name="Index2" scale="1.0" value="1.5" min="0.1" max="5.0" free="1"/> | |
| 209 | + <parameter name="Scale" scale="1e6" value="1.0" min="0.01" max="1000.0" free="0"/> | |
| 210 | 210 | </spectrum> |
| 211 | 211 | |
| 212 | 212 | |
| ... | ... | @@ -381,7 +381,7 @@ File function |
| 381 | 381 | .. code-block:: xml |
| 382 | 382 | |
| 383 | 383 | <spectrum type="FileFunction" file="data/filefunction.txt"> |
| 384 | - <parameter scale="1.0" name="Normalization" min="0.0" max="1000.0" value="1.0" free="1"/> | |
| 384 | + <parameter name="Normalization" scale="1.0" value="1.0" min="0.0" max="1000.0" free="1"/> | |
| 385 | 385 | </spectrum> |
| 386 | 386 | |
| 387 | 387 | This spectral model component implements an arbitrary function |
| ... | ... | @@ -444,6 +444,119 @@ Node function |
| 444 | 444 | ordering. |
| 445 | 445 | |
| 446 | 446 | |
| 447 | +Table model | |
| 448 | +^^^^^^^^^^^ | |
| 449 | + | |
| 450 | + An arbitrary spectral model defined on a M-dimensional grid of parameter | |
| 451 | + values. The spectrum is computed using M-dimensional linear interpolation. | |
| 452 | + The model definition is provided by a FITS file that follows the | |
| 453 | + `HEASARC OGIP standard <https://heasarc.gsfc.nasa.gov/docs/heasarc/ofwg/docs/general/ogip_92_009/ogip_92_009.html>`_. | |
| 454 | + | |
| 455 | + The structure of the table model FITS file is shown below. The FITS file | |
| 456 | + contains three binary table extensions after an empty image extension. | |
| 457 | + | |
| 458 | + .. _fig_model_table: | |
| 459 | + | |
| 460 | + .. figure:: model_table.png | |
| 461 | + :align: center | |
| 462 | + :width: 100% | |
| 463 | + | |
| 464 | + *Structure of table model FITS file* | |
| 465 | + | |
| 466 | + The ``PARAMETERS`` extension contains the definition of the model parameters. | |
| 467 | + Each row defines one model parameter. Each model parameter is defined by a | |
| 468 | + unique ``NAME``. The ``METHOD`` column indicates whether the model should be | |
| 469 | + interpolated linarly (value ``0``) or logarithmically (value ``1``). | |
| 470 | + So far only linear interpolation is supported, hence the field is ignored. | |
| 471 | + The ``INITIAL`` column indicates the initial parameter value, if the value in | |
| 472 | + the ``DELTA`` column is negative the parameter will be fixed, otherwise it will | |
| 473 | + be fitted. The ``MINIMUM`` and ``MAXIMUM`` columns indicate the range of values | |
| 474 | + for a given parameter, the ``BOTTOM`` and ``TOP`` columns are ignored. | |
| 475 | + The``NUMBVALS`` column indicates the number of parameter values for | |
| 476 | + which the table model was computed, the ``VALUE`` column indicates the | |
| 477 | + specific parameter values. | |
| 478 | + | |
| 479 | + In the example below there are two parameters named ``Index`` and ``Cutoff``, | |
| 480 | + and spectra were computed for 100 index values and 50 cutoff values, hence | |
| 481 | + a total of 5000 spectra are stored in the table model. | |
| 482 | + | |
| 483 | + .. _fig_model_table_parameters: | |
| 484 | + | |
| 485 | + .. figure:: model_table_parameters.png | |
| 486 | + :align: center | |
| 487 | + :width: 100% | |
| 488 | + | |
| 489 | + *Table model parameters extension* | |
| 490 | + | |
| 491 | + The ``ENERGIES`` extension contains the energy boundaries for the spectra in | |
| 492 | + the usual OGIP format: | |
| 493 | + | |
| 494 | + .. _fig_model_table_energies: | |
| 495 | + | |
| 496 | + .. figure:: model_table_energies.png | |
| 497 | + :align: center | |
| 498 | + :width: 40% | |
| 499 | + | |
| 500 | + *Energy boundaries extension* | |
| 501 | + | |
| 502 | + The ``SPECTRA`` extension contains the spectra of the table model. It consists | |
| 503 | + of two vector columns. The ``PARAMVAL`` column provides the parameter values | |
| 504 | + for which the spectrum was computed. Since there are two parameters in the | |
| 505 | + example the vector column has two entries. The ``INTPSPEC`` column provides | |
| 506 | + the spectrum :math:`\frac{dN(p)}{dE}` for the specific parameters. Since there | |
| 507 | + are 200 energy bins in this example the vector column has 200 entries. | |
| 508 | + | |
| 509 | + .. _fig_model_table_spectra: | |
| 510 | + | |
| 511 | + .. figure:: model_table_spectra.png | |
| 512 | + :align: center | |
| 513 | + :width: 40% | |
| 514 | + | |
| 515 | + *Spectra extension* | |
| 516 | + | |
| 517 | + | |
| 518 | + The model is defined using: | |
| 519 | + | |
| 520 | + .. math:: | |
| 521 | + \frac{dN}{dE} = N_0 \left. \frac{dN(p)}{dE} \right\rvert_{\rm file} | |
| 522 | + | |
| 523 | + where the parameters in the XML definition have the following mappings: | |
| 524 | + | |
| 525 | + * :math:`N_0` = ``Normalization`` | |
| 526 | + * :math:`p` = M model parameters (e.g. ``Index``, ``Cutoff``) | |
| 527 | + | |
| 528 | + The XML format for specifying a table model is: | |
| 529 | + | |
| 530 | + .. code-block:: xml | |
| 531 | + | |
| 532 | + <spectrum type="TableModel" file="model_table.fits"> | |
| 533 | + <parameter name="Normalization" scale="1.0" value="1.0" min="0.0" max="1000.0" free="1"/> | |
| 534 | + </spectrum> | |
| 535 | + | |
| 536 | + .. warning:: | |
| 537 | + If the file name is given without a path it is expected that the file | |
| 538 | + resides in the same directory than the XML file. | |
| 539 | + If the file resides in a different directory, an absolute path name should | |
| 540 | + be specified. | |
| 541 | + Any environment variable present in the path name will be expanded. | |
| 542 | + | |
| 543 | + Note that the default parameters of the table model are provided in the FITS | |
| 544 | + file, according to the | |
| 545 | + `HEASARC OGIP standard <https://heasarc.gsfc.nasa.gov/docs/heasarc/ofwg/docs/general/ogip_92_009/ogip_92_009.html>`_. | |
| 546 | + However, table model parameters may also be specified in the XML file, and | |
| 547 | + these parameters will then overwrite the parameters in the FITS file. For | |
| 548 | + example, for a 2-dimensional table model with an ``Index`` and a ``Cutoff`` | |
| 549 | + parameter, the XML file may look like | |
| 550 | + | |
| 551 | + .. code-block:: xml | |
| 552 | + | |
| 553 | + <spectrum type="TableModel" file="model_table.fits"> | |
| 554 | + <parameter name="Normalization" scale="1e-16" value="5.8" min="1e-07" max="1000" free="1"/> | |
| 555 | + <parameter name="Index" scale="-1" value="2.4" min="1.0" max="3.0" free="1"/> | |
| 556 | + <parameter name="Cutoff" scale="1e6" value="0.89" min="0.1" max="28.2" free="1"/> | |
| 557 | + </spectrum> | |
| 558 | + | |
| 559 | + | |
| 447 | 560 | Composite model |
| 448 | 561 | ^^^^^^^^^^^^^^^ |
| 449 | 562 | |
| ... | ... | @@ -451,14 +564,14 @@ Composite model |
| 451 | 564 | |
| 452 | 565 | <spectrum type="Composite"> |
| 453 | 566 | <spectrum type="PowerLaw" component="SoftComponent"> |
| 454 | - <parameter name="Prefactor" scale="1e-17" value="3" min="1e-07" max="1000.0" free="1"/> | |
| 567 | + <parameter name="Prefactor" scale="1e-17" value="3" min="1e-07" max="1000.0" free="1"/> | |
| 455 | 568 | <parameter name="Index" scale="-1" value="3.5" min="0.0" max="+5.0" free="1"/> |
| 456 | - <parameter name="PivotEnergy" scale="1e6" value="1" min="0.01" max="1000.0" free="0"/> | |
| 569 | + <parameter name="PivotEnergy" scale="1e6" value="1" min="0.01" max="1000.0" free="0"/> | |
| 457 | 570 | </spectrum> |
| 458 | 571 | <spectrum type="PowerLaw" component="HardComponent"> |
| 459 | - <parameter name="Prefactor" scale="1e-17" value="5" min="1e-07" max="1000.0" free="1"/> | |
| 572 | + <parameter name="Prefactor" scale="1e-17" value="5" min="1e-07" max="1000.0" free="1"/> | |
| 460 | 573 | <parameter name="Index" scale="-1" value="2.0" min="0.0" max="+5.0" free="1"/> |
| 461 | - <parameter name="PivotEnergy" scale="1e6" value="1" min="0.01" max="1000.0" free="0"/> | |
| 574 | + <parameter name="PivotEnergy" scale="1e6" value="1" min="0.01" max="1000.0" free="0"/> | |
| 462 | 575 | </spectrum> |
| 463 | 576 | </spectrum> |
| 464 | 577 | |
| ... | ... | @@ -510,7 +623,7 @@ Exponential model |
| 510 | 623 | |
| 511 | 624 | <spectrum type="Exponential"> |
| 512 | 625 | <spectrum type="FileFunction" file="opacity.txt"> |
| 513 | - <parameter scale="-1.0" name="Normalization" min="0.0" max="100.0" value="1.0" free="1"/> | |
| 626 | + <parameter name="Normalization" scale="-1.0" value="1.0" min="0.0" max="100.0" free="1"/> | |
| 514 | 627 | </spectrum> |
| 515 | 628 | </spectrum> |
| 516 | 629 | |
| ... | ... | @@ -518,9 +631,12 @@ Exponential model |
| 518 | 631 | spectral model and computes |
| 519 | 632 | |
| 520 | 633 | .. math:: |
| 521 | - M_{\rm spectral}(E) = \exp \left( M_{\rm spectral}(E) \right) | |
| 634 | + M_{\rm spectral}(E) = \exp \left( \alpha M_{\rm spectral}(E) \right) | |
| 635 | + | |
| 636 | + where | |
| 522 | 637 | |
| 523 | - where :math:`M_{\rm spectral}(E)` is any spectral model component. | |
| 638 | + * :math:`M_{\rm spectral}(E)` is any spectral model component | |
| 639 | + * :math:`\alpha` = ``Normalization`` | |
| 524 | 640 | |
| 525 | 641 | The model can be used to describe a spectrum with EBL absorption based on a |
| 526 | 642 | tabulated model of opacity as a function of photon energy. The corresponding |
| ... | ... | @@ -536,7 +652,7 @@ Exponential model |
| 536 | 652 | </spectrum> |
| 537 | 653 | <spectrum type="Exponential"> |
| 538 | 654 | <spectrum type="FileFunction" file="opacity.txt"> |
| 539 | - <parameter scale="-1.0" name="Normalization" min="0.0" max="100.0" value="1.0" free="1"/> | |
| 655 | + <parameter name="Normalization" scale="-1.0" value="1.0" min="0.0" max="100.0" free="1"/> | |
| 540 | 656 | </spectrum> |
| 541 | 657 | </spectrum> |
| 542 | 658 | </spectrum> | ... | ... |
doc/source/users/user_manual/models_temporal.rst
| ... | ... | @@ -7,7 +7,7 @@ The following sections present the temporal model components that are available |
| 7 | 7 | in ctools. |
| 8 | 8 | |
| 9 | 9 | .. warning:: |
| 10 | - Recall that the model is factorised according to | |
| 10 | + Recall that the source model is factorised according to | |
| 11 | 11 | |
| 12 | 12 | .. math:: |
| 13 | 13 | M(p,E,t) = M_{\rm spatial}(p|E) \times M_{\rm spectral}(E) \times M_{\rm temporal}(t) | ... | ... |
doc/source/users/user_manual/overview.jpg
doc/source/users/user_manual/overview.rst
| ... | ... | @@ -11,7 +11,7 @@ executables, and tools starting with the letters ``cs`` are implemented as |
| 11 | 11 | Python scripts. |
| 12 | 12 | |
| 13 | 13 | .. figure:: overview.jpg |
| 14 | - :width: 60% | |
| 14 | + :width: 65% | |
| 15 | 15 | :align: center |
| 16 | 16 | |
| 17 | 17 | The scripts :ref:`csiactdata`, :ref:`csiactobs`, :ref:`csfindobs` and |
| ... | ... | @@ -46,6 +46,7 @@ tools. |
| 46 | 46 | :ref:`csbkgmodel` prepares a standard background model for the analysis of |
| 47 | 47 | IACT data that was validated on H.E.S.S. data. :ref:`csmodelinfo` |
| 48 | 48 | inspects any given :ref:`model definition file <glossary_moddef>`, |
| 49 | +:ref:`csmodelselect` selects sources from a :ref:`model definition file <glossary_moddef>`, | |
| 49 | 50 | :ref:`csmodelmerge` merges several :ref:`model definition files <glossary_moddef>` |
| 50 | 51 | into a single one, and :ref:`csmodelsois` extracts sources of interest from a |
| 51 | 52 | :ref:`model definition file <glossary_moddef>` and replaces the remaining sources |
| ... | ... | @@ -54,6 +55,7 @@ by a diffuse map cube. |
| 54 | 55 | :ref:`ctskymap` generates sky maps from the data and :ref:`cssrcdetect` |
| 55 | 56 | detects sources in the sky map and writes them into a |
| 56 | 57 | :ref:`model definition file <glossary_moddef>`. |
| 58 | +:ref:`csscs` spatially separates source components based on their spectra. | |
| 57 | 59 | |
| 58 | 60 | :ref:`csspec` generates a spectrum and :ref:`ctbutterfly` computes a butterfly |
| 59 | 61 | diagram for a given gamma-ray source. | ... | ... |