From 28dd804ed486481d3f94f3b398963ebfefae1ba2 Mon Sep 17 00:00:00 2001 From: Jürgen Knödlseder Date: Thu, 16 Jul 2020 12:54:38 +0200 Subject: [PATCH] Update ctools documentation for release 1.7 --- doc/source/_templates/index.html | 16 +++++++++------- doc/source/about.rst | 11 +++++------ doc/source/admin/download.rst | 5 ++++- doc/source/admin/install_devel.rst | 10 +++++----- doc/source/admin/release_history/1.7.rst | 9 ++------- doc/source/admin/release_history/1.8.rst | 42 ++++++++++++++++++++++++++++++++++++++++++ doc/source/users/tutorials/1dc/first_fitting.rst | 4 ++-- doc/source/users/tutorials/1dc/first_onoff.rst | 6 +++--- doc/source/users/tutorials/1dc/first_stacked.rst | 4 ++-- doc/source/users/tutorials/hess_dr1/jointfermi.rst | 109 ++++++++++++++++++++++++++++++++++++++++++++++++++++++------------------------------------------------------- doc/source/users/tutorials/howto/comptel/howto_comptel_spectrum.rst | 2 +- doc/source/users/tutorials/howto/fermi/howto_fermi_spectrum.rst | 2 +- doc/source/users/tutorials/howto/howto_combine_instruments.rst | 6 +++--- doc/source/users/tutorials/howto/howto_xspec.rst | 2 +- doc/source/users/tutorials/quickstart/binning.rst | 2 +- doc/source/users/tutorials/quickstart/energy_dispersion.rst | 34 +++++++++++++++++----------------- doc/source/users/tutorials/quickstart/onoff.rst | 2 +- doc/source/users/tutorials/quickstart/response.rst | 2 +- doc/source/users/tutorials/quickstart/spectrum.rst | 2 +- doc/source/users/user_manual/data.rst | 9 +++++---- doc/source/users/user_manual/likelihood.rst | 2 +- doc/source/users/user_manual/model_table.png | Bin 0 -> 21123 bytes doc/source/users/user_manual/model_table_energies.png | Bin 0 -> 17044 bytes doc/source/users/user_manual/model_table_parameters.png | Bin 0 -> 23950 bytes doc/source/users/user_manual/model_table_spectra.png | Bin 0 -> 15723 bytes doc/source/users/user_manual/models.rst | 8 +++++--- doc/source/users/user_manual/models_bgd_comptel.rst | 104 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/source/users/user_manual/models_bgd_iact.rst | 364 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/source/users/user_manual/models_bgd_spi.rst | 209 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/source/users/user_manual/models_concept.rst | 2 +- doc/source/users/user_manual/models_implementation.rst | 172 ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- doc/source/users/user_manual/models_source.rst | 173 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/source/users/user_manual/models_spatial.rst | 439 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/source/users/user_manual/models_spatial_bgd.rst | 307 ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- doc/source/users/user_manual/models_spatial_src.rst | 407 ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- doc/source/users/user_manual/models_spectral.rst | 152 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++------------------ doc/source/users/user_manual/models_temporal.rst | 2 +- doc/source/users/user_manual/overview.jpg | Bin 642596 -> 0 bytes doc/source/users/user_manual/overview.rst | 4 +++- 39 files changed, 1594 insertions(+), 1030 deletions(-) create mode 100644 doc/source/admin/release_history/1.8.rst create mode 100644 doc/source/users/user_manual/model_table.png create mode 100644 doc/source/users/user_manual/model_table_energies.png create mode 100644 doc/source/users/user_manual/model_table_parameters.png create mode 100644 doc/source/users/user_manual/model_table_spectra.png create mode 100644 doc/source/users/user_manual/models_bgd_comptel.rst create mode 100644 doc/source/users/user_manual/models_bgd_iact.rst create mode 100644 doc/source/users/user_manual/models_bgd_spi.rst delete mode 100644 doc/source/users/user_manual/models_implementation.rst create mode 100644 doc/source/users/user_manual/models_source.rst create mode 100644 doc/source/users/user_manual/models_spatial.rst delete mode 100644 doc/source/users/user_manual/models_spatial_bgd.rst delete mode 100644 doc/source/users/user_manual/models_spatial_src.rst diff --git a/doc/source/_templates/index.html b/doc/source/_templates/index.html index 5c8cb62..1ee65ce 100755 --- a/doc/source/_templates/index.html +++ b/doc/source/_templates/index.html @@ -15,20 +15,22 @@ is supported as well. {%endtrans%}

{%trans%} ctools are based on GammaLib, a versatile toolbox for the scientific analysis of astronomical gamma-ray data. -Besides CTA, GammaLib supports also the analysis of Fermi/LAT and COMPTEL data, -and extensions to support further gamma-ray instruments are planned. An -interface to virtual observatory ressources does also exist. By making use of -the GammaLib multi-instrument capabilities, ctools supports the joint analysis -of CTA, H.E.S.S., MAGIC, VERITAS, Fermi/LAT, INTEGRAL/SPI and COMPTEL data. +Besides CTA, GammaLib supports the analysis of H.E.S.S., MAGIC, VERITAS, +Fermi/LAT, COMPTEL and INTEGRAL/SPI data. GammaLib supports in particular the +combination of data from different instruments in a true joint multi-wavelength +analysis that consistently handles the response of each instrument. An interface +to virtual observatory ressources does also exist. {%endtrans%}

{%trans%} ctools are developed by a team of enthousiastic gamma-ray astronomers with support from engineers. We regularily organise coding sprints where key developers but also newcomers meet to discuss the developments -and next steps, and advance with the coding of the software. {%endtrans%}

+and next steps, and advance with the coding of the software. +{%endtrans%}

{%trans%} ctools is free software distributed under the -GNU GPL license version 3 {%endtrans%}

+GNU GPL license version 3 +{%endtrans%}

