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 --- /dev/null +++ b/doc/source/users/user_manual/model_table.png 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 --- /dev/null +++ b/doc/source/users/user_manual/model_table_energies.png 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 --- /dev/null +++ b/doc/source/users/user_manual/model_table_parameters.png 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 --- /dev/null +++ b/doc/source/users/user_manual/model_table_spectra.png 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_spatial_bgd.rst b/doc/source/users/user_manual/models_bgd_iact.rst index 7381765..7cb04c9 100644 --- a/doc/source/users/user_manual/models_spatial_bgd.rst +++ b/doc/source/users/user_manual/models_bgd_iact.rst @@ -1,11 +1,30 @@ -.. _um_models_spatial_bgd: +.. _um_models_bgd_iact: -Spatial background model components ------------------------------------ +IACT background models +---------------------- -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. +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 @@ -26,11 +45,38 @@ General IACT background - .. 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``. + .. 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. @@ -238,13 +284,15 @@ Radial acceptance background 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. + 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. -CTA IRF background -^^^^^^^^^^^^^^^^^^ +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 @@ -252,7 +300,10 @@ CTA IRF background :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. + 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 @@ -274,12 +325,13 @@ CTA IRF background -CTA effective area background -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +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. + effective area has to be scaled to a reasonable background rate by selecting + appropriate values for the spectral model component. .. code-block:: xml @@ -290,13 +342,18 @@ CTA effective area background -CTA cube background -^^^^^^^^^^^^^^^^^^^ +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. - 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 + The background cube model is used by specifying a model of type ``CTACubeBackground``. Similar to the ``CTAIrfBackground`` model, the - background cube is multplied by a spectral model. + 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_source.rst index 5ee3ae6..9a7bc39 100644 --- a/doc/source/users/user_manual/models_implementation.rst +++ b/doc/source/users/user_manual/models_source.rst @@ -1,22 +1,23 @@ -.. _um_models_implementation: +.. _um_models_source: -Implementation --------------- +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. -Each model is factorised into -a spectral (tag ````), -a spatial (tags ```` or ````), and -a temporal component (tag ````). +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 \,\, cm^{-2} s^{-1} MeV^{-1} sr^{-1}`. +: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. diff --git a/doc/source/users/user_manual/models_spatial_src.rst b/doc/source/users/user_manual/models_spatial.rst index 2964a9f..8db16c7 100644 --- a/doc/source/users/user_manual/models_spatial_src.rst +++ b/doc/source/users/user_manual/models_spatial.rst @@ -1,4 +1,4 @@ -.. _um_models_spatial_src: +.. _um_models_spatial: Spatial source model components ------------------------------- @@ -7,9 +7,8 @@ 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. + Except of the ``DiffuseMapCube`` model, all spatial models are normalised + so that when integrated over the sphere the result is unity. Point source ^^^^^^^^^^^^ @@ -33,8 +32,8 @@ Point source * ``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 + Instead of ``RA`` and ``DEC`` one may use ``GLON`` and ``GLAT`` to give the + position in Galactic coordinates .. code-block:: xml @@ -54,6 +53,14 @@ Point source * ``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``. @@ -82,10 +89,43 @@ RadialDisk where - * ``RA`` is the Right Ascension (degrees) - * ``DEC`` is the Declination (degrees) + * ``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 ~~~~~~~~~~~~~~ @@ -112,8 +152,8 @@ RadialGaussian where - * ``RA`` is the Right Ascension (degrees) - * ``DEC`` is the Declination (degrees) + * ``RA`` is the Right Ascension of the Gaussian centre (degrees) + * ``DEC`` is the Declination of the Gaussian centre (degrees) * :math:`\sigma` = ``Sigma`` (degrees) RadialShell @@ -155,15 +195,11 @@ RadialShell where - * ``RA`` is the Right Ascension (degrees) - * ``DEC`` is the Declination (degrees) + * ``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) - .. note:: - For all radial source models the ``RA`` and ``DEC`` parameters can be - remplaced by ``GLON`` and ``GLAT`` for Galactic coordinates. - Elliptical source ^^^^^^^^^^^^^^^^^ @@ -239,10 +275,6 @@ EllipticalGaussian 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 ^^^^^^^^^^^^^^ 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 --- a/doc/source/users/user_manual/overview.jpg +++ b/doc/source/users/user_manual/overview.jpg 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.