{% endblock %} diff --git a/doc/source/about.rst b/doc/source/about.rst index dde2b0a..d67ecd3 100755 --- a/doc/source/about.rst +++ b/doc/source/about.rst @@ -15,13 +15,12 @@ Creation of shell or Python scripts and pipelines is supported as well. ctools are based on GammaLib, a versatile toolbox for the scientific analysis of astronomical gamma-ray data. -Besides CTA, GammaLib supports also the analysis of Fermi/LAT, INTEGRAL/SPI -and COMPTEL data, and extensions to support further gamma-ray instruments are -planned. +Besides CTA, GammaLib supports the analysis of H.E.S.S., MAGIC, VERITAS, +Fermi/LAT, COMPTEL and INTEGRAL/SPI data. +GammaLib supports in particular the combination of data from different instruments +in a true joint multi-wavelength analysis that consistently handles the response +of each instrument. An interface to virtual observatory ressources does also exist. -By making use of the GammaLib multi-instrument capabilities, ctools -supports the joint analysis of CTA, H.E.S.S., MAGIC, VERITAS, Fermi/LAT, -INTEGRAL/SPI and COMPTEL data. ctools are developed by a team of enthousiastic gamma-ray astronomers with support from engineers. We regularily organise diff --git a/doc/source/admin/download.rst b/doc/source/admin/download.rst index 1b1f1fd..b7b370a 100755 --- a/doc/source/admin/download.rst +++ b/doc/source/admin/download.rst @@ -3,7 +3,7 @@ Download ======== -The latest ctools release is ``ctools-1.6.3`` (7 November 2019). +The latest ctools release is ``ctools-1.7.0`` (16 July 2020). Below a table of ctools releases. Please read the :ref:`sec_release` to 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. * - ctools - gammalib - Mac OS X (10.7+) binary disk image + * - `1.7.0 `_ + - `1.7.0 `_ + - `ctools-1.7.0-macosx10.7.dmg `_ * - `1.6.3 `_ - `1.6.3 `_ - `ctools-1.6.3-macosx10.7.dmg `_ diff --git a/doc/source/admin/install_devel.rst b/doc/source/admin/install_devel.rst index 66cf7d5..6645f80 100644 --- a/doc/source/admin/install_devel.rst +++ b/doc/source/admin/install_devel.rst @@ -7,7 +7,7 @@ The current development version of the code can be downloaded as source tarballs, Mac OS X binaries, or directly from the `Git `_ repository. -The current ctools development release is ``ctools-1.7.0.dev``. +The current ctools development release is ``ctools-1.8.0.dev``. Source tarballs @@ -15,8 +15,8 @@ Source tarballs Download the source tarballs from the following links -- `ctools `_ -- `GammaLib `_ +- `ctools `_ +- `GammaLib `_ and follow the instructions on :ref:`sec_install_source`. @@ -26,7 +26,7 @@ Binary packages Download the installer image from the following link -- `Mac OS X (10.7+) `_ +- `Mac OS X (10.7+) `_ and follow the instructions on :ref:`sec_install_binary`. @@ -131,7 +131,7 @@ version as follows: $ conda create -n ctools-devel python=3.6 $ source activate ctools-devel - $ conda install --use-local ctools=1.7.0.dev + $ conda install --use-local ctools=1.8.0.dev Note that you can choose between Python 2.7, 3.5, 3.6 and 3.7 for your conda environment. diff --git a/doc/source/admin/release_history/1.7.rst b/doc/source/admin/release_history/1.7.rst index 824b26c..6ec8810 100644 --- a/doc/source/admin/release_history/1.7.rst +++ b/doc/source/admin/release_history/1.7.rst @@ -1,7 +1,7 @@ .. _1.7: -ctools 1.7 release -================== +ctools 1.7 release (16 July 2020) +================================= Overview -------- @@ -58,8 +58,3 @@ New features * [`2961 `_] - Add csscs script for spectral component separation - - -Clean up --------- - diff --git a/doc/source/admin/release_history/1.8.rst b/doc/source/admin/release_history/1.8.rst new file mode 100644 index 0000000..c98fbf1 --- /dev/null +++ b/doc/source/admin/release_history/1.8.rst @@ -0,0 +1,42 @@ +.. _1.8: + +ctools 1.8 release +================== + +Overview +-------- + +ctools 1.8 is a major release that adds significant functionality. + +In particular, this release provides: + +* ... +* ... + + +Bug fixes +--------- + +* [`2883 `_] - + ... + + +Improvements +------------ + +* [`2883 `_] - + ... + + +New features +------------ + +* [`2883 `_] - + ... + + +Clean up +-------- + +* [`2883 `_] - + ... diff --git a/doc/source/users/tutorials/1dc/first_fitting.rst b/doc/source/users/tutorials/1dc/first_fitting.rst index 49c49b4..2f39e7e 100755 --- a/doc/source/users/tutorials/1dc/first_fitting.rst +++ b/doc/source/users/tutorials/1dc/first_fitting.rst @@ -162,7 +162,7 @@ You create the spectrum for ``Src001`` using Input model definition XML file [$CTOOLS/share/models/crab.xml] results_stacked.xml Source name [Crab] Src001 Spectrum generation method (SLICE|NODES|AUTO) [AUTO] - Binning algorithm (LIN|LOG|FILE) [LOG] + Binning algorithm (FILE|LIN|LOG|POW) [LOG] Lower energy limit (TeV) [0.1] Upper energy limit (TeV) [100.0] Number of energy bins [20] 10 @@ -180,7 +180,7 @@ and for ``Src003`` using Input model definition XML file [results_stacked.xml] Source name [Src001] Src003 Spectrum generation method (SLICE|NODES|AUTO) [AUTO] - Binning algorithm (LIN|LOG|FILE) [LOG] + Binning algorithm (FILE|LIN|LOG|POW) [LOG] Lower energy limit (TeV) [0.1] Upper energy limit (TeV) [100.0] Number of energy bins [10] diff --git a/doc/source/users/tutorials/1dc/first_onoff.rst b/doc/source/users/tutorials/1dc/first_onoff.rst index 1886e95..c2f391d 100644 --- a/doc/source/users/tutorials/1dc/first_onoff.rst +++ b/doc/source/users/tutorials/1dc/first_onoff.rst @@ -200,7 +200,7 @@ follows: $ csphagen Input event list or observation definition XML file [obs.xml] Input model definition XML file (if NONE, use point source) [NONE] - Algorithm for defining energy bins (FILE|LIN|LOG) [LOG] + Algorithm for defining energy bins (FILE|LIN|LOG|POW) [LOG] Start value for first energy bin in TeV [0.1] Stop value for last energy bin in TeV [100.0] 50.0 Number of energy bins [120] 30 @@ -387,7 +387,7 @@ The fit result can be inspected by peeking the log file: Input event list or observation definition XML file [obs.xml] Input model definition XML file (if NONE, use point source) [NONE] CasA_model.xml Source name [Crab] Cassiopeia A - Algorithm for defining energy bins (FILE|LIN|LOG) [LOG] + Algorithm for defining energy bins (FILE|LIN|LOG|POW) [LOG] Start value for first energy bin in TeV [0.1] Stop value for last energy bin in TeV [50.0] Number of energy bins [30] @@ -467,7 +467,7 @@ and the SED by typing Input model definition XML file [$CTOOLS/share/models/crab.xml] CasA_results.xml Source name [Crab] Cassiopeia A Spectrum generation method (SLICE|NODES|AUTO) [AUTO] - Binning algorithm (LIN|LOG|FILE) [LOG] + Binning algorithm (FILE|LIN|LOG|POW) [LOG] Lower energy limit (TeV) [0.1] Upper energy limit (TeV) [100.0] 50.0 Number of energy bins [20] 30 diff --git a/doc/source/users/tutorials/1dc/first_stacked.rst b/doc/source/users/tutorials/1dc/first_stacked.rst index a7ffab6..b82a706 100755 --- a/doc/source/users/tutorials/1dc/first_stacked.rst +++ b/doc/source/users/tutorials/1dc/first_stacked.rst @@ -30,7 +30,7 @@ a counts cube. You do this using the :ref:`ctbin` tool: Image scale (in degrees/pixel) [0.02] Size of the X axis in pixels [200] 300 Size of the Y axis in pixels [200] 300 - Algorithm for defining energy bins (FILE|LIN|LOG) [LOG] + Algorithm for defining energy bins (FILE|LIN|LOG|POW) [LOG] Lower energy limit (TeV) [0.1] Upper energy limit (TeV) [100.0] Number of energy bins (1-200) [20] 30 @@ -93,7 +93,7 @@ You run :ref:`ctpsfcube` as follows: Image scale (in degrees/pixel) [1.0] Size of the X axis in pixels [10] Size of the Y axis in pixels [10] - Algorithm for defining energy bins (FILE|LIN|LOG) [LOG] + Algorithm for defining energy bins (FILE|LIN|LOG|POW) [LOG] Lower energy limit (TeV) [0.1] Upper energy limit (TeV) [100.0] Number of energy bins (1-1000) [20] 30 diff --git a/doc/source/users/tutorials/hess_dr1/jointfermi.rst b/doc/source/users/tutorials/hess_dr1/jointfermi.rst index 8d3421b..2a093c8 100644 --- a/doc/source/users/tutorials/hess_dr1/jointfermi.rst +++ b/doc/source/users/tutorials/hess_dr1/jointfermi.rst @@ -77,37 +77,37 @@ The model that will be used in this analysis is shown below: .. code-block:: xml - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + The model contains a point source located at the position of the Crab 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`: .. code-block:: bash - $ ctlike - Input event list, counts cube or observation definition XML file [] joint_observations.xml - Input model definition XML file [] joint_models.xml - Output model definition XML file [] joint_results.xml + $ ctlike + Input event list, counts cube or observation definition XML file [] joint_observations.xml + Input model definition XML file [] joint_models.xml + Output model definition XML file [] joint_results.xml The results are: prefactor (for 1 TeV pivot energy) (4.5±0.2)×10−11 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 .. code-block:: bash - $ ctbutterfly - Input event list, counts cube or observation definition XML file [events.fits] joint_observations.xml - Source of interest [Crab] - Input model definition XML file [$CTOOLS/share/models/crab.xml] joint_results.xml - Lower energy limit (TeV) [0.1] 0.05 - Upper energy limit (TeV) [100.0] - Output ASCII file [butterfly.txt] + $ ctbutterfly + Input event list, counts cube or observation definition XML file [events.fits] joint_observations.xml + Source of interest [Crab] + Input model definition XML file [$CTOOLS/share/models/crab.xml] joint_results.xml + Lower energy limit (TeV) [0.1] 0.05 + Upper energy limit (TeV) [100.0] + Output ASCII file [butterfly.txt] and spectral energy distribution (SED) .. code-block:: bash - $ csspec - Input event list, counts cube, or observation definition XML file [joint_observations.xml] - Input model definition XML file [joint_results.xml] - Source name [Crab] - Spectrum generation method (SLICE|NODES|AUTO) [AUTO] - Algorithm for defining energy bins (FILE|LIN|LOG) [LOG] - Start value for first energy bin in TeV [0.1] 0.05 - Stop value for last energy bin in TeV [100.0] - Number of energy bins (1-200) [10] 15 - Output spectrum file [spectrum.fits] + $ csspec + Input event list, counts cube, or observation definition XML file [joint_observations.xml] + Input model definition XML file [joint_results.xml] + Source name [Crab] + Spectrum generation method (SLICE|NODES|AUTO) [AUTO] + Algorithm for defining energy bins (FILE|LIN|LOG|POW) [LOG] + Start value for first energy bin in TeV [0.1] 0.05 + Stop value for last energy bin in TeV [100.0] + Number of energy bins (1-200) [10] 15 + Output spectrum file [spectrum.fits] Below you can see the resulting butterfly and SED. @@ -180,9 +180,8 @@ Below you can see the resulting butterfly and SED. .. code-block:: bash - $ $CTOOLS/share/examples/python/show_butterfly.py butterfly.txt - - $ $CTOOLS/share/examples/python/show_spectrum.py spectrum.fits + $ $CTOOLS/share/examples/python/show_butterfly.py butterfly.txt + $ $CTOOLS/share/examples/python/show_spectrum.py spectrum.fits The SED is not shown above 40 TeV because the low counting statistics make the results uninteresting. diff --git a/doc/source/users/tutorials/howto/comptel/howto_comptel_spectrum.rst b/doc/source/users/tutorials/howto/comptel/howto_comptel_spectrum.rst index c3ecb2f..e417d12 100755 --- a/doc/source/users/tutorials/howto/comptel/howto_comptel_spectrum.rst +++ b/doc/source/users/tutorials/howto/comptel/howto_comptel_spectrum.rst @@ -18,7 +18,7 @@ script. To do this, type Input model definition XML file [$CTOOLS/share/models/crab.xml] models.xml Source name [Crab] Spectrum generation method (SLICE|NODES|AUTO) [AUTO] - Algorithm for defining energy bins (FILE|LIN|LOG) [LOG] + Algorithm for defining energy bins (FILE|LIN|LOG|POW) [LOG] Start value for first energy bin in TeV [0.1] 0.00000075 Stop value for last energy bin in TeV [100.0] 0.00003 Number of energy bins (1-200) [20] 4 diff --git a/doc/source/users/tutorials/howto/fermi/howto_fermi_spectrum.rst b/doc/source/users/tutorials/howto/fermi/howto_fermi_spectrum.rst index 9be47d1..3cdeb87 100755 --- a/doc/source/users/tutorials/howto/fermi/howto_fermi_spectrum.rst +++ b/doc/source/users/tutorials/howto/fermi/howto_fermi_spectrum.rst @@ -18,7 +18,7 @@ script. To do this, type Input model definition XML file [$CTOOLS/share/models/crab.xml] vela_results.xml Source name [Crab] Vela Spectrum generation method (SLICE|NODES|AUTO) [AUTO] - Algorithm for defining energy bins (FILE|LIN|LOG) [LOG] + Algorithm for defining energy bins (FILE|LIN|LOG|POW) [LOG] Start value for first energy bin in TeV [0.1] 0.0001 Stop value for last energy bin in TeV [100.0] 0.1 Number of energy bins (1-200) [20] 10 diff --git a/doc/source/users/tutorials/howto/howto_combine_instruments.rst b/doc/source/users/tutorials/howto/howto_combine_instruments.rst index 81e7fcd..cef9a0c 100644 --- a/doc/source/users/tutorials/howto/howto_combine_instruments.rst +++ b/doc/source/users/tutorials/howto/howto_combine_instruments.rst @@ -51,7 +51,7 @@ Then bin the selected observations into a counts cube Image scale (in degrees/pixel) [0.02] Size of the X axis in pixels [200] Size of the Y axis in pixels [200] - Algorithm for defining energy bins (FILE|LIN|LOG) [LOG] + Algorithm for defining energy bins (FILE|LIN|LOG|POW) [LOG] Lower energy limit (TeV) [0.1] 0.03 Upper energy limit (TeV) [100.0] 150.0 Number of energy bins (1-200) [20] 40 @@ -78,7 +78,7 @@ Then compute the response cubes as follows Image scale (in degrees/pixel) [1.0] Size of the X axis in pixels [10] Size of the Y axis in pixels [10] - Algorithm for defining energy bins (FILE|LIN|LOG) [LOG] + Algorithm for defining energy bins (FILE|LIN|LOG|POW) [LOG] Lower energy limit (TeV) [0.1] 0.03 Upper energy limit (TeV) [100.0] 150.0 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 Input model definition XML file [$CTOOLS/share/models/crab.xml] models.xml Source name [Crab] Vela Spectrum generation method (SLICE|NODES|AUTO) [AUTO] - Algorithm for defining energy bins (FILE|LIN|LOG) [LOG] + Algorithm for defining energy bins (FILE|LIN|LOG|POW) [LOG] Start value for first energy bin in TeV [0.1] 0.0001 Stop value for last energy bin in TeV [100.0] 150.0 Number of energy bins (1-200) [20] diff --git a/doc/source/users/tutorials/howto/howto_xspec.rst b/doc/source/users/tutorials/howto/howto_xspec.rst index 2e86538..5b83b8a 100644 --- a/doc/source/users/tutorials/howto/howto_xspec.rst +++ b/doc/source/users/tutorials/howto/howto_xspec.rst @@ -49,7 +49,7 @@ Off counts spectrum: Calibration database [prod2] Instrument response function [South_0.5h] Input model definition XML file (if NONE, use point source) [NONE] - Algorithm for defining energy bins (FILE|LIN|LOG) [LOG] + Algorithm for defining energy bins (FILE|LIN|LOG|POW) [LOG] Start value for first energy bin in TeV [0.1] Stop value for last energy bin in TeV [100.0] Number of energy bins [120] 20 diff --git a/doc/source/users/tutorials/quickstart/binning.rst b/doc/source/users/tutorials/quickstart/binning.rst index fe55dfa..acf16fe 100755 --- a/doc/source/users/tutorials/quickstart/binning.rst +++ b/doc/source/users/tutorials/quickstart/binning.rst @@ -27,7 +27,7 @@ using the :ref:`ctbin` tool as follows: Image scale (in degrees/pixel) [0.02] Size of the X axis in pixels [200] Size of the Y axis in pixels [200] - Algorithm for defining energy bins (FILE|LIN|LOG) [LOG] + Algorithm for defining energy bins (FILE|LIN|LOG|POW) [LOG] Lower energy limit (TeV) [0.1] Upper energy limit (TeV) [100.0] Number of energy bins (1-200) [20] diff --git a/doc/source/users/tutorials/quickstart/energy_dispersion.rst b/doc/source/users/tutorials/quickstart/energy_dispersion.rst index a3c7e0f..92e793c 100755 --- a/doc/source/users/tutorials/quickstart/energy_dispersion.rst +++ b/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 Image scale (in degrees/pixel) [0.02] Size of the X axis in pixels [200] Size of the Y axis in pixels [200] - Algorithm for defining energy bins (FILE|LIN|LOG) [LOG] + Algorithm for defining energy bins (FILE|LIN|LOG|POW) [LOG] Lower energy limit (TeV) [0.1] Upper energy limit (TeV) [100.0] Number of energy bins (1-200) [20] @@ -82,22 +82,22 @@ using the :ref:`ctexpcube` tool. You run the tool as follows: .. code-block:: bash $ ctedispcube - Input event list or observation definition XML file [NONE] selected_events_edisp.fits - Calibration database [prod2] - Instrument response function [South_0.5h] - Input counts cube file to extract energy dispersion cube definition [NONE] - Coordinate system (CEL - celestial, GAL - galactic) (CEL|GAL) [CEL] - Projection method (AIT|AZP|CAR|GLS|MER|MOL|SFL|SIN|STG|TAN) [CAR] - First coordinate of image center in degrees (RA or galactic l) (0-360) [83.63] - Second coordinate of image center in degrees (DEC or galactic b) (-90-90) [22.51] - Image scale (in degrees/pixel) [1.0] - Size of the X axis in pixels [10] - Size of the Y axis in pixels [10] - Algorithm for defining energy bins (FILE|LIN|LOG) [LOG] - Lower energy limit (TeV) [0.1] - Upper energy limit (TeV) [100.0] - Number of energy bins (1-1000) [20] - Output energy dispersion cube file [edispcube.fits] + Input event list or observation definition XML file [NONE] selected_events_edisp.fits + Calibration database [prod2] + Instrument response function [South_0.5h] + Input counts cube file to extract energy dispersion cube definition [NONE] + Coordinate system (CEL - celestial, GAL - galactic) (CEL|GAL) [CEL] + Projection method (AIT|AZP|CAR|GLS|MER|MOL|SFL|SIN|STG|TAN) [CAR] + First coordinate of image center in degrees (RA or galactic l) (0-360) [83.63] + Second coordinate of image center in degrees (DEC or galactic b) (-90-90) [22.51] + Image scale (in degrees/pixel) [1.0] + Size of the X axis in pixels [10] + Size of the Y axis in pixels [10] + Algorithm for defining energy bins (FILE|LIN|LOG|POW) [LOG] + Lower energy limit (TeV) [0.1] + Upper energy limit (TeV) [100.0] + Number of energy bins (1-1000) [20] + Output energy dispersion cube file [edispcube.fits] Now you are ready to perform a binned maximum likelihood analysis taking the energy dispersion into account. You do this by running the :ref:`ctlike` tool diff --git a/doc/source/users/tutorials/quickstart/onoff.rst b/doc/source/users/tutorials/quickstart/onoff.rst index b5dc753..43aabbc 100644 --- a/doc/source/users/tutorials/quickstart/onoff.rst +++ b/doc/source/users/tutorials/quickstart/onoff.rst @@ -47,7 +47,7 @@ To derive On/Off observations from the ``events_edisp.fits`` event list, type: Instrument response function [South_0.5h] Input model definition XML file (if NONE, use point source) [NONE] $CTOOLS/share/models/crab.xml Source name [Crab] - Algorithm for defining energy bins (FILE|LIN|LOG) [LOG] + Algorithm for defining energy bins (FILE|LIN|LOG|POW) [LOG] Start value for first energy bin in TeV [0.1] Stop value for last energy bin in TeV [100.0] Number of energy bins [120] 30 diff --git a/doc/source/users/tutorials/quickstart/response.rst b/doc/source/users/tutorials/quickstart/response.rst index 82ae480..346ae35 100755 --- a/doc/source/users/tutorials/quickstart/response.rst +++ b/doc/source/users/tutorials/quickstart/response.rst @@ -59,7 +59,7 @@ You run :ref:`ctpsfcube` as follows: Image scale (in degrees/pixel) [1.0] Size of the X axis in pixels [10] Size of the Y axis in pixels [10] - Algorithm for defining energy bins (FILE|LIN|LOG) [LOG] + Algorithm for defining energy bins (FILE|LIN|LOG|POW) [LOG] Lower energy limit (TeV) [0.1] Upper energy limit (TeV) [100.0] Number of energy bins (1-1000) [20] diff --git a/doc/source/users/tutorials/quickstart/spectrum.rst b/doc/source/users/tutorials/quickstart/spectrum.rst index 4334aa7..28c4939 100755 --- a/doc/source/users/tutorials/quickstart/spectrum.rst +++ b/doc/source/users/tutorials/quickstart/spectrum.rst @@ -34,7 +34,7 @@ bins between 100 GeV and 100 TeV: Input model definition XML file [$CTOOLS/share/models/crab.xml] crab_results.xml Source name [Crab] Spectrum generation method (SLICE|NODES|AUTO) [AUTO] - Binning algorithm (LIN|LOG|FILE) [LOG] + Binning algorithm (FILE|LIN|LOG|POW) [LOG] Lower energy limit (TeV) [0.1] Upper energy limit (TeV) [100.0] Number of energy bins [20] 10 diff --git a/doc/source/users/user_manual/data.rst b/doc/source/users/user_manual/data.rst index ce34133..a827f1b 100755 --- a/doc/source/users/user_manual/data.rst +++ b/doc/source/users/user_manual/data.rst @@ -1,9 +1,10 @@ .. _um_data: -The data --------- +IACT data +--------- -ctools operates on event lists. An event list is a table where each row +For Imaging Air Cherenkov Telescopes (IACTs), such as CTA, H.E.S.S., MAGIC or +VERITAS, ctools operates on event lists. An event list is a table where each row corresponds to a registered event and each column corresponds to a property of the event. Required properties are the event identifier, the reconstructed 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. Note that times are given in so-called Mission-Elapsed Time (MET) in seconds, and that the zero-point of the MET is specified by the ``MJDREFI`` and -``MJDREFF`` keywords as the integer and fraction part of a Modified Julian Date +``MJDREFF`` keywords as the integer and fractional part of a Modified Julian Date (MJD) in the header of the GTI. The same holds also for the trigger times in the event list. diff --git a/doc/source/users/user_manual/likelihood.rst b/doc/source/users/user_manual/likelihood.rst index ff7b82b..c349a31 100755 --- a/doc/source/users/user_manual/likelihood.rst +++ b/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 fitting the source and the background together to the data, and :math:`\ln L(M_b)` is the log-likelihood value obtained when fitting only the background model to the data. -Under the hypothesis that the model :math:`M_s+M_b` provides a satisfactory fit +Under the hypothesis that the model :math:`M_b` provides a satisfactory fit of the data, :math:`\mathrm{TS}` follows a :math:`\chi^2_n` distribution with :math:`n` degrees of freedom, where :math:`n` is the number of free parameters in the source model component. Therefore diff --git a/doc/source/users/user_manual/model_table.png b/doc/source/users/user_manual/model_table.png new file mode 100644 index 0000000..9a1fa62 Binary files /dev/null and b/doc/source/users/user_manual/model_table.png differ diff --git a/doc/source/users/user_manual/model_table_energies.png b/doc/source/users/user_manual/model_table_energies.png new file mode 100644 index 0000000..9041db7 Binary files /dev/null and b/doc/source/users/user_manual/model_table_energies.png differ diff --git a/doc/source/users/user_manual/model_table_parameters.png b/doc/source/users/user_manual/model_table_parameters.png new file mode 100644 index 0000000..b74f2d1 Binary files /dev/null and b/doc/source/users/user_manual/model_table_parameters.png differ diff --git a/doc/source/users/user_manual/model_table_spectra.png b/doc/source/users/user_manual/model_table_spectra.png new file mode 100644 index 0000000..31ad0bd Binary files /dev/null and b/doc/source/users/user_manual/model_table_spectra.png differ diff --git a/doc/source/users/user_manual/models.rst b/doc/source/users/user_manual/models.rst index 3b93f05..0782518 100755 --- a/doc/source/users/user_manual/models.rst +++ b/doc/source/users/user_manual/models.rst @@ -7,8 +7,10 @@ Modelling the data :maxdepth: 1 models_concept - models_implementation - models_spatial_src - models_spatial_bgd + models_source + models_spatial models_spectral models_temporal + models_bgd_iact + models_bgd_comptel + models_bgd_spi diff --git a/doc/source/users/user_manual/models_bgd_comptel.rst b/doc/source/users/user_manual/models_bgd_comptel.rst new file mode 100644 index 0000000..9aabb61 --- /dev/null +++ b/doc/source/users/user_manual/models_bgd_comptel.rst @@ -0,0 +1,104 @@ +.. _um_models_bgd_comptel: + +COMPTEL background models +------------------------- + +The following section presents the model that is available in ctools for the +modelling of instrumental background in COMPTEL data. + +In general, the instrumental background in COMPTEL data for a given energy +band :math:`E'` is specified by a so-called DRB cube: + +.. math:: + M(p',E') = {\rm DRB}(\chi, \psi, \bar{\varphi} | E') + +where :math:`M(p',E')` is given in units of +:math:`{\rm events} \,\, {\rm s}^{-1} {\rm MeV}^{-1} {\rm sr}^{-1}`. +:math:`(\chi, \psi)` is the photon scatter direction while +:math:`\bar{\varphi}` is the Compton scattering angle. + + +DRB cubes +^^^^^^^^^ + +DRB cubes are specified as FITS files in the +:ref:`observation definition file ` +using the ``DRB`` parameter, e.g. + +.. code-block:: xml + + + + + + + + + + + ... + + +Since DRB files are not provided by HEASARC, the user may specify the DRG +file as a first order approximation of the instrumental background distribution +in COMPTEL data. + + +DRB fitting +^^^^^^^^^^^ + +The usual way of handling the COMPTEL background model during a maximum likelihood +fit is to adjust the normalisation of each :math:`\bar{\varphi}`-layer of the +DRB cube to the data. This is accomplished by using the ``DRBFitting`` model, +e.g. + +.. code-block:: xml + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ... + + +.. warning:: + Depending on the energy band :math:`E'`, a DRB cube may be empty for a number + of :math:`\bar{\varphi}`-layers, which means that the corresponding + normalisation cannot be adjusted. To avoid warnings during the :ref:`ctlike` + model fit it is recommended to fix the ``Normalization`` parameters of the + corresponding layers. In the example above, all layers with :math:`\bar{\varphi}` + values below 16 degrees were fixed, the first fitted normalisation + is for :math:`\bar{\varphi}=17` degrees. diff --git a/doc/source/users/user_manual/models_bgd_iact.rst b/doc/source/users/user_manual/models_bgd_iact.rst new file mode 100644 index 0000000..7cb04c9 --- /dev/null +++ b/doc/source/users/user_manual/models_bgd_iact.rst @@ -0,0 +1,364 @@ +.. _um_models_bgd_iact: + +IACT background models +---------------------- + +The following sections present the model components that are available in +ctools for the modelling of instrumental background in data from Imaging Air +Cherenkov Telescopes (IACTs) such as CTA, H.E.S.S., VERITAS, and MAGIC. + +IACT background models are factorised into an optional spatial tag +(tags ```` or ````) and a spectral tag +(tag ````) using + +.. math:: + M(p',E') = M_{\rm spatial}(p'|E') \times M_{\rm spectral}(E') + +where :math:`M(p',E')` is given in units of +:math:`{\rm events} \,\, {\rm s}^{-1} {\rm MeV}^{-1} {\rm sr}^{-1}`. + +For the spectral components, all spectra described in +:ref:`um_models_spectral` +may be used. + +.. note:: + Spatial directions :math:`p'` and energies :math:`E'` are now the + reconstructed quantities, hence no convolution of the model with the + :ref:`Instrument Response Functions ` is performed. + + +General IACT background +^^^^^^^^^^^^^^^^^^^^^^^ + + The general IACT background model is factorised in a spatial and spectral + component and has the type ``CTABackground``. It has the following XML + structure: + + .. code-block:: xml + + + + ... + + + ... + + + + .. warning:: + You need to specify the ``instrument`` label in the ``source`` tag + that corresponds to the ``instrument`` label of the observation to which + the model should apply. Supported ``instrument`` labels are ``CTA``, + ``HESS``, ``VERITAS`` and ``MAGIC``. + + For example, if you analyse a H.E.S.S. observation you need to specify + ``instrument="HESS"`` in the ``source`` tag, while the model type is + still ``CTABackground``. So don't get confused! + + .. code-block:: xml + + + + The same logic applies to the radial acceptance, IRF, effective area and + cube background models. + + .. warning:: + In case that a background model should be used for the analysis of + On/Off data, the corresponding ``OnOff`` ``instrument`` label needs to + be selected. Supported ``OnOff`` ``instrument`` labels are ``CTAOnOff``, + ``HESSOnOff``, ``VERITASOnOff`` and ``MAGICOnOff``. + + For example, if you analyse a H.E.S.S. On/Off observation you need to + specify + + .. code-block:: xml + + + + The same logic applies to the radial acceptance, IRF, effective area and + cube background models. + + The following sections describe the spatial model components that are + available. + + +Gaussian +~~~~~~~~ + + The ``Gaussian`` model describes a 2D Gaussian shape in offset angle squared + + .. code-block:: xml + + + + + + + ... + + + + and implements + + .. math:: + M_{\rm spatial}(\theta) = \exp \left(-\frac{1}{2} + \left( \frac{\theta^2}{\sigma} \right)^2 \right) + + where + + * :math:`\sigma` = ``Sigma`` (degrees) + + and + + .. math:: + \theta = \sqrt{\mathrm{DETX} \times \mathrm{DETX} + \mathrm{DETY} \times\mathrm{DETY}} + + with :math:`\mathrm{DETX}` and :math:`\mathrm{DETY}` being the detector + coordinates in the nominal system. + + +Profile +~~~~~~~ + + The ``Profile`` model describes a radial profile + + .. code-block:: xml + + + + + + + + + ... + + + + and implements + + .. math:: + M_{\rm spatial}(\theta) = (1 + (\theta/c_0)^{c_1})^{-c_2/c_1} + + where + + * :math:`c_0` = ``Width`` (degrees) + * :math:`c_1` = ``Core`` + * :math:`c_2` = ``Tail`` + + +Polynom +~~~~~~~ + + The ``Polynom`` model describes a polynomial with an arbitrary number of + coefficients + + .. code-block:: xml + + + + + + + + ... + + + ... + + + + and implements + + .. math:: + M_{\rm spatial}(\theta) = \sum_{i=0}^m c_i \theta^i + + where + + * :math:`c_0` = ``Coeff0`` + * :math:`c_1` = ``Coeff1`` + * :math:`c_2` = ``Coeff2`` + * :math:`c_3` = ``Coeff3`` + * ... + + +Gradient +~~~~~~~~ + + The ``Gradient`` model describes a bilinear gradient over the field of + view + + .. code-block:: xml + + + + + + + + ... + + + + and implements + + .. math:: + M_{\rm spatial}(\mathrm{DETX},\mathrm{DETY}) = + 1 + \nabla_\mathrm{x} \mathrm{DETX} + \nabla_\mathrm{y} \mathrm{DETY} + + where + + * :math:`\nabla_\mathrm{x}` = ``Grad_DETX`` (per degree) + * :math:`\nabla_\mathrm{y}` = ``Grad_DETY`` (per degree) + + + +Multiplicative +~~~~~~~~~~~~~~ + + The ``Multiplicative`` model describes a multiplication of spatial models + + .. code-block:: xml + + + + + ... + + + ... + + ... + + + ... + + + + and implements + + .. math:: + M_{\rm spatial}(\mathrm{DETX},\mathrm{DETY}) = + \prod_{i=0}^{N-1} M^{(i)}_{\rm spatial}(\mathrm{DETX},\mathrm{DETY}) + + where :math:`M^{(i)}_{\rm spatial}(\mathrm{DETX},\mathrm{DETY})` is any + spatial model component, including another multiplicative model, and + :math:`N` is the number of model components that are multiplied. + For example, the default model for a H.E.S.S. data analysis is specified + by + + .. code-block:: xml + + + + + + + + + + + + + ... + + + + +Radial acceptance background +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + + For legacy reasons, there exists a class of radially symmetric background + models of the type ``RadialAcceptance`` with the following XML structure: + + .. code-block:: xml + + + + ... + + + ... + + + + These models require a ```` tag as the spatial component and + accept all spatial model types that take the offset angle :math:`\theta` + as variable, such as ``Gaussian``, ``Profile`` and ``Polynom``. + + .. warning:: + The use of the radial acceptance model is deprecated, and the + ``CTABackground`` model should be used instead. + + +IRF background +^^^^^^^^^^^^^^ + + The :ref:`Instrument Response Functions (IRFs) ` contain a template + that predicts the background rate as function of position in the field of view + and measured energy in units of + :math:`{\rm events} \, {\rm s}^{-1} {\rm MeV}^{-1} {\rm sr}^{-1}`. This template + can be used by specifying a model of type ``CTAIrfBackground``. No spatial component + will be specified explicitly since the spatial (and spectral) information is + already contained in the template. + + The model will be multiplied by a spectral component to allow for the adjustment + of the energy distribution of the background rate. + + .. code-block:: xml + + + + ... + + + + If the observation is an On/Off observation, do not forget to switch the instrument + to ``CTAOnOff``: + + .. code-block:: xml + + + + ... + + + + +Effective area background +^^^^^^^^^^^^^^^^^^^^^^^^^ + + Instead of using the background template the effective area for gamma rays can + also be used to model the instrumental background. Note that in this case the + effective area has to be scaled to a reasonable background rate by selecting + appropriate values for the spectral model component. + + .. code-block:: xml + + + + ... + + + + +Cube background +^^^^^^^^^^^^^^^ + + For a stacked analysis, the background rates are predicted by a so called + background cube. The FITS file name of the background cube is specified + either as ctools task parameter, or using the ``BkgCube`` parameter in the + the observation definition XML file. + + The background cube model is used by specifying a model of type + ``CTACubeBackground``. Similar to the ``CTAIrfBackground`` model, the + background cube is multplied with a spectral model to allow for the adjustment + of the energy distribution of the background rate. + + .. code-block:: xml + + + + ... + + diff --git a/doc/source/users/user_manual/models_bgd_spi.rst b/doc/source/users/user_manual/models_bgd_spi.rst new file mode 100644 index 0000000..d3aad4c --- /dev/null +++ b/doc/source/users/user_manual/models_bgd_spi.rst @@ -0,0 +1,209 @@ +.. _um_models_bgd_spi: + +SPI background models +--------------------- + +The instrumental background in INTEGRAL/SPI data is modelled by so-called +templates that describe the variation of the background rates with time: + +.. math:: + M(p',E',t') = \sum_{i=0}^{N-1} n_i(d',E',t') \times {\rm TPL}_i(d',E',t') + +where :math:`M(p',E',t')` is given in units of +:math:`{\rm events} \,\, {\rm s}^{-1} {\rm MeV}^{-1} {\rm sr}^{-1}`. +:math:`d'` is the SPI detector identifier, +:math:`E'` is the measured energy, and +:math:`t'` is the time that is linked via the pointing of the SPI +telescope to an area of the sky. + +:math:`{\rm TPL}_i(d',E',t')` is the :math:`i` th out of :math:`N` +templates, and :math:`n_i(d',E',t')` is a normalisation factor for this +template that may depend on the SPI detector identifier, measured energy and +time. + + +Creating a background model +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +Since the number of background normalisation factors for INTEGRAL/SPI data +analysis may be large, it is not recommenced to create a +:ref:`model definition XML file ` +directly, but to use the ``gammalib.GSPIModelDataSpace()`` constructor in +a Python script to set up the background model. +The ``gammalib.GSPIModelDataSpace()`` constructor takes four arguments: + +* a SPI observation group +* the name you want to give to the model component +* a fit method that should be used for the model component +* an index that refers to the template that should be used for the model + component + +In the example below it is assumed that three background templates +were generated using the +`Off-line Scientific Analysis (OSA) `_ +task ``spi_obs_back``, which appends the templates to the SPI observation +group ``og_spi.fits``. +The first template corresponds to the saturated event rates in the Germanium +detectors, the second is a constant rate template, and the third corresponds +to a linearly increasing rate with time. + + .. code-block:: python + + # Load SPI observation + og = gammalib.GSPIObservation('og_spi.fits') + + # Set background model components + bgm_model_1 = gammalib.GSPIModelDataSpace(og, 'GEDSAT', 'orbit,dete', 0) + bgm_model_2 = gammalib.GSPIModelDataSpace(og, 'CONST', 'dete', 1) + bgm_model_3 = gammalib.GSPIModelDataSpace(og, 'TIME1', 'dete', 2) + + # Append models + models = gammalib.GModels() + models.append(bgm_model_1) + models.append(bgm_model_2) + models.append(bgm_model_3) + + # Save models + models.save('model_spi.xml') + +For illustration, the typical content of the resulting XML file is as follows: + + .. code-block:: xml + + + + + + + ... + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +Fit methods +^^^^^^^^^^^ + +The fit method defines how the indices of the SPI data space are +grouped into template normalisation factors. Grouping is allowed in all three +data space dimensions: for pointings, detectors and energies. + +In the example above, individual background normalisation factors for the +``GEDSAT`` template were assigned to each orbit and detector, while for the +``CONST`` and ``TIME1`` template there is one normalisation factor per +detector. Here some further examples: + +* ``orbit,dete,gedfail``: one normalisation factor per orbit and detector and + Germanium detector failure period +* ``orbit,evtclass``: one normalisation factor per orbit and event class +* ``dete,ebin``: one normalisation factor per detector and energy bin +* ``gedanneal``: one normalisation factor per Germanium detector annealing + period + + +Pointing grouping +~~~~~~~~~~~~~~~~~ + +point +..... + +Assigns a template normalisation factor for each pointing. + + +orbit +..... + +Assigns a template normalisation factor for each orbit. + +date +.... + +Assigns a template normalisation factor for each date interval. For example, +``date 4 hours`` assigns a normalisation factor for intervals of 4 hours, +or ``date 1 month`` assigns a normalisation factor for intervals of one month. +The following time units are supported: ``min``, ``hour``, ``day``, ``week``, +``month`` or ``year``. + +gedfail +....... + +Makes sure that there are different template normalisation factors before and +after the failure of a Germanium detector. This method can either be used +as a fit method, or can be used in combination with ``point``, ``orbit``, +``date`` and ``gedanneal``. + +gedanneal +......... + +Makes sure that there are different template normalisation factors before and +after the Germanium detector annealing. This method can either be used +as a fit method, or can be used in combination with ``point``, ``orbit``, +``date`` and ``gedfail``. + + +Detector grouping +~~~~~~~~~~~~~~~~~ + +dete +.... + +Assigns a template normalisation factor for each detector. + +evtclass +........ + +Assigns a template normalisation factor for event class. Event classes are +either single detector events (SE), double detector events (ME2) or tripple +detector events (ME3). + + +Energy grouping +~~~~~~~~~~~~~~~ + +ebin +.... + +Assigns a template normalisation factor for each energy bin. diff --git a/doc/source/users/user_manual/models_concept.rst b/doc/source/users/user_manual/models_concept.rst index 47590e9..8e7d4b0 100644 --- a/doc/source/users/user_manual/models_concept.rst +++ b/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 event distribution. Generally, the measured events can be separated into two distinct classes: events being attributed to gamma rays of celestial origin (the "source" -events) or events being attributed to any other kind of trigger (the +events) and events being attributed to any other kind of trigger (the "background" events). In the first case, the :ref:`Instrument Response Functions (IRFs) ` describe how an incident gamma-ray converts into a measured event. diff --git a/doc/source/users/user_manual/models_implementation.rst b/doc/source/users/user_manual/models_implementation.rst deleted file mode 100644 index 5ee3ae6..0000000 --- a/doc/source/users/user_manual/models_implementation.rst +++ /dev/null @@ -1,172 +0,0 @@ -.. _um_models_implementation: - -Implementation --------------- - -The general model is describe in ctools using a -:ref:`model definition XML file `. -Below is a simple example of such a file comprising one source and one -background model. -Each model is factorised into -a spectral (tag ````), -a spatial (tags ```` or ````), and -a temporal component (tag ````). - -.. math:: - M(p,E,t) = M_{\rm spatial}(p|E) \times M_{\rm spectral}(E) \times M_{\rm temporal}(t) - -where :math:`M(p,E,t)` is given in units of -:math:`photons \,\, cm^{-2} s^{-1} MeV^{-1} sr^{-1}`. - -The spatial model component describes the energy dependent morphology of the -source. -It satisfies - -.. math:: - \int_{\Omega} M_{\rm spatial}(p|E) \, d\Omega = 1 - -for all :math:`E`, hence the spatial component does not -impact the spatially integrated spectral and temporal properties of the -source (the integration is done here over the spatial parameters -:math:`p` in a spherical coordinate system). -The units of the spatial model component are -:math:`[M_{\rm spatial}] = {\rm sr}^{-1}` -(but see the exception of the -:ref:`DiffuseMapCube spatial model component `). - -The spectral model component describes the spatially integrated spectral -distribution of the source. -It satisfies - -.. math:: - \int_{E} M_{\rm spectral}(E) \, dE = \Phi - -where :math:`\Phi` is the spatially and spectrally integrated total source -flux. -The units of the spectral model component -are :math:`[M_{\rm spectral}] = {\rm cm}^{-2} {\rm s}^{-1} {\rm MeV}^{-1}`. - -The temporal model component describes the relative variation of the -source flux with respect to the mean value given by the spectral model -component. -The temporal model component is unit less. - -In this specific example, the source component ``Crab`` describes -a point source at the location of the Crab nebula with a power law spectral -shape that is constant in time. -The background component ``Background`` is modelled using the template that is -provided with the -:ref:`Instrument Response Functions (IRFs) ` -and that is multiplied by a spectral power law function. - -.. code-block:: xml - - - - - - - - - - - - - - - - - - - - - - - - - - -Model parameters are specified by a ```` tag with a certain -number of attributes. -The ``name`` attribute gives the (case-sensitive) parameter name that -needs to be unique within a given model component. -The ``scale`` attribute gives a scaling factor that will be multiplied by -the ``value`` attribute to provide the real (physical) parameter value. -The ``min`` and ``max`` attributes specify boundaries for the ``value`` -term of the parameter. -And the ``free`` attribute specifies whether a parameter should be fitted -(``free="1"``) or kept fixed (``free="0"``) in a maximum likelihood -analysis. -After a maximum likelihood fit using :ref:`ctlike`, an -``error`` attribute giving the statisical uncertainty of the ``value`` -term will be appended to each ```` tag. - -.. note:: - For compatibility reasons with the Fermi/LAT XML format the ```` - tag can be omitted for models that are constant in time. - -.. note:: - - XML files are ASCII files and can be edited by hand using any text - editor. - The indentation of the XML elements is not mandatory. - -.. note:: - - The splitting of parameter values into a ``value`` and ``scale`` factor - is mainly for numerical purposes. - Parameter fitting algorithms can be ill-conditioned if several - parameters of vastly different orders of magnitudes need to be - optimised simultaneously. - Splitting a value into two components allows to "prescale" the - parameters so that the effective parameters to be optimised (the ``value`` terms) - are all of about unity. - -.. note:: - - The syntax of the :ref:`model definition XML file ` has been - inspired from the syntax used by the Fermi/LAT ScienceTools, but for reasons - of clarity and homogenity of the various model and parameter names we have - made some modifications. - Nevertheless, the format used by the Fermi/LAT ScienceTools is also - supported. - -.. note:: - - To cope with cross-calibration uncertainties between different instruments, - instrument specific scaling factors :math:`S_{\rm inst}` can be multiplied - to the source models according to - - .. math:: - M(p,E,t) = S_{\rm inst} \times M_{\rm spatial}(p|E) \times M_{\rm spectral}(E) \times M_{\rm temporal}(t) - - and an example for the specification of scale factors :math:`S_{\rm CTA}` for - ``CTA`` and :math:`S_{\rm HESS}` for H.E.S.S. in the - :ref:`model definition XML file ` - is shown below. - In the example, :math:`S_{\rm CTA}` is fixed to :math:`1`, hence the - scale factor could also be omitted from the XML file. - The scale factor :math:`S_{\rm HESS}` is set to :math:`1.1` and will be - fitted during the model fit. - - .. code-block:: xml - - - - - - - - - - - - - - - - - - - - diff --git a/doc/source/users/user_manual/models_source.rst b/doc/source/users/user_manual/models_source.rst new file mode 100644 index 0000000..9a7bc39 --- /dev/null +++ b/doc/source/users/user_manual/models_source.rst @@ -0,0 +1,173 @@ +.. _um_models_source: + +Source models +------------- + +The general model is describe in ctools using a +:ref:`model definition XML file `. +Below is a simple example of such a file comprising one source and one +background model (see :ref:`um_models_bgd` for the implementation of the +background models). + +Each source model is factorised into a spatial (tags ````, a +spectral (tag ````), and a temporal component (tag ````) +using + +.. math:: + M(p,E,t) = M_{\rm spatial}(p|E) \times M_{\rm spectral}(E) \times M_{\rm temporal}(t) + +where :math:`M(p,E,t)` is given in units of +:math:`photons \,\, {\rm cm}^{-1} {\rm s}^{-1} {\rm MeV}^{-1} {\rm sr}^{-1}`. + +The spatial model component describes the energy dependent morphology of the +source. +It satisfies + +.. math:: + \int_{\Omega} M_{\rm spatial}(p|E) \, d\Omega = 1 + +for all :math:`E`, hence the spatial component does not +impact the spatially integrated spectral and temporal properties of the +source (the integration is done here over the spatial parameters +:math:`p` in a spherical coordinate system). +The units of the spatial model component are +:math:`[M_{\rm spatial}] = {\rm sr}^{-1}` +(but see the exception of the +:ref:`DiffuseMapCube spatial model component `). + +The spectral model component describes the spatially integrated spectral +distribution of the source. +It satisfies + +.. math:: + \int_{E} M_{\rm spectral}(E) \, dE = \Phi + +where :math:`\Phi` is the spatially and spectrally integrated total source +flux. +The units of the spectral model component +are :math:`[M_{\rm spectral}] = {\rm cm}^{-2} {\rm s}^{-1} {\rm MeV}^{-1}`. + +The temporal model component describes the relative variation of the +source flux with respect to the mean value given by the spectral model +component. +The temporal model component is unit less. + +In this specific example, the source component ``Crab`` describes +a point source at the location of the Crab nebula with a power law spectral +shape that is constant in time. +The background component ``Background`` is modelled using the template that is +provided with the +:ref:`Instrument Response Functions (IRFs) ` +and that is multiplied by a spectral power law function. + +.. code-block:: xml + + + + + + + + + + + + + + + + + + + + + + + + + + +Model parameters are specified by a ```` tag with a certain +number of attributes. +The ``name`` attribute gives the (case-sensitive) parameter name that +needs to be unique within a given model component. +The ``scale`` attribute gives a scaling factor that will be multiplied by +the ``value`` attribute to provide the real (physical) parameter value. +The ``min`` and ``max`` attributes specify boundaries for the ``value`` +term of the parameter. +And the ``free`` attribute specifies whether a parameter should be fitted +(``free="1"``) or kept fixed (``free="0"``) in a maximum likelihood +analysis. +After a maximum likelihood fit using :ref:`ctlike`, an +``error`` attribute giving the statisical uncertainty of the ``value`` +term will be appended to each ```` tag. + +.. note:: + For compatibility reasons with the Fermi/LAT XML format the ```` + tag can be omitted for models that are constant in time. + +.. note:: + + XML files are ASCII files and can be edited by hand using any text + editor. + The indentation of the XML elements is not mandatory. + +.. note:: + + The splitting of parameter values into a ``value`` and ``scale`` factor + is mainly for numerical purposes. + Parameter fitting algorithms can be ill-conditioned if several + parameters of vastly different orders of magnitudes need to be + optimised simultaneously. + Splitting a value into two components allows to "prescale" the + parameters so that the effective parameters to be optimised (the ``value`` terms) + are all of about unity. + +.. note:: + + The syntax of the :ref:`model definition XML file ` has been + inspired from the syntax used by the Fermi/LAT ScienceTools, but for reasons + of clarity and homogenity of the various model and parameter names we have + made some modifications. + Nevertheless, the format used by the Fermi/LAT ScienceTools is also + supported. + +.. note:: + + To cope with cross-calibration uncertainties between different instruments, + instrument specific scaling factors :math:`S_{\rm inst}` can be multiplied + to the source models according to + + .. math:: + M(p,E,t) = S_{\rm inst} \times M_{\rm spatial}(p|E) \times M_{\rm spectral}(E) \times M_{\rm temporal}(t) + + and an example for the specification of scale factors :math:`S_{\rm CTA}` for + ``CTA`` and :math:`S_{\rm HESS}` for H.E.S.S. in the + :ref:`model definition XML file ` + is shown below. + In the example, :math:`S_{\rm CTA}` is fixed to :math:`1`, hence the + scale factor could also be omitted from the XML file. + The scale factor :math:`S_{\rm HESS}` is set to :math:`1.1` and will be + fitted during the model fit. + + .. code-block:: xml + + + + + + + + + + + + + + + + + + + + diff --git a/doc/source/users/user_manual/models_spatial.rst b/doc/source/users/user_manual/models_spatial.rst new file mode 100644 index 0000000..8db16c7 --- /dev/null +++ b/doc/source/users/user_manual/models_spatial.rst @@ -0,0 +1,439 @@ +.. _um_models_spatial: + +Spatial source model components +------------------------------- + +The following sections present the spatial model components that are available +in ctools for gamma-ray sources. + +.. note:: + Except of the ``DiffuseMapCube`` model, all spatial models are normalised + so that when integrated over the sphere the result is unity. + +Point source +^^^^^^^^^^^^ + + The ``PointSource`` model describes a point source + + .. code-block:: xml + + + + + + + + ... + + + + where + + * ``RA`` is the Right Ascension (degrees) + * ``DEC`` is the Declination (degrees) + + Instead of ``RA`` and ``DEC`` one may use ``GLON`` and ``GLAT`` to give the + position in Galactic coordinates + + .. code-block:: xml + + + + + + + + ... + + + + where + + * ``GLON`` is the Galactic longitude (degrees) + * ``GLAT`` is the Galactic latitude (degrees) + + .. note:: + Galactic coordinates using the ``GLON`` and ``GLAT`` parameters can be + specified for all spatial models that require a sky coordinate. Galactic + coordinates are transformed internally into celestial coordinates, and + in case that a model is written into an XML file, the corresponding + parameters will be replaced by the celestial coordinates ``RA`` and + ``DEC``. + + .. note:: + For compatibility with the Fermi/LAT ScienceTools the model type + ``PointSource`` can be replaced by ``SkyDirFunction``. + + +Radial source +^^^^^^^^^^^^^ + +RadialDisk +~~~~~~~~~~ + + The ``RadialDisk`` model describes a uniform intensity distribution within + a given radius + + .. code-block:: xml + + + + + + + + + ... + + + + where + + * ``RA`` is the Right Ascension of the disk centre (degrees) + * ``DEC`` is the Declination of the disk centre (degrees) + * ``Radius`` is the disk radius (degrees) + +RadialRing +~~~~~~~~~~ + + The ``RadialRing`` model specifies a uniform intensity distribution within + a circular ring + + .. code-block:: xml + + + + + + + + + + ... + + + + where + + * ``RA`` is the Right Ascension of the ring centre (degrees) + * ``DEC`` is the Declination of the ring centre (degrees) + * ``Radius`` is the inner ring radius (degrees) + * ``Width`` is the ring width radius (degrees) + + .. note:: + Specifying the inner ring radius and ring width guarantees that both + parameters are well defined. The ring outer radius is given by + ``Radius+Width``. + + +RadialGaussian +~~~~~~~~~~~~~~ + + The ``RadialGaussian`` model describes a Gaussian intensity distribution + + .. code-block:: xml + + + + + + + + + ... + + + + and implements + + .. math:: + M_{\rm spatial}(\theta) = \frac{1}{2 \pi \sigma^2} \exp + \left(-\frac{1}{2}\frac{\theta^2}{\sigma^2} \right), + + where + + * ``RA`` is the Right Ascension of the Gaussian centre (degrees) + * ``DEC`` is the Declination of the Gaussian centre (degrees) + * :math:`\sigma` = ``Sigma`` (degrees) + +RadialShell +~~~~~~~~~~~ + + The ``RadialShell`` model describes a spherical shell projected on the sky + + .. code-block:: xml + + + + + + + + + + ... + + + + and implements + + .. math:: + M_{\rm spatial}(\theta) = n_0 \left \{ + \begin{array}{l l} + \displaystyle + \sqrt{ \theta_{\rm out}^2 - \theta^2 } - \sqrt{ \theta_{\rm in}^2 - \theta^2 } + & \mbox{if $\theta \le \theta_{\rm in}$} \\ + \\ + \displaystyle + \sqrt{ \theta_{\rm out}^2 - \theta^2 } + & \mbox{if $\theta_{\rm in} < \theta \le \theta_{\rm out}$} \\ + \\ + \displaystyle + 0 & \mbox{if $\theta > \theta_{\rm out}$} + \end{array} + \right . + + where + + * ``RA`` is the Right Ascension of the shell centre (degrees) + * ``DEC`` is the Declination of the shell centre (degrees) + * :math:`\theta_{\rm out}` = ``Radius`` + ``Width`` (degrees) + * :math:`\theta_{\rm in}` = ``Radius`` (degrees) + + +Elliptical source +^^^^^^^^^^^^^^^^^ + +EllipticalDisk +~~~~~~~~~~~~~~ + + The ``EllipticalDisk`` model describes a uniform intensity distribution within + an elliptical circumference: + + .. code-block:: xml + + + + + + + + + + + ... + + + + where + + * ``RA`` is the Right Ascension (degrees) + * ``DEC`` is the Declination (degrees) + * ``PA`` is the position angle, counted counterclockwise from North (degrees) + * ``MinorRadius`` is the minor radius of the ellipse (degrees) + * ``MajorRadius`` is the major radius of the ellipse (degrees) + +EllipticalGaussian +~~~~~~~~~~~~~~~~~~ + + The ``EllipticalGaussian`` model describes a Gaussian intensity distribution + + .. code-block:: xml + + + + + + + + + + + ... + + + + and implements + + .. math:: + M_{\rm spatial}(\theta, \phi) = \exp \left( -\frac{\theta^2}{2 r_\mathrm{eff}^2} \right), + + with + + .. math:: + r_\mathrm{eff} = \frac{ab} {\sqrt{\left( a \sin (\phi - \phi_0) \right)^2 + + \sqrt{\left( b \cos (\phi - \phi_0) \right)^2}}} + + where + + * ``RA`` is the Right Ascension (degrees) + * ``DEC`` is the Declination (degrees) + * ``PA`` is the position angle, counted counterclockwise from North (degrees) + * :math:`a` = ``MinorRadius`` (degrees) + * :math:`b` = ``MajorRadius`` (degrees) + * :math:`\phi_0` is the position angle of the ellipse, counted counterclockwise + from North + * :math:`\phi` is the azimuth angle with respect to North. + + +Diffuse source +^^^^^^^^^^^^^^ + +DiffuseIsotropic +~~~~~~~~~~~~~~~~ + + The ``DiffuseIsotropic`` model describes an isotropic intensity distribution + + .. code-block:: xml + + + + + + + ... + + + + where + + * ``Value`` is isotropic intensity + + .. note:: + For compatibility with the Fermi/LAT ScienceTools the model type + ``DiffuseIsotropic`` can be replaced by ``ConstantValue``. + +DiffuseMap +~~~~~~~~~~ + + The ``DiffuseMap`` model describes an arbitrary intensity distribution in + form of a sky map + + .. code-block:: xml + + + + + + + ... + + + + where + + * ``Normalization`` is a normalization value + + and the ``file`` attribute specifies a sky map FITS file name. If a file name + without path is specified it is assumed that the FITS file resides in the same + directory as the model definition XML file. + + .. note:: + For compatibility with the Fermi/LAT ScienceTools the model type + ``DiffuseMap`` can be replaced by ``SpatialMap`` and the parameter + ``Normalization`` can be replaced by ``Prefactor``. + + .. note:: + By default, the diffuse map is normalised so that + + .. math:: + \int_{\Omega} M_{\rm spatial}(p|E) \, d\Omega = 1 + + which means that the units of the spatial model component are + :math:`[M_{\rm spatial}] = {\rm sr}^{-1}`. + To avoid the normalisation you may add the ``normalize="0"`` attribute + to the spatial model tag. + + .. code-block:: xml + + + + + + + ... + + + + In that case, generally + + .. math:: + \int_{\Omega} M_{\rm spatial}(p|E) \, d\Omega \neq 1 + + and the spectral component cannot be directly interpreted as a physical + source intensity. + + .. _um_models_spatial_src_diffuse_cube: + +DiffuseMapCube +~~~~~~~~~~~~~~ + + The ``DiffuseMapCube`` model describes an arbitrary energy-dependent intensity + distribution in form of a map cube + + .. code-block:: xml + + + + + + + ... + + + + where + + * ``Normalization`` is a normalization value + + Note that the map cube is not normalised to unit, hence generally + + .. math:: + \int_{\Omega} M_{\rm spatial}(p|E) \, d\Omega \neq 1 + + To compute the flux in a given energy band for a ``DiffuseMapCube`` model + you have to integrated both the spatial and spectral components, i.e. + + .. math:: + \Phi = \int_{\Omega} \int_{E} M_{\rm spatial}(p|E) \times + M_{\rm spectral}(E)\, d\Omega \, dE + + .. note:: + For compatibility with the Fermi/LAT ScienceTools the model type + ``DiffuseMapCube`` can be replaced by ``MapCubeFunction`` and the parameter + ``Normalization`` can be replaced by ``Value``. + + +Composite model +^^^^^^^^^^^^^^^ + + The ``Composite`` model implements a composite model that is the sum of an + arbitrary number of spatial models + + .. code-block:: xml + + + + + + + + + + + + + + + ... + + + + which implements + + .. math:: + M_{\rm spatial}(p|E) = \frac{1}{N} \sum_{i=0}^{N-1} M_{\rm spatial}^{(i)}(p|E) + + where :math:`M_{\rm spatial}^{(i)}(p|E)` is any spatial model component + (including another composite model), and :math:`N` is the number of + model components that are combined. diff --git a/doc/source/users/user_manual/models_spatial_bgd.rst b/doc/source/users/user_manual/models_spatial_bgd.rst deleted file mode 100644 index 7381765..0000000 --- a/doc/source/users/user_manual/models_spatial_bgd.rst +++ /dev/null @@ -1,307 +0,0 @@ -.. _um_models_spatial_bgd: - -Spatial background model components ------------------------------------ - -The following sections present the spatial model components that are available -in ctools for instrumental background modelling for Imaging Air Cherenkov -Telescopes (IACTs) such as H.E.S.S., VERITAS, MAGIC and CTA. - - -General IACT background -^^^^^^^^^^^^^^^^^^^^^^^ - - The general IACT background model is factorised in a spatial and spectral - component and has the type ``CTABackground``. It has the following XML - structure: - - .. code-block:: xml - - - - ... - - - ... - - - - .. note:: - Please speficy the ``instrument`` label in the XML file that corresponds - to the ``instrument`` label of the data. Otherwise the model will not be used - for your data. Valid ``instrument`` labels are ``HESS``, ``VERITAS``, - ``MAGIC`` and ``CTA``. - - The following sections describe the spatial model components that are - available. - - -Gaussian -~~~~~~~~ - - The ``Gaussian`` model describes a 2D Gaussian shape in offset angle squared - - .. code-block:: xml - - - - - - - ... - - - - and implements - - .. math:: - M_{\rm spatial}(\theta) = \exp \left(-\frac{1}{2} - \left( \frac{\theta^2}{\sigma} \right)^2 \right) - - where - - * :math:`\sigma` = ``Sigma`` (degrees) - - and - - .. math:: - \theta = \sqrt{\mathrm{DETX} \times \mathrm{DETX} + \mathrm{DETY} \times\mathrm{DETY}} - - with :math:`\mathrm{DETX}` and :math:`\mathrm{DETY}` being the detector - coordinates in the nominal system. - - -Profile -~~~~~~~ - - The ``Profile`` model describes a radial profile - - .. code-block:: xml - - - - - - - - - ... - - - - and implements - - .. math:: - M_{\rm spatial}(\theta) = (1 + (\theta/c_0)^{c_1})^{-c_2/c_1} - - where - - * :math:`c_0` = ``Width`` (degrees) - * :math:`c_1` = ``Core`` - * :math:`c_2` = ``Tail`` - - -Polynom -~~~~~~~ - - The ``Polynom`` model describes a polynomial with an arbitrary number of - coefficients - - .. code-block:: xml - - - - - - - - ... - - - ... - - - - and implements - - .. math:: - M_{\rm spatial}(\theta) = \sum_{i=0}^m c_i \theta^i - - where - - * :math:`c_0` = ``Coeff0`` - * :math:`c_1` = ``Coeff1`` - * :math:`c_2` = ``Coeff2`` - * :math:`c_3` = ``Coeff3`` - * ... - - -Gradient -~~~~~~~~ - - The ``Gradient`` model describes a bilinear gradient over the field of - view - - .. code-block:: xml - - - - - - - - ... - - - - and implements - - .. math:: - M_{\rm spatial}(\mathrm{DETX},\mathrm{DETY}) = - 1 + \nabla_\mathrm{x} \mathrm{DETX} + \nabla_\mathrm{y} \mathrm{DETY} - - where - - * :math:`\nabla_\mathrm{x}` = ``Grad_DETX`` (per degree) - * :math:`\nabla_\mathrm{y}` = ``Grad_DETY`` (per degree) - - - -Multiplicative -~~~~~~~~~~~~~~ - - The ``Multiplicative`` model describes a multiplication of spatial models - - .. code-block:: xml - - - - - ... - - - ... - - ... - - - ... - - - - and implements - - .. math:: - M_{\rm spatial}(\mathrm{DETX},\mathrm{DETY}) = - \prod_{i=0}^{N-1} M^{(i)}_{\rm spatial}(\mathrm{DETX},\mathrm{DETY}) - - where :math:`M^{(i)}_{\rm spatial}(\mathrm{DETX},\mathrm{DETY})` is any - spatial model component, including another multiplicative model, and - :math:`N` is the number of model components that are multiplied. - For example, the default model for a H.E.S.S. data analysis is specified - by - - .. code-block:: xml - - - - - - - - - - - - - ... - - - - -Radial acceptance background -^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - For legacy reasons, there exists a class of radially symmetric background - models of the type ``RadialAcceptance`` with the following XML structure: - - .. code-block:: xml - - - - ... - - - ... - - - - These models require a ```` tag as the spatial component and - accept all spatial model types that take the offset angle :math:`\theta` - as variable, such as ``Gaussian``, ``Profile`` and ``Polynom``. The use - of the radial acceptance model is deprecated, and the ``CTABackground`` - model should be used instead. - - -CTA IRF background -^^^^^^^^^^^^^^^^^^ - - The :ref:`Instrument Response Functions (IRFs) ` contain a template - that predicts the background rate as function of position in the field of view - and measured energy in units of - :math:`{\rm events} \, {\rm s}^{-1} {\rm MeV}^{-1} {\rm sr}^{-1}`. This template - can be used by specifying a model of type ``CTAIrfBackground``. No spatial component - will be specified explicitly since the spatial (and spectral) information is - already contained in the template. The model will be multiplied by a spectral law. - - .. code-block:: xml - - - - ... - - - - If the observation is an On/Off observation, do not forget to switch the instrument - to ``CTAOnOff``: - - .. code-block:: xml - - - - ... - - - - -CTA effective area background -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - - Instead of using the background template the effective area for gamma rays can - also be used to model the instrumental background. Note that in this case the - effective area has to be scaled to a reasonable background rate. - - .. code-block:: xml - - - - ... - - - - -CTA cube background -^^^^^^^^^^^^^^^^^^^ - - For a stacked analysis, the background rate is predicted by a so called - background cube. The background cube is used by specifying a model of type - ``CTACubeBackground``. Similar to the ``CTAIrfBackground`` model, the - background cube is multplied by a spectral model. - - .. code-block:: xml - - - - ... - - diff --git a/doc/source/users/user_manual/models_spatial_src.rst b/doc/source/users/user_manual/models_spatial_src.rst deleted file mode 100644 index 2964a9f..0000000 --- a/doc/source/users/user_manual/models_spatial_src.rst +++ /dev/null @@ -1,407 +0,0 @@ -.. _um_models_spatial_src: - -Spatial source model components -------------------------------- - -The following sections present the spatial model components that are available -in ctools for gamma-ray sources. - -.. note:: - Except of the ``DiffuseMapCube`` model, all spatial models are normalized - so that when integrated over the sphere the result is unity. For clarify, - the spatial normalisation is omitted in the formulae below. - -Point source -^^^^^^^^^^^^ - - The ``PointSource`` model describes a point source - - .. code-block:: xml - - - - - - - - ... - - - - where - - * ``RA`` is the Right Ascension (degrees) - * ``DEC`` is the Declination (degrees) - - The ``RA`` and ``DEC`` parameters can be remplaced by ``GLON`` and ``GLAT`` - for Galactic coordinates - - .. code-block:: xml - - - - - - - - ... - - - - where - - * ``GLON`` is the Galactic longitude (degrees) - * ``GLAT`` is the Galactic latitude (degrees) - - .. note:: - For compatibility with the Fermi/LAT ScienceTools the model type - ``PointSource`` can be replaced by ``SkyDirFunction``. - - -Radial source -^^^^^^^^^^^^^ - -RadialDisk -~~~~~~~~~~ - - The ``RadialDisk`` model describes a uniform intensity distribution within - a given radius - - .. code-block:: xml - - - - - - - - - ... - - - - where - - * ``RA`` is the Right Ascension (degrees) - * ``DEC`` is the Declination (degrees) - * ``Radius`` is the disk radius (degrees) - -RadialGaussian -~~~~~~~~~~~~~~ - - The ``RadialGaussian`` model describes a Gaussian intensity distribution - - .. code-block:: xml - - - - - - - - - ... - - - - and implements - - .. math:: - M_{\rm spatial}(\theta) = \frac{1}{2 \pi \sigma^2} \exp - \left(-\frac{1}{2}\frac{\theta^2}{\sigma^2} \right), - - where - - * ``RA`` is the Right Ascension (degrees) - * ``DEC`` is the Declination (degrees) - * :math:`\sigma` = ``Sigma`` (degrees) - -RadialShell -~~~~~~~~~~~ - - The ``RadialShell`` model describes a spherical shell projected on the sky - - .. code-block:: xml - - - - - - - - - - ... - - - - and implements - - .. math:: - M_{\rm spatial}(\theta) = n_0 \left \{ - \begin{array}{l l} - \displaystyle - \sqrt{ \theta_{\rm out}^2 - \theta^2 } - \sqrt{ \theta_{\rm in}^2 - \theta^2 } - & \mbox{if $\theta \le \theta_{\rm in}$} \\ - \\ - \displaystyle - \sqrt{ \theta_{\rm out}^2 - \theta^2 } - & \mbox{if $\theta_{\rm in} < \theta \le \theta_{\rm out}$} \\ - \\ - \displaystyle - 0 & \mbox{if $\theta > \theta_{\rm out}$} - \end{array} - \right . - - where - - * ``RA`` is the Right Ascension (degrees) - * ``DEC`` is the Declination (degrees) - * :math:`\theta_{\rm out}` = ``Radius`` + ``Width`` (degrees) - * :math:`\theta_{\rm in}` = ``Radius`` (degrees) - - .. note:: - For all radial source models the ``RA`` and ``DEC`` parameters can be - remplaced by ``GLON`` and ``GLAT`` for Galactic coordinates. - - -Elliptical source -^^^^^^^^^^^^^^^^^ - -EllipticalDisk -~~~~~~~~~~~~~~ - - The ``EllipticalDisk`` model describes a uniform intensity distribution within - an elliptical circumference: - - .. code-block:: xml - - - - - - - - - - - ... - - - - where - - * ``RA`` is the Right Ascension (degrees) - * ``DEC`` is the Declination (degrees) - * ``PA`` is the position angle, counted counterclockwise from North (degrees) - * ``MinorRadius`` is the minor radius of the ellipse (degrees) - * ``MajorRadius`` is the major radius of the ellipse (degrees) - -EllipticalGaussian -~~~~~~~~~~~~~~~~~~ - - The ``EllipticalGaussian`` model describes a Gaussian intensity distribution - - .. code-block:: xml - - - - - - - - - - - ... - - - - and implements - - .. math:: - M_{\rm spatial}(\theta, \phi) = \exp \left( -\frac{\theta^2}{2 r_\mathrm{eff}^2} \right), - - with - - .. math:: - r_\mathrm{eff} = \frac{ab} {\sqrt{\left( a \sin (\phi - \phi_0) \right)^2 + - \sqrt{\left( b \cos (\phi - \phi_0) \right)^2}}} - - where - - * ``RA`` is the Right Ascension (degrees) - * ``DEC`` is the Declination (degrees) - * ``PA`` is the position angle, counted counterclockwise from North (degrees) - * :math:`a` = ``MinorRadius`` (degrees) - * :math:`b` = ``MajorRadius`` (degrees) - * :math:`\phi_0` is the position angle of the ellipse, counted counterclockwise - from North - * :math:`\phi` is the azimuth angle with respect to North. - - .. note:: - For all elliptical source models the ``RA`` and ``DEC`` parameters can be - remplaced by ``GLON`` and ``GLAT`` for Galactic coordinates. - - -Diffuse source -^^^^^^^^^^^^^^ - -DiffuseIsotropic -~~~~~~~~~~~~~~~~ - - The ``DiffuseIsotropic`` model describes an isotropic intensity distribution - - .. code-block:: xml - - - - - - - ... - - - - where - - * ``Value`` is isotropic intensity - - .. note:: - For compatibility with the Fermi/LAT ScienceTools the model type - ``DiffuseIsotropic`` can be replaced by ``ConstantValue``. - -DiffuseMap -~~~~~~~~~~ - - The ``DiffuseMap`` model describes an arbitrary intensity distribution in - form of a sky map - - .. code-block:: xml - - - - - - - ... - - - - where - - * ``Normalization`` is a normalization value - - and the ``file`` attribute specifies a sky map FITS file name. If a file name - without path is specified it is assumed that the FITS file resides in the same - directory as the model definition XML file. - - .. note:: - For compatibility with the Fermi/LAT ScienceTools the model type - ``DiffuseMap`` can be replaced by ``SpatialMap`` and the parameter - ``Normalization`` can be replaced by ``Prefactor``. - - .. note:: - By default, the diffuse map is normalised so that - - .. math:: - \int_{\Omega} M_{\rm spatial}(p|E) \, d\Omega = 1 - - which means that the units of the spatial model component are - :math:`[M_{\rm spatial}] = {\rm sr}^{-1}`. - To avoid the normalisation you may add the ``normalize="0"`` attribute - to the spatial model tag. - - .. code-block:: xml - - - - - - - ... - - - - In that case, generally - - .. math:: - \int_{\Omega} M_{\rm spatial}(p|E) \, d\Omega \neq 1 - - and the spectral component cannot be directly interpreted as a physical - source intensity. - - .. _um_models_spatial_src_diffuse_cube: - -DiffuseMapCube -~~~~~~~~~~~~~~ - - The ``DiffuseMapCube`` model describes an arbitrary energy-dependent intensity - distribution in form of a map cube - - .. code-block:: xml - - - - - - - ... - - - - where - - * ``Normalization`` is a normalization value - - Note that the map cube is not normalised to unit, hence generally - - .. math:: - \int_{\Omega} M_{\rm spatial}(p|E) \, d\Omega \neq 1 - - To compute the flux in a given energy band for a ``DiffuseMapCube`` model - you have to integrated both the spatial and spectral components, i.e. - - .. math:: - \Phi = \int_{\Omega} \int_{E} M_{\rm spatial}(p|E) \times - M_{\rm spectral}(E)\, d\Omega \, dE - - .. note:: - For compatibility with the Fermi/LAT ScienceTools the model type - ``DiffuseMapCube`` can be replaced by ``MapCubeFunction`` and the parameter - ``Normalization`` can be replaced by ``Value``. - - -Composite model -^^^^^^^^^^^^^^^ - - The ``Composite`` model implements a composite model that is the sum of an - arbitrary number of spatial models - - .. code-block:: xml - - - - - - - - - - - - - - - ... - - - - which implements - - .. math:: - M_{\rm spatial}(p|E) = \frac{1}{N} \sum_{i=0}^{N-1} M_{\rm spatial}^{(i)}(p|E) - - where :math:`M_{\rm spatial}^{(i)}(p|E)` is any spatial model component - (including another composite model), and :math:`N` is the number of - model components that are combined. diff --git a/doc/source/users/user_manual/models_spectral.rst b/doc/source/users/user_manual/models_spectral.rst index ce52015..0a0608c 100644 --- a/doc/source/users/user_manual/models_spectral.rst +++ b/doc/source/users/user_manual/models_spectral.rst @@ -86,10 +86,10 @@ Power law .. code-block:: xml - - - - + + + + This spectral model component implements the power law function @@ -202,11 +202,11 @@ Super exponentially cut-off power law .. code-block:: xml - - - - - + + + + + @@ -381,7 +381,7 @@ File function .. code-block:: xml - + This spectral model component implements an arbitrary function @@ -444,6 +444,119 @@ Node function ordering. +Table model +^^^^^^^^^^^ + + An arbitrary spectral model defined on a M-dimensional grid of parameter + values. The spectrum is computed using M-dimensional linear interpolation. + The model definition is provided by a FITS file that follows the + `HEASARC OGIP standard `_. + + The structure of the table model FITS file is shown below. The FITS file + contains three binary table extensions after an empty image extension. + + .. _fig_model_table: + + .. figure:: model_table.png + :align: center + :width: 100% + + *Structure of table model FITS file* + + The ``PARAMETERS`` extension contains the definition of the model parameters. + Each row defines one model parameter. Each model parameter is defined by a + unique ``NAME``. The ``METHOD`` column indicates whether the model should be + interpolated linarly (value ``0``) or logarithmically (value ``1``). + So far only linear interpolation is supported, hence the field is ignored. + The ``INITIAL`` column indicates the initial parameter value, if the value in + the ``DELTA`` column is negative the parameter will be fixed, otherwise it will + be fitted. The ``MINIMUM`` and ``MAXIMUM`` columns indicate the range of values + for a given parameter, the ``BOTTOM`` and ``TOP`` columns are ignored. + The``NUMBVALS`` column indicates the number of parameter values for + which the table model was computed, the ``VALUE`` column indicates the + specific parameter values. + + In the example below there are two parameters named ``Index`` and ``Cutoff``, + and spectra were computed for 100 index values and 50 cutoff values, hence + a total of 5000 spectra are stored in the table model. + + .. _fig_model_table_parameters: + + .. figure:: model_table_parameters.png + :align: center + :width: 100% + + *Table model parameters extension* + + The ``ENERGIES`` extension contains the energy boundaries for the spectra in + the usual OGIP format: + + .. _fig_model_table_energies: + + .. figure:: model_table_energies.png + :align: center + :width: 40% + + *Energy boundaries extension* + + The ``SPECTRA`` extension contains the spectra of the table model. It consists + of two vector columns. The ``PARAMVAL`` column provides the parameter values + for which the spectrum was computed. Since there are two parameters in the + example the vector column has two entries. The ``INTPSPEC`` column provides + the spectrum :math:`\frac{dN(p)}{dE}` for the specific parameters. Since there + are 200 energy bins in this example the vector column has 200 entries. + + .. _fig_model_table_spectra: + + .. figure:: model_table_spectra.png + :align: center + :width: 40% + + *Spectra extension* + + + The model is defined using: + + .. math:: + \frac{dN}{dE} = N_0 \left. \frac{dN(p)}{dE} \right\rvert_{\rm file} + + where the parameters in the XML definition have the following mappings: + + * :math:`N_0` = ``Normalization`` + * :math:`p` = M model parameters (e.g. ``Index``, ``Cutoff``) + + The XML format for specifying a table model is: + + .. code-block:: xml + + + + + + .. warning:: + If the file name is given without a path it is expected that the file + resides in the same directory than the XML file. + If the file resides in a different directory, an absolute path name should + be specified. + Any environment variable present in the path name will be expanded. + + Note that the default parameters of the table model are provided in the FITS + file, according to the + `HEASARC OGIP standard `_. + However, table model parameters may also be specified in the XML file, and + these parameters will then overwrite the parameters in the FITS file. For + example, for a 2-dimensional table model with an ``Index`` and a ``Cutoff`` + parameter, the XML file may look like + + .. code-block:: xml + + + + + + + + Composite model ^^^^^^^^^^^^^^^ @@ -451,14 +564,14 @@ Composite model - + - + - + - + @@ -510,7 +623,7 @@ Exponential model - + @@ -518,9 +631,12 @@ Exponential model spectral model and computes .. math:: - M_{\rm spectral}(E) = \exp \left( M_{\rm spectral}(E) \right) + M_{\rm spectral}(E) = \exp \left( \alpha M_{\rm spectral}(E) \right) + + where - where :math:`M_{\rm spectral}(E)` is any spectral model component. + * :math:`M_{\rm spectral}(E)` is any spectral model component + * :math:`\alpha` = ``Normalization`` The model can be used to describe a spectrum with EBL absorption based on a tabulated model of opacity as a function of photon energy. The corresponding @@ -536,7 +652,7 @@ Exponential model - + diff --git a/doc/source/users/user_manual/models_temporal.rst b/doc/source/users/user_manual/models_temporal.rst index 4c629cb..582b95f 100644 --- a/doc/source/users/user_manual/models_temporal.rst +++ b/doc/source/users/user_manual/models_temporal.rst @@ -7,7 +7,7 @@ The following sections present the temporal model components that are available in ctools. .. warning:: - Recall that the model is factorised according to + Recall that the source model is factorised according to .. math:: M(p,E,t) = M_{\rm spatial}(p|E) \times M_{\rm spectral}(E) \times M_{\rm temporal}(t) diff --git a/doc/source/users/user_manual/overview.jpg b/doc/source/users/user_manual/overview.jpg index a3c8e41..67396a7 100644 Binary files a/doc/source/users/user_manual/overview.jpg and b/doc/source/users/user_manual/overview.jpg differ diff --git a/doc/source/users/user_manual/overview.rst b/doc/source/users/user_manual/overview.rst index 7fa0424..13c0793 100755 --- a/doc/source/users/user_manual/overview.rst +++ b/doc/source/users/user_manual/overview.rst @@ -11,7 +11,7 @@ executables, and tools starting with the letters ``cs`` are implemented as Python scripts. .. figure:: overview.jpg - :width: 60% + :width: 65% :align: center The scripts :ref:`csiactdata`, :ref:`csiactobs`, :ref:`csfindobs` and @@ -46,6 +46,7 @@ tools. :ref:`csbkgmodel` prepares a standard background model for the analysis of IACT data that was validated on H.E.S.S. data. :ref:`csmodelinfo` inspects any given :ref:`model definition file `, +:ref:`csmodelselect` selects sources from a :ref:`model definition file `, :ref:`csmodelmerge` merges several :ref:`model definition files ` into a single one, and :ref:`csmodelsois` extracts sources of interest from a :ref:`model definition file ` and replaces the remaining sources @@ -54,6 +55,7 @@ by a diffuse map cube. :ref:`ctskymap` generates sky maps from the data and :ref:`cssrcdetect` detects sources in the sky map and writes them into a :ref:`model definition file `. +:ref:`csscs` spatially separates source components based on their spectra. :ref:`csspec` generates a spectrum and :ref:`ctbutterfly` computes a butterfly diagram for a given gamma-ray source. -- libgit2 0.21.4